Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
      • Versions
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page
  • Didomi Endpoints
  • Web SDK
  • API
  • Reverse proxy setup
  • Create a dedicated sub-domain
  • Configure a reverse proxy
  • Limits
  • Delayed updates to the consent notice
  1. SDKs
  2. Web SDK
  3. Custom domain

Reverse proxy

With a reverse proxy, all traffic to your custom domain will be routed first to your infrastructure before being proxied to Didomi if needed. A reverse proxy allows you to do caching and traffic management.

Didomi Endpoints

Web SDK

The Web SDK is served on sdk.privacy-center.org and is composed of the following files.

Name
Description

Loader

Dynamic file that contains the configuration of consent notices. The file is specific to every organization and notice. Update frequency: Every time you publish a new version of the consent notice in the Didomi Console or when Didomi releases a new version of the Web SDK (up to a few times a week). Cache lifetime: Short (from minutes up to 1 hour) Pattern: https://sdk.privacy-center.org/{Public API Key}/loader.js

Core

Static JavaScript file that contains the logic of the SDK. The file is updated regularly (up to a few times a week) when Didomi releases a new version of the SDK. Update frequency: When Didomi releases a new version of the Web SDK (up to a few times a week).

Cache lifetime: Long (1 year) Pattern: https://sdk.privacy-center.org/sdk/{Version ID}/.sdk.{Version ID}.{Browser support}.js

UI

Static JavaScript files that contain all the UI of the SDK. The file is updated regularly when Didomi releases a new version of the SDK. Update frequency: When Didomi releases a new version of the Web SDK (up to a few times a week).

Cache lifetime: Long (1 year) Patterns:

- https://sdk.privacy-center.org/sdk/{Version ID}/ui-{Regulation}-{Language}-web.{Version ID}.{Browser support}.js (for GDPR and other regulations with multiple languages) - https://sdk.privacy-center.org/sdk/{Version ID}/ui-ccpa.{Version ID}.{Browser support}.js - https://sdk.privacy-center.org/sdk/{Version ID}/ui-cpa.{Version ID}.{Browser support}.js - https://sdk.privacy-center.org/sdk/{Version ID}/ui-cpra.{Version ID}.{Browser support}.js - https://sdk.privacy-center.org/sdk/{Version ID}/ui-ctdpa.{Version ID}.{Browser support}.js - https://sdk.privacy-center.org/sdk/{Version ID}/ui-vcdpa.{Version ID}.{Browser support}.js - https://sdk.privacy-center.org/sdk/{Version ID}/iab-texts.{Version ID}.{Browser support}.js (IAB vendor information)

We do not guarantee the number of files or the structure of their paths as those can change pretty often when we update our SDK to add new regulations or features, and optimize the loading process. Do not try to whitelist specific files to cache: all files from the sdk.privacy-center.org domain should be proxied and cached without any filtering on your side.

API

The API is available on api.privacy-center.org. All requests sent to the API must be proxied to the domain without any caching.

Reverse proxy setup

To setup a reverse proxy, implement the following steps.

Create a dedicated sub-domain

Create a dedicated sub-domain and point it to your reverse proxy.

We'll use dsdk.client.com as an example in this documentation but any sub-domain will work.

Configure a reverse proxy

Configure the reverse proxy software of your choice with two rules to proxy:

  • All files from https://dsdk.client.com to https://sdk.privacy-center.org with their associated path, method, headers, and body. The proxy must query the Didomi URL in HTTPS. For instance, the request GET https://dsdk.client.com/loader.js?domain=... should be proxied to GET https://sdk.privacy-center.org/loader.js?domain=....

  • All requests to https://dsdk.client.com/api/ to https://api.privacy-center.org with their associated path, method, headers, and body. The proxy must query the Didomi URL in HTTPS. For instance, the request POST https://dsdk.client.com/api/events should be proxied to POST https://api.privacy-center.org/events.

Requests to origin (Didomi CDN)

When proxying a request to the Didomi CDN, your proxy should be configured with the following rules:

Rule

Description

Forward and cache based on path and query string

The full path and query string of requests sent to sdk.privacy-center.org must be forwarded in entirety to the Didomi CDN. Caching must be done on the full path and query string. Requests to api.privacy-center.org must never be cached.

Cache based on geo (ISO country and region)

The Didomi CDN files are generated and served based on the user ISO country and region codes (determined from the user IP). Ensure that your proxy acts the same way and caches different versions of a given file based on the country and region of the user request.

Files returned by the Didomi CDN are not specific to a given user but to the user country and region.

Requests to api.privacy-center.org must never be cached.

Do not forward cookies

Cookies should not be forwarded to the Didomi CDN and can be discarded from the request.

Forward user IP

The original IP of the user should be forwarded to the Didomi CDN in the X-Forwarded-For header.

Your proxy must NOT query the Didomi CDN more often than indicated by the cache headers returned by the Didomi CDN. In particular, it must not query the Didomi CDN for every single request coming from users. Country and region-based caching MUST be configured in your proxy.

Your proxy will be automatically throttled and disabled without warning if it is querying the Didomi CDN too often.

Add the user country and region to your notices

To do this, you will need to add the user country and region directly to your local SDK config object during page load, dynamically setting the window.didomiConfig.user.country and window.didomiConfig.user.region properties to have their values equal to a valid country and region codes:

window.didomiConfig = {
    user: {
        country: "US",
        region: "CA"
    }
}

This will override the default geolocation behavior on the loader.js route, meaning that for example a visitor located in California loading the SDK for a URL that would otherwise be https://dsdk.client.com/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn will end up making a request to our CDN at https://sdk.privacy-center.org/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn&country=US&region=CA;country=US and region=CA having been added at load time and used to serve a config as if the user was located in California.

Caching

Your proxy must cache files based on:

  • The full path and query string

  • The user country and region ISO codes

If the reverse proxy does not correctly cache files based on the rules listed above, the wrong consent notice could be returned and shown to the user (for instance, GDPR could be shown to a California user even if you have configured CPRA for your notice).

Responses from origin (Didomi CDN) and caching headers

After getting a file from the Didomi CDN, your proxy must respect all cache headers returned by the Didomi CDN (Cache-Control, Expires, etc.) to ensure that files updated on the Didomi CDN get updated in your proxy as well.

You must return the cache headers to the end user as well to limit the number of requests sent by users to your proxy and the number of requests sent by your proxy to the Didomi CDN.

If your proxy is querying the Didomi CDN more often than indicated by the cache headers, it must include HTTP headers like If-Modified-Since or Etag from the cached files.

Files can be cached locally by your proxy and returned if stale to increase reliability.

Limits

The following limits apply when using a reverse proxy to serve the Didomi SDK.

Delayed updates to the consent notice

When you publish changes to a consent notice with a the regular SDK domain, the notice is instantaneously updated on your website. The cache of the Didomi CDN is invalidated to ensure that the changes are immediate. With a reverse proxy, an additional delay is added as the cache of the proxy is not immediately cleared. Having a mechanism to clear the proxy cache after publishing a consent notice can help solve this problem.

PreviousDomain delegationNextShare consents between domains

Last updated 10 months ago

You must add the country and region code to your notice configuration on page load to ensure the correct loader.js file is downloaded from our services to be cached by your proxy correctly.

Read more information about leveraging the didomiConfig object for controlling the behavior of user location . Please note that this may require obtaining a new embed code for your notice and updating the embed code in your HTML if your notice was created earlier than September 2023.

ISO 3166-1 alpha-2
ISO 3166-2
here