Implementation Guidance

Application Launch

OneTrust recommends calling the Banner API on each app launch to determine whether a banner needs to be shown. If IAB TCF is in scope and the TC String is available, it must be passed into the header of the API call in addition to the otConsentString for showBanner to return false.

After the first/initial API call, it will be the application's responsibility to store the otConsentString in local storage and send it in subsequent calls for any of the APIs used. The otConsentString should be updated once a new one from the latest API used is received and passed into the next API call. Rinse and repeat.

If IAB TCF in in scope, the TC String must be passed into the header for the Banner, Preference Center and Vendor List APIs for the correct values to be returned. The TC String will only need to be passed into the Save and Log Consent API if using the SYNC_PROFILE interaction type.

User Interface

The application is responsible for providing the UI but OneTrust provides the necessary data to seed the UI. View the Get Banner UI and _Get Preference Center UI pages for more information.

If you're retrieving an IAB TCF Vendor List, make sure you include the otConsentString, OT-Tcf-Eu2v2-Consent-String, and OT-Addtl-Consent-String (if GAC is in scope) in the header to ensure the correct consentStatus and legIntStatus for each vendor is returned. The vendor list API will also only return active vendors as configured in admin UI.

Saving Consent

As the user makes a consent choice on the banner or preference center, the application can save the consent with the Save and Log Consent API.

If you use any of the ALLOW_ALL or REJECT_ALL interaction types, you can leave the keys in the consent body empty. The consent status will only have to be specified when using any of the CONFIRM interaction types.

If you're updating consent for an IAB TCF vendor, you only have to update the vendor whose consent is changing, you won't have to update all of them.

As of 202410.1.0, if the OT-Identifiervalue will be updated/different from the identifier stored in otConsentString, you'll have to pass in the OT-Identifier-UpdateTypeheader with a value of Rename-Identifier. This header is applicable for all 4 APIs but is typically only used with the Save and Log Consent API with a cross device use case. For example, if the application collects consent anonymously (pre-login) and a user logs in, you may be calling the Save and Log Consent API with your cross device credentials (including OT-Identifier). At this point, the identifier you specify may be different from the identifier stored in otConsentString. In this case, the OT-Identifier-UpdateTypeheader is needed to prevent errors. To simplify things, you can pass in this header for every single call even if the identifier is not changing.

Cross Device Consent

Retrieving User Profiles

To retrieve a user's profile, ensure you're passing OT-Identifier, OT-Sync-Profile-Auth, and OT-Fetch-Type into the Banner and Preference Center API calls.

Updating/Creating User Profiles

To update or create a user's profile, ensure you are passing OT-Identifier, OT-Sync-Profile-Auth, and OT-Fetch-Type into the Save and Log Consent API call. If these keys are not passed with the correct JWT for the identifier, profiles will not be created or updated (i.e. isAnonymous is set to true).

Anonymous to Authenticated State Workflow

If your application is collecting user consent during the anonymous/logged out state, you may want to retrieve profile consent (if it exists) or convert the anonymous consent to known/profile consent (if new user) upon login. To support this use case, you can use the SYNC_PROFILE interaction type with the Save and Log Consent API.

The behavior of SYNC_PROFILE can change depending on the 'Override server consent when unknown users log in' toggle in the admin UI.

There are 4 possible journeys depending on the state of the aforementioned toggle:

Override server consent --> OFF

If a user profile DOES exist on OT servers, the profile will be downloaded and anonymous consent is overwritten.

---

Override server consent --> OFF

If a user profile DOES NOT exist on OT servers, the user's anonymous consent will be converted to a new profile.

---

Override server consent --> ON

If a user profile DOES exist on OT servers, the latest/most recent consent will persist. For example, if consent given anonymously (before login) is the latest consent (in terms of the time stamp), it will be retained/persisted instead of the existing server consent. If the existing server consent time stamp is the latest, then the server consent will override consent stored locally on the browser/device.

---

Override server consent --> ON

