Zephr User Guide

Integrate in Existing Technology Stack

419 views 0

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

Running HTML feature rules in-browser is less secure than using the Zephr CDN. This is due to the intrinsic risks associated with a JavaScript-based solution, such as the end user disabling JavaScript in their browser. To prevent circumvention of the JavaScript, Zephr recommends loading some or all content after Zephr has run. Alternatively, consider using the Zephr CDN, which is a more secure solution. For further information on running HTML features in the transformation layer of the CDN, see the HTML Features in the CDN Transformation Layer topic.

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 the Sites topic.

    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 configuring the JavaScript run() method, see the Configure JavaScript Run Method topic.

    For further information on CORS configuration, see Configure the Browser topic.

    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.

    For further information on configuring the cdnAPI endpoint, see the Configure the CDN API Endpoint topic.

  • Note the default live domain

    The default live domain is used when the cdnAPI endpoint is not explicitly specified to initialise the Zephr JavaScript.

    For further information on finding you default domain, see the Find Your Zephr Domain topic.

  • 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.

An example of this implementation is provided in the Example Implementation topic.

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 on using out-of-the-box Zephr functionality with a third-party CDN, see the Use Zephr Functionality with Third-Party CDNs topic.