Custom Tracking Domain (CTD)

What is the purpose of custom tracking domain

Custom tracking domain (CTD) is a way to maintain reliable tracking, data quality and a single customer view compatible with the tracking protection mechanisms introduced by browsers, such as Safari's Intelligent Tracking Prevention (ITP) or Mozilla's Enhanced Tracking Protection (ETP) or many ad blockers. Measures taken by the browsers primarily aim to protect the user's privacy and as a result, change the way cookies are handled. Since browsers are becoming more privacy-conscious, Bloomreach Engagement and its use of "cookie" must also adapt. The custom tracking domain enables the switch from JavaScript cookies to HTTP cookies.

📘

CTD restores the original state of your standard tracking, but not cross-domain tracking.

How CTD works

To make your cookie resistant against ITP and similar measures you can use your subdomain as a custom tracking domain (CTD) for front-end tracking. This gives you the ability to set server-side cookies by Bloomreach Engagement API under your first-party custom tracking domain such as analytics-api.yourdomain.com ( \*.yourdomain.com ), making the Bloomreach Engagement cookie a first-party server-side cookie resistant to tracking preventions.

Most commonly, Bloomreach Engagement uses the api.exponea.com domain to serve JS SDK, service worker for web push notifications, and all of our API endpoints (this may differ for single tenant instances) However, you can configure a custom tracking domain for each top-level domain of each website that you are tracking.

Bloomreach Engagement uses two cookies of different types to maintain the customer identity a client-side __etc_exponea__ and server-side xnpe_<project_id> cookie. Both cookies will hold the same value but can have different expiration. When using CTD, the server-side xnpe_<project_id> cookie will have a long expiry and ensure consistent tracking of anonymous users. The __etc_exponea__ will be still capped to the 7-day expiration on Safari and upon next visit will be renewed based on the xnpe_<project_id> cookie.

Default example:
Website: www.myeshop.com

• Tracking API set to api.exponea.com
• JS SDK loaded from https://api.exponea.com/js/exponea.min.js
• JS SDK creates document cookie on domain .myeshop.com
  • Name: etc_exponea
  • Domain: .myeshop.com
  • Set by: SDK using document.cookie
  • Type: client-side, first-party
  • Expiry: 3 years (default) or your configured custom expiration, for some browsers it can be capped to shorter expiry (7 days on Safari), once this cookie expires the identity is lost

Custom tracking domain example:
Website www.myeshop.com and custom tracking domain analytics-api.myeshop.com

• Tracking API set to analytics-api.myeshop.com
• JS SDK loaded from https://analytics-api.myeshop.com/js/exponea.min.js
• Tracking API creates server-side cookie on domain .myeshop.com
  • Name: xnpe_<project_id>
  • Domain: .myeshop.com
  • Set by: Tracking API
  • Type: server-side, first-party
  • Expiry: 3 years (default) or your configured custom expiration
• JS SDK creates document cookie on domain .myeshop.com
  • Name: __etc_exponea__
  • Domain: .myeshop.com
  • Set by: JS API document.cookie
  • Type: client-side, first-party
  • Expiry: 3 years (default) or your configured custom expiration, for some browsers it can be capped to shorter expiry (7 days on Safari), upon expiry it will be renewed based on the xnpe_<project_id> cookie
• Both __etc_exponea__ and xnpe_<project_id> will hold the same value

How to set up a custom tracking domain

1-4. Create a new domain

Follow the 4-step instructions from the Custom Domain Management article. Once complete, continue with the steps below.

5. Try to test load SDK

Try to test load our SDK from your new domain (you can do this via any browser)
e.g analytics-api.yourdomain.com/js/exponea.min.js

6. Update and test the tracking snippet

There are up to three places where the snippet needs to be updated, based on the version of the web integration snippet you are using. You can update the snippet directly using the instructions below or look into the Web Integration tab where, once the CTD is set up, you can find the updated snippet. In case you have multiple custom domains in one project, follow the steps below.

📘

When updating the snippet be careful to keep all your existing configuration of the initialization unchanged.

1. Tracking API target

Add/Update the "target" parameter to your initialization config and set it to your custom domain e.g. "target" : "https://analytics-api.yourdomain.com

<script type="text/javascript">
    exponea.initialize({
        "target": "//analytics-api.yourdomain.com",
        "token": "<project_token>",
        ...
    });
</script>

2. JS SDK link

Look for the link to exponea.min.js in the initialization snippet and replace the JS SDK domain to your custom tracking domain.
Example:
Change from
//api.exponea.com/js/exponea.min.js
to
//analytics-api.yourdomain.com/js/exponea.min.js

<script>
(function(b,c){
...a.src=g+"//analyticsapi.yourdomain.com/js/exponea.min.js";...
})(window,document);
</script>

If you just see r.target+"/js/exponea.min.js" you have a newest version of the snippet and this stp is not needed.

3. Non-flickering experiments API path

In case you are using non-flickering experiments update the “path” parameter in their initialization config and set it to your custom domain
e.g. webxpClient.path = https://analytics-api.yourdomain.com

<script>
    webxpClient.path = 'https://analytics-api.yourdomain.com';
    webxpClient.sign = '<PROJECT-TOKEN>' + '/' + 
    ...
</script>

7. Make sure everything is working

Visit your website and make sure everything is working (events are being tracked, weblayers displayed…).

📘

Cookies

You might also review the cookies and check the expiry when switching to your new domain. Before doing so please make sure to read how CTD works and which cookies are used.