Implementation Guidance
This page walks you through how to implement the CMP API solution in your application.
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
underOT_GroupConsents
andOT_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
otConsentString
This string can be stored in private storage locally as it's only used by the CMP API service.
storageKeys
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 in0
: 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
}
}
Updated 23 days ago