Didomi Consent String

This document describes an optional binary format for the didomi_token usually stored in Cookies. The new token will be named didomi_dcs and will replace the didomi_token in cookies and local storage. This alternate version of the token is inspired by the IAB TCF consent string and the IAB GPP string and provides a smaller and more compact cookie generated and used by the SDK.

This new cookie format is currently in beta version, please contact [e-mail] if you want to be notified of its final release.

Once enabled, the didomi_dcs cookiewill replace the didomi_token cookie used by your organization.

What purpose does a Consent String serve?

A Consent String’s primary purpose is to encapsulate the expression of a user's choices for their personal data processing under any regulation. The Consent String is used as Didomi's storage format (in cookies or similar local storage) and can be consumed by Didomi's clients and partners to determine whether they have the necessary legal permissions to process a user's personal data for their purposes.

The Didomi Consent String stores user choices for custom vendors and purposes in all cases. Within the context of a GDPR regulation, the IAB TCF String remains the source of truth and the Didomi Web SDK works with both strings to create a unified view of consent choices that are reflected in the public API functions on the SDK. Custom vendors and purposes are assigned numerical IDs that are encoded in the Didomi Consent String and can be accessed by the following API functions:

• Didomi.getVendorNumericId

• Didomi.getVendorByNumericId

• Didomi.getPurposeByNumericId

• Didomi.getPurposeNumericId

What information is stored in a Consent String?

In general, a Consent String contains the following information:

1. General Metadata: version of the Consent String, when it was last updated, when it was initially created, user ID, etc.

2. Purposes Status: user’s choices for processing their personal data for specific purposes.

3. Vendors Status: a user's choices for third-party vendors to access and process their personal data.

Consent String Sections

The Didomi Consent String is divided into several sections:

Encoded Sections

• Header Section: contains general metadata;

• Purposes Consent Section: a user’s choice for processing their personal data for specific purposes based on consent legal basis;

• Purposes Legitimate Interest Section: a user’s choice for processing their personal data for specific purposes based on legitimate interest legal basis;

• Vendors Consent Section: a user's choices for third-party vendors to access and process their personal data for consent legal basis;

• Vendors Legitimate Interest Section: a user's choices for third-party vendors to access and process their personal data based on legitimate interest legal basis;

Non-encoded Sections

• Device ID (DID): a device ID where Didomi Consent String is stored. The DID is appended to the previous Consent String Sections with the . character as a separator. The DID is always the first ID appended to the last of the Consent String Sections. This field is optional, but we still append the . as a placeholder to separate it from the OUID.

• Organization User ID (OUID): a user’s id assigned to this user by the organization (client). It is used to synchronize the user choices between different sessions. The OUID is appended to the string after the DID with the . character as a separator. This field is optional and is only appended to the consent string when the cross device feature is enabled.

• Signature: a cryptographic signature used for the previous sections and DID if it’s present. Signature is concatenated to Consent String Sections with the ~ character. Not bit-encoded. Signature is only generated when the related premium feature is enabled (this feature is coming soon)

Consent String Format Definition

There are consent string examples at the end of the document. The following section of this document defines the structure and format of the consent string.

Didomi Consent String := Sections~Signature |
                         Sections.DID~Signature |
                         Sections.DID.OUID~Signature |
                         Sections..OUID~Signature

Please not that DID, OUID and Signature are not bit-encoded and are appended after the end of the other Sections with separation characters: . for IDs and ~ for the Signature.

Sections := [Header, Purposes Consent, Purposes LI, Vendors Consent, Vendors LI]
 
Purposes Or Vendors Section := Purposes Consent | 
                               Purposes LI | 
                               Vendors Consent | 
                               Vendors LI

Section := [Fields]

Header := [Version, UserId, Created, LastUpdated, HasSynced, LastSync?]   

Purposes Or Vendors Section := [EncodingAlgorithm, Encoded] 

Encoded := BitField Encoded | Range Encoded | Fibonacci Encoded

BitField Encoded := [StartFromOne, StartID?, NumberOfIDs, BitField] 

Range Encoded := [EncodedStatuses, Encoded Ranges, Encoded Ranges?]

Encoded Ranges := [NumberOfRanges, [Range]]

Range := [SingleIdRange, RangeStart, RangeEnd?]

Fibonacci Encoded := [EncodedStatuses, Fibonacci Encoded Ranges, Fibonacci Encoded Ranges?]

Fibonacci Encoded Ranges := [NumberOfRanges, [Fibonacci Range]]

Fibonacci Range := [FibonacciRangeStart, FibonacciNumberIdsInRange]

(? indicates optional fields)

Didomi Consent String Structure

Didomi Consent String	Details
	Sections
	Signature
Sections
	Header
	Purposes Consent
	Purposes LI
	Vendors Consent
	Vendors LI
Header
	Version
	UserId
	Created
	LastUpdated
	HasSynced
	LastSync Optional
Purposes Or Vendors Section
	EncodingAlgorithm
	Encoded
Encoded
	BitField Encoded
BitField Encoded
	StartFromOne
	StartID Optional
	NumberOfIDs
	BitField