If a user profile DOES NOT exist on OT servers, the user's anonymous consent will be converted to a new profile.

---

❗️

IMPORTANT

Explicit consent MUST be collected in order for a profile to be created if one does not exist. For example, if the app does not surface a banner UI to collect explicit consent or the user does not visit the preference center UI and confirm choices, a profile will NOT be created (if no profile exists) upon log in/calling SYNC_PROFILE. See diagram below for more detail.

Recommended Usage

The application should call the Save and Log Consent API with the SYNC_PROFILE interaction type upon each log in.

Storage Data

The application is responsible for storing the following data in local storage and updating the values on each API call.

otConsentString

This string can be stored in private storage locally as it's only used by the CMP API service.

storageKeys

If IAB TCF or GPP is in scope, a storageKey object will be returned in the response of the banner, preference center, and save consent APIs. The application should store all data in this object in common storage. On any subsequent calls of the three aforementioned APIs, the storageKey values should be updated.

• The OT-Addtl-Consent-String is only needed with the Vendor List API but the string should be updated according to user consent

Handling Consent Changes

When a user makes or updates their consent choices, the application needs to become aware so that it can control the next set of actions like:

• Allowing or restricting processing of 3rd party SDKs based on their categorization
• Passing latest user consent values to 3rd Party SDKs
• Passing the IAB's encoded TC String to 3rd party SDKs
• Passing the IAB's USP String to 3rd Party SDKs
• Routing the user to another location in the App
• Displaying messages to the user of their changes
• Logging updates to internally owned APIs
• etc...

User consent status for OneTrust categories, individual SDKs, and IAB purposes (if applicable) are returned in the response for the Banner, Preference Center, and Save Consent APIs under storageKeys. As such, current consent status can be retrieved at any point in the user journey. Ensure that an updated otConsentString and OT-Tcf-Eu2v2-Consent-String (if applicable) are passed in the header of each call.

For OneTrust category and IAB purpose consents, reference OT_GroupConsents. For IAB legitimate interest consents, reference OT_GroupLIConsents. For SDK level consents, reference OT_SdkConsents.

Integer values:

• 1: Opted in
• 0: Opted out

Sample response:

"storageKeys": {
   "OT_GroupConsents": {
       "C0001": 1,
       "C0003": 1,
       "C0002": 0,
       "C0005": 0,
       "C0004": 0,
       "IAB2V2_1": 1,
       "ISF2V2_1": 1,
       "IFE2V2_1": 1,
       "V2STACK42": 1
   },
   "OT_GroupLIConsents": {
       "IAB2V2_2": 1,
       "IAB2V2_7": 1,
       "IAB2V2_8": 1,
       "IAB2V2_9": 1,
       "IAB2V2_10": 1,
       "IAB2V2_11": 1
   },
   "OT_SdkConsents": {
       "704806db-3653-44f4-b13b-52164408bc2e": 1,
       "60bf4101-0b0c-451e-9c48-1eca1b402821": 1,
       "599e5da7-a94e-4137-9335-3965fd823af7": 0,
       "0f81f224-f142-46be-bba5-86736df1c238": 1
   }
}

Moving Between IAB and Non-IAB Jurisdictions

Users traveling from IAB to non-IAB regions and back will need to have their previous IAB choices restored so they're not re-prompted for consent. To accommodate this use case, OneTrust recommends the app pass the TC String (OT-Tcf-Eu2v2-Consent-String) if available into the header of each API call, even in a non-IAB region. Similar to the otConsentString which helps persist OneTrust related consents, the TC String (OT-Tcf-Eu2v2-Consent-String) persists IAB consents. For regions where IAB is not in scope, the CMP API service will disregard the TC String if passed into the call.

To determine if a user is in an IAB region, the app can inspect the response to see if IABTCF_TCString is present under storageKeys. If it is present, then they are in an IAB region. If it is not present, they are not in an IAB region.

This will apply for IAB GPP as well, just swap the TC String keys for GPP String.