Zephr User Guide

Browser-Side HTML Features without the Zephr CDN

96 views 0

Zephr gives you the ability to run HTML Features rule in the Zephr Site CDN, or in Browser, allowing you to integrate Zephr in a way that makes sense for your existing technology stack.

This guide discusses working with Zephr In-Browser, without using the Zephr CDN. For this example, your development team will deploy a JavaScript library into your site pages.

In-Browser HTML Features

Zephr uses a JavaScript library, available via NPM, to enact transformations client-side.

Typically, the JavaScript is deployed automatically by the Zephr CDN, however, if you’re not using the Zephr CDN, the JavaScript will need to be deployed into site pages by your development team.

Prerequisites

In order to use client-side rules, you must, at least, set up a Zephr organisation with one or more sites. A site is required even though the CDN is not being used, as it will act as the domain for all requests to the Zephr Public API.

To create a site, follow our Sites Guide. Note: when creating a site you will be forced to add an Origin. If you were using Zephr to deliver content this would be the upstream CMS. If possible, you should still configure this to point to the origin or live site, although any base URL will do.

In order to use the Decision API (which will be called by the Zephr JavaScript library) CORS allowed origins must be configured. This is a comma delimited list of all of the public base URLs from which the API will be called. For example, “https://mysite.com,https://www.mysite.com”.

Take note of the default “live” domain, from the top of the page, as it will be required to initialize the Zephr JavaScript.

To test that the site has been created correctly, go to the default domain + “/blaize/health-check”; for example, https://v4-demo-chris-my-site.cdn.demo.zephr.com/blaize/health-check. You should see a JSON object with the message “ok”. Note that it may take up to 30 seconds for the site to come online.

Installing a Standalone Website

Note: Typically, this step is not required, because, as previously mentioned, the Zephr CDN will deploy the JavaScript. If you were using the CDN you would need to select “Inject Browser Feature Script Tags” in the site configuration. This guide has more details.

The JavaScript can be included on-site in one of two ways. Either using the script hosted by Zephr or by using NPM to import the module into your own project.

Using Zephr Hosted JS

Include the following HTML in your document.

<HTML>
    <head>
        <script src="https://assets.zephr.com/zephr-browser/1.0.1/zephr-browser.umd.js"></script>
        ...

The JavaScript will need to be initialized with a line of code, so you can include the script in the document head or anywhere else in the document. You may also use a tag manager to deploy the script.

To execute the Zephr you should use code similar to:

document.addEventListener('DOMContentLoaded', (event) => {
 zephrBrowser.run(baseUrl);
});

In this case, the variable baseUrl should be set to the default site URL from the site configuration stage, e.g. https://v4-demo-chris-my-site.cdn.demo.zephr.com

Using NPM

To install the Zephr module run:

$ npm install --save @zephr/browser

The tool is packaged as both UMD and ES6 modules. Once imported, the zephrBrowser object can be used as per the hosted script:

import * as zephrBrowser from 'zephr-browser.modern.js';

document.addEventListener('DOMContentLoaded', (event) => {
 zephrBrowser.run(baseUrl);
});

Verify installation

To verify that the script is installed correctly, load up a page including the Zephr JavaScript and use your browser’s inspector to check that an AJAX request is made to the Zephr Public API to retrieve (client-side) features:

Retrieving client-site features

The library will also log out the features that have been configured and if they were found on page:

Logging Features

Example page

This following is a full example of a page that will be loosely referred to in the upcoming instructions:

<HTML>
    <head>
        <script src="https://assets.zephr.com/zephr-browser/1.0.1/zephr-browser.umd.js"></script>
        <script>
          let baseUrl = 'https://v4-demo-chris-my-site.cdn.demo.zephr.com';
          document.addEventListener('DOMContentLoaded', (event) => {
             zephrBrowser.run(baseUrl);
          });
       </script>
    </head>
    <body>
       <h1>Zephr JS test</h1>
       <div class="private">
          Don't look here!
       </div>
    </body>
</html>

Building an In-Browser Rule

Once the JavaScript has been added to a site, you can configure a feature rule. To do this go to Products > Features in the Zephr console, then click Add a Feature:

Give the Feature a Title and choose HTML as the type of integration.

Click Continue to create the Feature.

In any brand new feature, you will initially see the Developer Interface. This is where the type of integration can be configured. Whether a feature rule is executed server-side (edge-side) or in-browser is dictated by the Where To Run option. For this example, select Run In Browser.

Because you are not using the Zephr CDN, the Site Integration section will only allow CSS Selector; enter a CSS Selector for the feature below.

Developer Console - Run In Browser

Click Update & Lock to continue.

If you return to an existing feature the developer interface will be closed by default. You can find it at the bottom of the page. Click anywhere in the border to re-open it.

Now, create a basic rule to test the integration. To do this ensure you are in the Anonymous user journey – which you will be by default – and click Outcomes > Add Outcome.

Name your new Outcome; click Add a Component, then Add Custom Component Block. Enter a title and a recognizable message.

Custom Component Block Example

Click Save, then press Save again to save your Outcome. You should now have a new outcome in the palette, with the title you just chose.

Drag your new outcome onto the canvas and connect it to the Page View node.

At the bottom of the page click on the small arrow next to Save and select Save and Publish.

Testing the rule

You can now return to the test page you created in the previous section and refresh. The console logging should now be updated:

Testing an In-Browser Rule

Augmenting Decision Data

With this integration, you also have the ability to add a custom data argument in the run command, which can then be used within a Zephr Feature to determine a customer’s journey.

The example below looks at whether a user has Ad Block running on their browser. In this case, the user does.

document.addEventListener('DOMContentLoaded', (event) => {
zephrBrowser.run({
  cdnApi: 'https://{zephr-cdn-url}',
  customData: {
    hasAdBlock: true
  }
});
        });

With this information being passed to the custom object, you can use the Custom Data Node within your Zephr Feature Builder to make a decision based upon the information.

To do this, navigate to the relevant Feature, and select Content > Custom Data from the Rules Builder Palette. Drag this onto your canvas, and a modal will appear. Select the Property Name of the object you wish to query, then add a Condition and Value to search for.

In the case of the above example, we would be looking for hasAdBlock | contains | true

Browser-Side Features - Custom Data

Once complete, click Save. This will form a branch in your rule to create journeys for users who are using Ad Block, and those who aren’t, respectively.

Common Custom Data Objects

Our clients often wish to make decisions based on whether a user is browsing in an Incognito Window, as well as whether they are running Ad Block. Using the below examples, you can pass this information into a custom data object for use in a Browser-Side rule:

Limitations

The biggest limitation with any JavaScript-based solution is that it relies upon JavaScript and the site visitor to allow the execution to run honestly. A sensible strategy for high-value content is to load some or all of the content after Zephr has executed, to prevent circumvention by disabling JavaScript. Alternatively, you can use the Zephr CDN – which is far more secure.

An additional limitation that comes from directly including the JavaScript in the site (and not using the JavaScript in combination with the CDN) is that Zephr forms with not work, as they expect a same-origin path for Zephr API calls. This will not be an issue if you are using a third-party identity platform, as Zephr forms will not be in use.