Range Encoded
	EncodedStatuses
	Encoded Ranges
	Encoded Ranges Optional
Encoded Ranges
	NumberOfRanges
	Sequence of Range
Range
	SingleIdRange
	RangeStart
	RangeEnd Optional
Fibonacci Encoded
	EncodedStatuses
	Fibonacci Encoded Ranges
	Fibonacci Encoded Ranges Optional
Fibonacci Encoded Ranges
	NumberOfRanges
	Sequence of Fibonacci Range
Fibonacci Range
	FibonacciRangeStart
	FibonacciNumberIdsInRange

Didomi Consent String Fields

Section	Field	Optional (*)	Purposes and Vendors Statuses Encoding Algorithm	Description	Type	Size	Sample decoded value	Sample encoded value
Header	Version	No	N/A	Didomi Consent String format version	number	6 bits	1	000001
Header	UserId	No	N/A	User ID	string	128 bits	1875afe1-461b-6b9f-9d66-700174abbffc	00011000011101011010111111100001010001100001101101101011100111111001110101100110011100000000000101110100101010111011111111111100
Header	Created	No	N/A	Didomi Consent String Create timestamp	date	36 bits	2023-04-12T18:10:00.000Z	001111101010001001011000011110110000
Header	LastUpdated	No	N/A	Didomi Consent Last Update timestamp	date	36 bits	2023-04-12T18:10:00.000Z	001111101010001001011000011110110000
Header	HasSynced	No	N/A	If LastSync is present or not	number	1 bit	0 - LastSync is not present 1 - LastSync is present	0 - LastSync is not present 1 - LastSync is present
Header	LastSync	Yes	N/A	Last sync date	date	36 bits	2023-04-12T18:10:00.000Z	001111101010001001011000011110110000
Purposes and Vendors	EncodingAlgorithm	No	N/A	Defines encoding algorithm that was used to encode purposes or vendors IDs statuses. None could be set to LI statues and in this case LI status are equal to Consent statuses	number	2 bits	0 := BitField Encoding 1 := Range Encoding 2 := Fibonacci Encoding 3 := None	00 := BitField Encoding 01 := Range Encoding 10 := Fibonacci Encoding 11 := None
Purposes and Vendors	StartFromOne	No	BitField	Defines if the StartID field should be used to determine minimum ID encoded	number	1 bit	0 := Encoding starts from StartID 1 := Encoding starts form ID 1	0 := Encoding starts from StartID 1 := Encoding starts form ID 1
Purposes and Vendors	StartID	Yes	BitField	Start (minimum) vendor or purposes ID that was encoded	number	16 bits	1024	0000010000000000
Purposes and Vendors	NumberOfIDs	No	BitField	Number of vendor or purposes IDs encoded	number	16 bits	10	0000010000000000
Purposes and Vendors	BitField	No	BitField	BitField encoded vendors or purposes IDs statuses: Enabled, Disabled or Undefined.	BitSet	variable	Each 2 bits: 00 := Undefined 01 := Disabled 10 := Enabled	000110001001000110
Purposes and Vendors	EncodedStatuses	No	Range, Fibonacci	Define what statuses and in what order have been encoded.	number	4 bits	0 := Enabled 1 := Enabled, Disabled 3 := Enabled, Undefined 4 := Disabled, Enabled 5 := Disabled 7 := Disabled, Undefined 12 := Undefined, Enabled 13 := Undefined, Disabled 15 : = Undefined	0000 := Enabled 0001 := Enabled, Disabled 0011 := Enabled, Undefined 0100 := Disabled, Enabled 0101 := Disabled 0111 := Disabled, Undefined 1100 := Undefined, Enabled 1101 := Undefined, Disabled 1111 := Undefined
Purposes and Vendors	NumberOfRanges	No	Range, Fibonacci	Number of ranges encoded	number	16 bits	3	0000000000000011
Purposes and Vendors	FibonacciRangeStart	No	Fibonacci	First ID in the encoded range for Fibonacci encoding	number	2 ≤ … ≤ 23 bits	7	01011
Purposes and Vendors	FibonacciNumberIdsInRange	No	Fibonacci	Number of IDs encoded in the range for Fibonacci encoding	number	2 ≤ … ≤ 23 bits	1	11
Purposes and Vendors	SingleIdRange	No	Range	Set to 1 if range contains only RangeStart ID	number	1 bit	0 := RangeEnd is present 1 := Single ID Range	0 := RangeEnd is present 1 := Single ID Range
Purposes and Vendors	RangeStart	No	Range	First ID in the encoded range	number	16 bits	1	0000000000000001
Purposes and Vendors	RangeEnd	Yes	Range	Last ID in the encoded range	number	16 bits	3	0000000000000011

Optional fields should appear in an encoded string if the value of the related field is set accordingly.

For example, if StartFromOne is set to 0, then StartID should be present in the encoded field. If StartFromOne is 1, then StartID will be absent.

Within the same consent string, different sections may have different encoding (BitField, Range or Fibonacci) based on the range of the IDs to encode. The final goal being the generation of the smallest possible cookie. The EncodingAlgorithm property indicates which mechanism was used for encoding the given section. To better demonstrate how this works, we have added these detailed scenarios.