SDKs
API
Share consents across devices
Introduction
The Didomi CMP supports syncing to allow consent sharing across devices and environments. Consent can be shared between all environments that have syncing enabled in the same organization: multiple websites, multiple apps (same or multiple devices), multiple websites and apps together, etc.
When syncing is enabled and an organization user ID is available, the Didomi CMP will load the previously stored user choices from the Consents API and will apply them locally.
Syncing is currently a premium feature. You can schedule a meeting with our Support team through the console to enable the feature for your account. See this article for more information.
We do not support the cross device feature for AMP sites due to the single consent status limitation of the framework.
Configuration
How to share an organization user ID with Didomi?
For the sync process to work properly, a
user.organizationUserId property needs to be set in the Didomi configuration object:1
window.didomiConfig = {
2
user: {
3
organizationUserId: 'organization-user-id',
4
}
5
};
Copied!
This value represents the unique identifier with which the organization identifies the user for which it wants to sync the consents. This can be an email address, a user ID, etc. We recommend hashing the value to not communicate plain user IDs to Didomi.
This must be set before the Didomi Web SDK is embedded onto the page.
You need extra steps to authenticate the user ID on the Didomi side so please read on to complete your configuration.
Which user organization ID to share with Didomi?
When the user is identified by the website through a login process or any other authentication method, a unique user ID should be shared with the Didomi SDK through the
window.didomiConfig object.
The unique user ID can be any string but we recommend sending a hashed version of your internal user ID to not expose any sensitive data on the page or to Didomi. Avoid sharing plain email addresses, user names, etc. with Didomi.The same unique user ID will need to be shared in other environments like mobile apps. If you are sending a hashed ID, make sure that you will be able to send exactly the same ID in from environments.
The user ID shared on the website will be used as the organization user ID in our Consents API. If you are accessing the user status or event from the API, you will need to specify the same user ID as what is shared on the website, including any form of anonymization or hashing method in place.
The organization user ID must be consistent across your organization and all the other Didomi products you are using (APIs, Privacy Center, etc.).
Authentication with a hash digest
Using a hash digest does not guarantee the confidentiality of the user ID passed to Didomi as it is exposed in clear text on the page.
As the user ID is provided in a public environment (on a webpage), we need to authenticate it to guarantee that users cannot freely read and write consents for any user ID.
To authenticate the user ID and prove that it was authorized by the website, you will need to compute a hash digest of the user ID concatenated with a secret. This digest must be computed directly by your server in an authenticated context and not on the client-side. When it receives a request, Didomi will re-compute the digest with the secret and make sure that it matches the digest that you provided.
The hash digest should be provided in the
user.organizationUserIdAuthDigest property. You will also need to provide the ID of the secret and the hashing algorithm used for generating the hash digest.Example:
1
<script type="text/javascript">
2
window.didomiConfig = {
3
user: {
4
organizationUserId: 'organization_user_id',
5
organizationUserIdAuthDigest: MD5('organization_user_id' + 'secret'),
6
organizationUserIdAuthSid: 'secret_id',
7
organizationUserIdAuthAlgorithm: 'hash-md5'
8
}
9
};
10
</script>
Copied!
Note that the digest is computed on the concatenation of the user ID and the secret, without any extra space added. Example:
organization_user_idsecretSecrets
When computing a hash digest, a secret needs to be used. Secrets can be managed through the Didomi API to obtain an actual secret and its associated ID. Read our documentation to manage secrets for your organizations.
Hashing methods
Didomi supports the following methods for computing a digest:
Algorithm
ID
Description
Hash MD5
hash-md5Hexadecimal digest computed with the MD5 algorithm
Hash SHA1
hash-sha1Hexadecimal digest computed with the SHA1 algorithm
Hash SHA256
hash-sha256Hexadecimal digest computed with the SHA256 algorithm
HMAC SHA1
hmac-sha1Hexadecimal representation of a HMAC computed with the SHA1 algorithm
HMAC SHA256
hmac-sha256Hexadecimal representation of a HMAC computed with the SHA256 algorithm
For all methods, the content to compute the digest on and the secret are the same. The method ID must be provided in the
organizationUserIdAuthAlgorithm property.Salting
For increased security, you can use a salt when computing the hash digest. You will need to provide the salt in the configuration so that Didomi can use it when verifying the user ID.
Example:
1
<script type="text/javascript">
2
window.didomiConfig = {
3
user: {
4
organizationUserId: 'organization_user_id',
5
organizationUserIdAuthDigest: MD5('organization_user_id' + 'secret'),
6
organizationUserIdAuthSid: 'secret_id',
7
organizationUserIdAuthAlgorithm: 'hash-md5'
8
organizationUserIdAuthSalt: 'salt'
9
}
10
};
11
</script>
Copied!
Information expiration
The authentication methods guarantee the integrity of the information (i.e., the information originates from the client and cannot be modified by a third-party) but do not guarantee that that information cannot be reused.
To prevent reusing an encrypted user identifier, we support the addition of expiration information. You can mark the information as having an expiration date so that it cannot be used after a certain date using the
organizationUserIdExp parameter. This should be a valid unix timestamp value.Example:
1
<script type="text/javascript">
2
window.didomiConfig = {
3
user: {
4
organizationUserId: 'organization_user_id',
5
organizationUserIdAuthDigest: MD5('organization_user_id' + 'secret' + 'salt'),
6
organizationUserIdAuthSid: 'secret_id',
7
organizationUserIdAuthAlgorithm: 'hash-md5',
8
organizationUserIdAuthSalt: 'salt',
9
organizationUserIdExp: 1628714229
10
}
11
};
12
</script>
Copied!
Enabling sync
The sync process can be enabled with a
sync.enabled configuration option in the Didomi configuration object:1
window.didomiConfig = {
2
user: {
3
organizationUserId: 'organization-user-id',
4
},
5
sync: {
6
enabled: true
7
}
8
};
Copied!
Behavior
Frequency
By default, the sync process will run once every day. The value in seconds for the sync process can be specified via the
frequency configuration option.1
window.didomiConfig = {
2
user: {
3
organizationUserId: 'organization-user-id',
4
},
5
sync: {
6
enabled: true,
7
frequency: 86400
8
}
9
};
Copied!
Sync timeout
The maximum time allowed for the syncing process to be completed can be specified with a
sync.timeout configuration option in the Didomi configuration object:1
window.didomiConfig = {
2
user: {
3
organizationUserId: 'organization-user-id',
4
},
5
sync: {
6
enabled: true,
7
timeout: 2000
8
}
9
};
Copied!
The
sync.timeout configuration option accepts an integer which represents the maximum time allowed (in milliseconds) for the syncing process to be completed.If the syncing process takes more time to be completed than it is specified in
sync.timeout configuration option, the initialization continues as if there was no data to sync.Delaying notice showing
The Didomi CMP enables delaying notice showing while the sync is in progress. This ensures that the user never sees the consent notice if sync is possible.
The
sync.delayNotice configuration option can be used for delaying the notice showing until the sync is complete:1
window.didomiConfig = {
2
user: {
3
organizationUserId: 'organization-user-id',
4
},
5
sync: {
6
enabled: true,
7
delayNotice: true
8
}
9
};
Copied!
Last modified 3mo ago