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.

📘

Cross device consent

When you need to retrieve a user's consent profile (e.g. upon login or app launch), the app should call the Banner API (passing in the identifier, JWT, and fetch type) to determine if a banner needs to be shown. The user's profile consents will be returned in storageKeys under OT_GroupConsents and OT_SdkConsents.

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 both the otConsentString and OT-Tcf-Eu2v2-Consent-String 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.

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).

Storage Data

The application is responsible for storing the following data in local storage and updating the values on each app launch or consent change.

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.

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 as well as individual SDKs 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 is passed in the header of each call. For category consents, reference OT_GroupConsents. 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
   },
   "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
   }
}