Custom tracking domain

Some browsers use mechanisms that disable third-party tracking scripts and cookies. This disables Synerise tracking.

To avoid this, you can serve the Synerise tracking tools from your own subdomain.

When you complete the instructions in this article, the tracking domain will change from a Synerise domain to your sub-domain. Third-party tracking blockers will not affect Synerise tracking.

The process involves:

1. Preparing the domain.
2. Creating a tracking code.
3. Updating Synerise API requests made from the site.
   
   WARNING:

   If you're changing to a custom domain in a workspace where Dynamic Content is used to inject Synerise API requests into the website, you will need to update the Dynamic Content too.
   

Preparing the domain

1. In your hosting, create a subdomain for Synerise tracking, for example api.example.com
   
   Important: The domain name should NOT: contain indications that it is used for tracking; refer to Synerise; or include strings typical to Synerise elements, such as synerise, snr, or snrs.
2. Configure a CNAME DNS entry for the created subdomain:
   

   // For Azure Cloud deployments:
   NAME                    TYPE   VALUE
   --------------------------------------------------
   api.example.com.        CNAME  web.snrbox.com.
   
   // For Google Cloud Platform deployments (currently only available in Belgium):
   NAME                    TYPE   VALUE
   --------------------------------------------------
   api.example.com.        CNAME  web.geb.snrbox.com.

   Note: After creating a DNS entry, you may need to wait 24-72 hours before it becomes active.
3. If you want to use your own certificate:
   1. Prepare an X.509-format certificate.
   2. Deliver the public key as a .pem file to Synerise Support.
      
      Important: When you use your own certificate, it is your responsibility to monitor its expiration time and re-generate it.
4. If you want Synerise Support to provide a certificate for you:
   1. Contact Synerise Support to request the certificate.
      Synerise Support generates a certificate by using third-party solutions such as letsencrypt.org.
   2. If your domain has CAA records, add the following record to the root domain or subdomains used with Synerise:

      api.example.com. IN CAA 0 issue “letsencrypt.org”
      

      Important: If your domain does not use CAA records, you do not have to add them.

Creating a tracking code

Create a tracking code (or update an existing one) with your custom domain as described in Getting started and add it to your website.

Updating your Synerise API requests

In Synerise API requests authorized with the tracker key (for example, Recommendations, Search, AI events APIs), you must:

1. Change the domain to your custom domain.
2. Add ai/ to the beginning of the endpoint path.

These endpoints can be recognized by the availability of authorization methods other than JWT:

• the X-Api-Key header (legacy).
• the token parameter in the query, for example:

  api.synerise.com/search/v2/indices/123/query?query=q&token=B264B70A-1111-1111-1111-AC35EEFA0B59
                                                       |------ tracker key authentication ------|
  

Example:
If you make requests to the following endpoint:

https://api.synerise.com/search/v2/indices/123/query?query=q&token=B264B70A-1111-1111-1111-AC35EEFA0B59

the new query is:

https://api.example.com/ai/search/v2/indices/123/query?query=q&token=B264B70A-1111-1111-1111-AC35EEFA0B59