Self-hosting
To serve the Web SDK from your own domain and infrastructure, we recommend setting up a reverse proxy. This ensures that the SDK and API requests are cached on your own servers while allowing you to use the latest version from the SDK and from the consent notice configuration.

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.The API is available on
api.privacy-center.org
. All requests sent to the API must be proxied to the domain without any caching.To setup a reverse proxy, implement the following steps.
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 the reverse proxy software of your choice with two rules to proxy:
- All files from
https://dsdk.client.com
tohttps://sdk.privacy-center.org
with their associated path, method, headers, and body. The proxy must query the Didomi URL in HTTPS. For instance, the requestGET https://dsdk.client.com/loader.js?domain=...
should be proxied toGET https://sdk.privacy-center.org/loader.js?domain=...
. - All requests to
https://dsdk.client.com/api/
tohttps://api.privacy-center.org
with their associated path, method, headers, and body. The proxy must query the Didomi URL in HTTPS. For instance, the requestPOST https://dsdk.client.com/api/events
should be proxied toPOST https://api.privacy-center.org/events
.
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.
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).
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.
Once your sub-domain and proxy are setup, the SDK needs to be configured to use your domain for three types of requests:
- The initial
loader.js
request that is sent directly from the Embed code obtained from the Didomi Console. - The chunks loaded by the SDK itself.
- Requests sent to the API by the SDK.
The following steps explain how to configure the SDK.
Update the Embed code from the Didomi Console to replace
https://sdk.privacy-center.org/
with your sub-domain. This ensures that the first request to load the Didomi SDK (the loader.js
file) uses your sub-domain.For the other JavaScript files loaded by the SDK, you must configure the paths to use by setting the
sdkPath
and apiPath
properties in the window.didomiConfig
object:<script type="text/javascript">
window.didomiConfig = {
sdkPath: 'https://dsdk.client.com/',
apiPath: 'https://dsdk.client.com/api',
};
</script>
The
sdkPath
property must start with http://
, https://
, or //
. It must also end with a final /
. The apiPath
property must start with http://
, https://
, or //
.For security reasons and to avoid injecting JavaScript on your website from the Didomi Console, the
sdkPath
and apiPath
properties cannot be set via Custom JSON in the Didomi Console.
They must be set directly on your website via the window.didomiConfig
object.The following limits apply when using a reverse proxy to serve the Didomi SDK.
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.
Last modified 12d ago