Zephr User Guide

Browser-Side HTML Features without the Zephr CDN

358 views 0

You can integrate Zephr with your existing technology stack using an HTML Features rule in the browser.

Before You Start

Before you use in-browser HTML features, make sure that you:

  • Deploy the JavaScript library on your site pages

    Notes:

    1. You must use the version linked above to ensure that you deploy the latest version of the Javascript library
    2. To reduce load time, you must run the JavaScript library as soon as possible on your page. Zephr recommends that you run it as soon as the DOMContentLoaded event is triggered
    3. If you use lazy loading, the JavaScript library must run every time content is loaded

    The JavaScript library is available through NPM. Zephr uses the library to handle Zephr decisions in the browser and run client-side rules.

  • Set up a Zephr organisation with one or more sites

    At least one site is required even if not using the CDN, as it acts as the domain for all requests to the Zephr Public API.

    For further information on creating a site, see Sites.

    Note: When creating a site, you must add an Origin. If you were using Zephr to deliver content, this would be the upstream CMS. Zephr recommends that you configure this to point to the origin of the live site; although you can use any base URL.

  • If the Decision API endpoint is explicitly configured to cdnAPI in the JavaScript run() method, configure CORS allowed origins

    CORS allowed origins let you use the Decision API, which is called by the Zephr JavaScript library. The origins are configured using a comma-delimited list of the public base URLs from which the API is called. For example, “https://mysite.com,https://www.mysite.com”. For further information on CORS configuration, see Sites.

    If the cdnAPI endpoint is not explicitly configured, the Decision API endpoint is the origin URL for the site and you do not need to configure CORS.

  • Note the default live domain

    You can find the default live domain at the top of the page. It is used when the cdnAPI endpoint is not explicitly specified to initialise the Zephr JavaScript.

  • Test the site

    Navigate to the default domain and append /blaize/health-check; for example, https://v4-demo-chris-my-site.cdn.demo.zephr.com/blaize/health-check. If the site is correctly set up, you see a JSON object with the message ok.

Note: It can take up to 30 seconds for the site to be available online.

Configuration

You must configure the JavaScript run method, and the endpoint for the domain from which you run the script.

JavaScript

You can use the following main arguments with the JavaScript run method:

  • cdnApi [String]

    This is the Zephr CDN API base URL. For further information, see CDN API Endpoint below

  • jwt [String]

    This is the JSON Web Token (JWT) used for authentication

  • customData [Object]

    This allows you to pass additional string key/value pairs for use in decisions. These define the parameter that you can use when building custom decisions

    For example, you could configure the following types of customData points:

    • pageType. For example, this could define a page as an article, slideshow, or homepage
    • contentLabel. For example, this could define the type of information on the page as news, opinion, or column
    • pageIsSponsored. For example, this could indicate whether the content is sponsored using true or false values

Note: It can take a while for the page to load to your origin CMS, depending on the number of third-party scripts. If this is causing issues, you can configure cache rules to minimise the delay. For further information on configuring cache rules, see Sites.

JavaScript Flow

CDN API Endpoint

The client browser uses the CDN API endpoint to run Zephr rules. The way in which you configure this endpoint defines the domain from which the script runs; for example, Staging or Production.

The endpoint can be configured in the following ways:

  • Preserve the explicit cdnAPI endpoint
  • Reverse proxy

Preserve the Explicit cdnAPI Endpoint

You can set the endpoint to a pre-determined Zephr CDN. All GET and POST calls must be forwarded to /blaize* and /zephr* API endpoints.

This approach ensures that the browser runs the correct version for the site; for example, staging or production.

To preserve the explicit cdnAPI endpoint, you must set a subdomain. A Canonical Name (CNAME) record points to the Zephr CDN API endpoint from this subdomain. You must use the subdomain to ensure that the cookie is a first-party cookie.

For example, if you set a subdomain using the format <subdomain>.<site>.com, the CNAME record points to <subdomain>.<site>.cdn.zephr.com. This is defined in the JavaScript run() method as follows:

<subdomain>.<site>.com canonical name = <subdomain>.<site>.cdn.zephr.com

Note: You must configure separate subdomains for each site in the same format. For further information, see Sites.

Reverse Proxy

To use reverse proxy, you must remove the explicit cdnAPI endpoint configuration from the JavaScript run() method. This means that the API calls use the origin URL.

The resulting feature decision URLs are constructed as follows:

  • Rule retrieval: https://<site>/zephr/feature
  • Rule decisions and outcome retrieval: https://<site>>/zephr/feature-decisions

You must configure a rule on your server to change the origin domain to the actual Zephr endpoint and preserve the path. The proxy rule must include /blaize* and /zephr* URLs. Both GET and POST methods must be forwarded.

Note: This method allows you to deploy multiple sites on the same web service distribution without support from your technical team each time a new site is deployed.

For further information on reverse proxy, including sequence diagrams, see Using Zephr Functionality Through Third-Party CDNs.

Install a Standalone Website

If using the Zephr CDN, this step is not required, as the Zephr CDN deploys the JavaScript. When using the CDN, you simply select Inject Browser Feature Script Tags in the site configuration. For information on using the Zephr CDN, see Browser-Side HTML Features with the Zephr CDN.

Note: If using this approach, you cannot use any of the optional parameters in the JavaScript run() method.

The JavaScript can be included on-site using either of the following methods:

  • Run the script hosted by Zephr
  • Import the module to your project using NPM

Run the Script

To run the script hosted by Zephr, Check the latest version number.

The following HTML is automatically injected to your document by a script that is loaded from the CDN:

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

