Hosting Options

There are multiple possible hosting options for Transcend Consent:

  1. Transcend-Hosted using transcend-cdn.com
  2. Transcend-Hosted using Custom Domain Alias
  3. Self-Hosting using “Upload/Download”
  4. Self-Hosting using “Reverse Proxy”

For Option 1, the Consent modules are uploaded to and served from Transcend’s CDN. The end-user downloads the modules from transcend-cdn.com. This is the default option. The main downside is that you’ll be loading critical Consent modules from a third party domain, which may be blocked by browser extensions and incur additional TLS handshakes when the site is loaded for the first time.

For Option 2, the Consent modules are uploaded to and served from Transcend’s CDN, but the end-user will download these modules from the customer’s own domain. This is accomplished using DNS aliases and Cloudflare’s custom hostname solution. This is our recommended solution if you wish to load Consent modules from your own domain.

Customers may want to self-host to fulfil security requirements, or to help improve page performance. When self-hosting, customers will have more control over caching controls and there will be fewer TLS handshakes on initial page load. The main downside is that regionalization will not work out of the box. If you wish to offer different user experiences based on the user's geo-IP/regional information, then you will need to re-implement this feature yourself.

We do not recommend self-hosting, because it is incompatible with our regionalization feature, and also adds a great deal of complexity to the caching logic. Should issues arise, the Transcend Support team will not be able to provide much assistance since our team would not be familiar with your specific infrastructure setup.

For Option 3, the customer downloads the file from Transcend’s CDN, and uploads it to their CDN. The end-user downloads the Consent modules from the customer CDN, and Transcend’s CDN is never involved. The two files are kept in sync via some background process that is triggered by our webhook. For this feature, the main downside here is that there will be more engineering lift compared to option #1, and you will need to re-implement the regionalization feature. If you must load resources from your own domain and CDN, we recommend Option 4 over Option 3.

For Option 4, the customer’s CDN acts as a reverse proxy to Transcend’s CDN. When the end-user requests the file from the customer’s CDN, two things could happen:

  1. If it is already cached, then the customer’s CDN will simply return the file from the cache and Transcend’s CDN is not involved.
  2. If it is not cached, the customer's CDN will fetch the file from Transcend’s CDN and then cache it. How this is implemented depends entirely on which CDN provider the customer is using, so we can’t provide much more detail/guidance here.

This is the default option, and you do not need to take any additional steps to set up Transcend Consent.

This is our recommended option if you wish to serve Consent modules from your own domain. Please refer to the implementation steps here.

Self-hosting is when the customer serves the consent modules from their own CDN. For self-hosting, you do not need to make any changes in the Admin Dashboard relating to the custom domain/custom sync domain, as those inputs are for the Custom Domain Alias feature.

Some customers choose to self-host for security reasons. There are also performance benefits if the customer hosts the Consent resources on the same host as that of their site’s static content, as that reduces the number of TLS handshakes that need to happen for each page load

Transcend Consent consists of multiple modules, and you only need to self-host the modules that you actually use. Even then, it is fine to do a mix-and-match approach where you only host some modules that are on the critical performance path and let Transcend handle the rest. For example, if you are only concerned about performance, then only hosting the web consent core modules should be sufficient, as only these modules can be loaded in a blocking, synchronous manner.

Note, for the implementation, you will need your BUNDLE_ID, which can be found in Developer Settings.

  1. Copy the following resources to your CDN. It is important to preserve the paths of these modules. So if you want to self-host at example.com, then the ui module should live at example.com/cm/BUNDLE_ID/ui.js.
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/airgap.js
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/ui.js
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/xdi.js
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/metadata.json
  1. [Optional] You may choose to copy over the UI resources to your CDN as well. These UI modules are loaded async and should not impact the critical loading path of the site.
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/cm.css
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/translations/<language-key>.json. The full list of supported language keys can be found at this repository, under ConsentManagerLanguageKey.
  • You will also need to modify the location from which airgap.js will load these modules (you don’t need to do this step for the other modules as they are assumed to be loading via relative paths):
  • data-css=https://your-cdn.com/cm/<BUNDLE_ID>/cm.css
  • data-messages=https://your-cdn.com/cm/<BUNDLE_ID>/translations
  1. [Optional] You may also want to host the test bundle resources as well, which can be found at the path cm-test instead of cm, e.g. https://transcend-cdn.com/cm-test/<BUNDLE_ID>/airgap.js
  2. Set up a recurring process to re-sync your CDN with ours. We can send a webhook to your server whenever you publish changes in the Admin Dashboard. This can be set up in Developer > Advanced Settings
  3. You should now be able to update the airgap.js script snippet to load from your CDN.
  4. Decide if you want to offer different Regional Consent Experiences for users based on where they are. If so, you will need to re-implement this feature on your CDN.
  • [Optional] Note, if you want to offer different Regional Consent Experiences for users based on where they are, then you should load the airgap.js script with the query parameter ?regime-hints=”off” so that you don’t accidentally load in (and cache) the wrong region info.
  1. [Optional] Implement geo-ip hints on your CDN. This can be accomplished by adding code that prepends the following snippet to the airgap.js file:
