OLD Custom Tracking Domain Set Up For Single Tenant Instance

Follow the steps below to set up a custom tracking domain (CTD) for single tenant instances. For more information about how it works see custom tracking domain (CTD) article.

If your API tracking domain is not your subdomain or you have multiple websites on different domains you will need to set additional custom tracking domains for each of your tracked website domains. Follow the steps below.

In case you have a single tenant instance, and your API tracking domain is already a subdomain of your website it might automatically act as a custom tracking domain. Find out what kind of DNS records you are using and see if you need any changes. Learn about differences in DNS records.

📘

Custom tracking domain setting in project settings is not available on single tenant instances and domains will thus be configured by our IT.

1. Prepare a list of subdomains

Define a list of tracking subdomains of your websites to be used as tracking domains e.g. analytics-api.yourdomain.com. The selected subdomain should be dedicated entirely for this use, nothing existing should run there, not even on sub-sub domains e.g "something.analytics-api.yourdomain.com".

❗️

Setting DNS records on an incorrect domain that is used for other purposes can have serious consequences.

2. Request subdomain configuration

Provide the list of domains and the type of DNS records you wish to use: NS zone (recommended) or CNAME to your CSM. Our developers will configure the domains on the Bloomreach Engagement side and provide you with instructions to set the DNS records.

3. Set the DNS record

Our IT will provide the NS DNS records to be configured for your domains. Please bear in mind that setting DNS records doesn’t happen instantaneously and can take up to 24 hours.

Due to this delay, you need to plan ahead and understand the impact of DNS changes. For example, when you switch from an old e-mail tool to Bloomreach Engagement, the delay during the DNS change can affect deliverability.

There are commonly 4 NS records that need to be set.

CNAME records
In case you decide to use CNAME records, our IT will provide the destination domain to which clients need to set the CNAME records. Once the client knows the destination domain, they will need to set a DNS CNAME record for the new subdomain.

🚧

CNAME records does not work to ensure persistent cookies and anonymous identity.

CNAME example:

4. Try to test load SDK

Make sure you followed steps 2. and 3. and your new tracking domain is configured. 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

Be aware it may take a while till the DNS records are propagated and available for validation. If you set your records and your domain is not working, try coming back to it in 24 hours. If it still does not work, the records might not be set correctly.

5. 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 (needed for older snippets)

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 step is not needed.

3. Non-flickering experiments API path (needed for older snippets)

In case you are using the older implementation of 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>

6. Make sure that everything is working

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

📘

Cookies expiry

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.