You must add a line of code to initialise the JavaScript, so you can include the script. This code can be added anywhere in the document, typically in the document head. You can also use a tag manager to deploy the script.

After you deploy the script, you can view information on decisions and meters from Zephr under the window.Zephr object.

Import Module Using NPM

To install the Zephr module, run the following command in a terminal:

npm install --save @zephr/browser

The tool is packaged as both UMD and ES6 modules.

You must import the zephrBrowser object and run the script as follows:

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

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

In the code above, set the baseUrl variable to the default site URL from the site configuration stage; for example, https://v4-demo-chris-my-site.cdn.demo.zephr.com.

Verify installation

To verify that the script installed correctly, complete the following steps:

  1. Load a page that includes the Zephr JavaScript
  2. Use your browser’s inspector to check that an AJAX request is made to the Zephr Public API to retrieve (client-side) features, as illustrated below:

    Retrieving client-site features

  3. The library also logs the configured features that were found on page, as illustrated below:

    Logging Features

    Example Page

    The following example page is referred to in the upcoming instructions.

    You might need to change the version in the following example to match the latest version number.

    The example page is as follows:

    <HTML>
        <head>
            <script src="https://assets.zephr.com/zephr-browser/1.3.9/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

    When you have added the JavaScript to a site, you can configure a feature rule.

    To configure a feature rule in the Admin console, complete the following steps:

    1. Select Products from the main menu
    2. Select Features from the menu options

      The Features screen displays.

    3. Select the Add a Feature button

      The Add a Feature screen displays.

    4. Complete the Add a Feature screen as follows:
      1. Enter a name for the Feature in the Title text box
      2. Optionally, add a description of the feature, using no more than 100 characters, in the Description text box
      3. Select the HTML radio button from the Types of Integration options
      4. Select the Continue button to create the Feature

      The Developer Interface screen displays.

    5. Complete the Developer Interface section to configure the type of integration as follows:
      1. Select the Run In Browser radio button from the Where to Run options
      2. Enter a CSS Selector for the feature in the CSS Selector text box, as illustrated below:

        Developer Console - Run In Browser

      3. Select the Update & Lock button. Selecting the Cancel button closes and locks the Developer Interface without making changes

        Note: If you return to an existing feature, the Developer Interface section is locked by default and located at the bottom of the page. You can unlock and open the Developer Interface section by clicking inside the border.

        The rules canvas section displays.

    6. Create a basic rule to test the integration as follows:
      1. By default, the Anonymous user journey is selected, select Outcomes from the decision bar
      2. Select Add Outcome from the listed decision points

        The Add an Outcome screen displays.

      3. Enter a name for your Outcome in the Title text box
      4. Optionally, add a description of the outcome in the Description text box
      5. Select the Add a New Form Or Custom Component Block button
      6. Select the Add Custom Component Block button

        The Custom Content Block dialog box displays.

      7. Enter a name for the custom content block in the Title text box
      8. Enter a message in the large text box, as illustrated below:

        Custom Component Block Example

      9. Select the Save button

        The Add an Outcome screen displays.

      10. Select the Save button to save your Outcome

      Your new outcome is added to the palette, with the title you entered.

    7. Drag your outcome to the rules canvas
    8. Connect your outcome to the Page View node
    9. Scroll to the bottom of the screen and select the up arrow next to the Save button
    10. Select Save and Publish

    Test the Rule

    To test the rule, complete the following steps:

    1. Open the page you created; for example, we open the page that was created in Example Page
    2. Refresh your browser

    The console log updates as illustrated below:

    Testing an In-Browser Rule

    Augmenting Decision Data

    With this integration, you can add a custom data argument in the run command. This can be used in a Zephr Feature to determine a customer’s journey.

    The following example determines whether a user has Ad Block running on their browser:

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

    As you can see, the user does have Ad Block running.

    This information is passed to the custom object. You can use the Custom Data Node in your Zephr Feature Builder to make a decision based on the response as follows:

    1. Navigate to the relevant Feature
    2. Select Content from the decision bar
    3. Drag the Custom Data decision point to the rules canvas

      The Custom Data dialog box displays.

    4. Select the object that you want to query from the Property Name options

      In our example, we select hasAdBlock.

    5. Select the condition from the Condition drop-down menu

      In our example, we select Contains.

    6. Enter the value to search for in the Value text box

      In our example, we enter true.

      The Custom Data dialog box with our selections is as illustrated below:

      Browser-Side Features - Custom Data

    7. Select the Save button

    Your rule now includes branches for the following user journeys:

    • Using Ad Block
    • Not using Ad Block

    Common Custom Data Objects

    You might want to make decisions based on whether a user has an Incognito Window, as well as whether they are running Ad Block.

    You can use the following examples to pass this information to a custom data object for use in a Browser-Side rule:

    • Ad Block: https://github.com/sitexw/BlockAdBlock
    • Incognito Browsing: https://github.com/Maykonn/js-detect-incognito-private-browsing-paywall

    Zephr Functionality Through Third-Party CDNs

    Zephr out-of-the-box functionality, such as forms, extensions and Single Sign-on (SSO), expects a same-origin path for Zephr API calls. If you are not using the Zephr CDN, you must reverse or forward proxy any browser requests towards /blaize* and /zephr*. For further information, see Using Zephr Functionality Through Third-Party CDNs.

    Limitations

    The biggest limitation with any JavaScript-based solution is that it relies on JavaScript. The site visitor must also have JavaScript enabled in their browser.

    One strategy for high-value content is to load some, or all, of the content after Zephr has executed. This prevents circumvention by disabling JavaScript. Alternatively, you can use the Zephr CDN, which is far more secure.