self.transcend = Object.assign(
  {
    country, // 2-letter country code, ISO 13166-1 alpha-2
    countryRegion, // The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.
  },
  self.transcend,
);
// rest of airgap.js

Here is a simple JavaScript snippet that you can use to prepend this data (where originOriginalBody refers to the raw airgap.js contents loaded from Transcend CDN):

const locationInfo = {
  country: userCountryCode,
  countryRegion: userCountryRegion,
};
const locationScript = `self.transcend=Object.assign(${JSON.stringify(
  locationInfo,
)},self.transcend);`;
const newBody = originOriginalBody.replace(
  'self.transcend=',
  `${locationScript}self.transcend=`,
);

In order to sync consent preferences across your websites, you will need to host a set of files that define this grouping of consent preference. Every site (eTLD+1) should host a sync endpoint that can coordinate consent sync across the site’s subdomains.

  1. Copy the sync endpoint into your CDN. The sync endpoint is an empty-looking HTML file that can be found at https://sync-transcend-cdn.com/cm/<BUNDLE_ID>
  2. Host the sync endpoint at each site where you want to enable consent sync for that site’s subdomain.
  • If you want consent syncing between foo.example.com and bar.example.com, then you would host the sync endpoint at sync.example.com/cm/<BUNDLE_ID>
  • If you also want syncing between foo.acme.com and bar.acme.com, then you would additionally host the sync endpoint at sync.acme.com/cm/<BUNDLE_ID>
  1. Configure airgap.js to use the custom sync endpoint(s) using the load option data-sync-endpoint
  • For the airgap.js script loaded at example.com, then you would set data-sync-endpoint=https://sync.example.com/cm/<BUNDLE_ID>
  • For the airgap.js script loaded at acme.com, then you would set data-sync-endpoint=https://sync.acme.com/cm/<BUNDLE_ID>

Follow the instructions for self-hosting Web Consent Core Modules You’ll also need to copy/mirror these additional resources onto your CDN:

  • https://transcend-cdn.com/cm/<BUNDLE_ID>/bridge.html
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/bridge.js
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/native/config.json

Follow the instructions for self-hosting Web Consent Core Modules You’ll also need to copy/mirror these additional resources onto your CDN:

  • https://transcend-cdn.com/cm/<BUNDLE_ID>/tcf/ui.js
  • https://transcend-cdn.com/cm/<BUNDLE_ID>/gpp.js

This is hyper-specific to the CDN provider that each customer uses, so we cannot provide detailed guidance at this time. We also don’t recommend this option due to the added complexity of having two different CDN caches interact with each other. For the Transcend CDN, we set the Cache-Control header to be max-age=60,s-maxage=86400. This header controls both the CDN and the browser cache. We also invalidate our CDN cache whenever the user clicks “Publish Changes” from the Admin Dashboard.

If you want to pursue this option, the first step is to consult with your CDN provider for more details on how to set up the reverse proxy.

Once that is done, you will need to decide if you want to offer different Regional Consent Experiences for users based on where they are. This is a feature that is offered by the Transcend CDN, so in moving to using your own CDN, you will need to re-implement it. Implementation involves two steps:

  1. When loading airgap.js script from Transcend CDN, make sure to use the query parameter ?regime-hints=off so that you don’t accidentally load in (and cache) the wrong region info.
  2. Before serving the airgap.js resource to the end-user, prepending this snippet to the top of the file:
self.transcend = Object.assign(
  {
    country, // 2-letter country code, ISO 13166-1 alpha-2
    countryRegion, // The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.
  },
  self.transcend,
);
// rest of airgap.js

Here is a simple JavaScript snippet that you can use to prepend this data (where originOriginalBody refers to the raw airgap.js contents loaded from Transcend CDN):

const locationInfo = {
  country: userCountryCode,
  countryRegion: userCountryRegion,
};
const locationScript = `self.transcend=Object.assign(${JSON.stringify(
  locationInfo,
)},self.transcend);`;
const newBody = originOriginalBody.replace(
  'self.transcend=',
  `${locationScript}self.transcend=`,
);