Configure SDK Parameters
Overview
The SDK retrieves an object that contains all the data needed to present a UI to a user and collect consent for the SDKs used in your application. The data returned is determined by the configurations made in the OneTrust admin console (tenant).
Before proceeding, make sure that your SDK Data has been published inside of the OneTrust Admin Portal (tenant). If the data has not been published, the SDK will not have any data to retrieve. For more information, please review our Publishing the SDK documentation.
- Add the script tag to the body of your
index.htmlfile to callonetrust.jsor the other three files, depending on which option you chose in the Download SDK page.
<!--Option 1-->
<body>
<div id="root"></div>
<script src="onetrust.js"></script>
</body>
<!--Option 2-->
<body>
<script src="../../build/anyCustomPolyfills.js" type="text/javascript"></script>
<script src="../../build/polyfills.js" type="text/javascript"></script>
<script src="../../build/polyfills_corejs.js" type="text/javascript"></script>
<script src="../../build/onetrust_No_Polyfills.js" type="text/javascript"></script>
</body>
- Call
oneTrustTV.Settings()and pass in the following keys:
oneTrustTV.Settings({
key: '',
languageCode: '',
version: '',
storageLocation: '',
countryCodeOverride: '', //optional
regionCodeOverride: '', //optional
redirect: '' //optional if app is an SPA
});
Important
oneTrustTV.Settings() is only setting the values needed for initialization but does not download any data. Data will only start downloading once setupUI() is called. This method must be called each time before setupUI() is called.
Parameters
| Parameter | Description | Required | Location |
|---|---|---|---|
| key | The Application ID (retrieved from OneTrust Admin console) | Yes | OneTrust Admin Console/Tenant |
| languageCode | 2-digit or 4-digit (in the case of advanced languages) ISO language code used to return content in a specific language. Note: Any language code format which is not listed in OneTrust environment will be considered as an invalid input. If the languageCode passed by your application is valid, but does not match with a language configuration available for your template, then the SDK will return content in the default language configured in OneTrust environment (usually, but not always, English). | Yes | Developer defined |
| version | Version of the SDK data to retrieve. Should be (but not always) the version of the SDK used. | Yes | OneTrust Admin Console/Tenant |
| storageLocation | The CDN location for the JSON that the SDK fetches. (Usually, but not always, cdn.cookielaw.org) | Yes | OneTrust Admin Console/Tenant |
| countryCodeOverride | Two-letter ISO 3166-2 country code. This can be used to bypass the automatic geo-ip lookup performed by the SDK. | Optional | Developer defined |
| regionCodeOverride | Two-letter ISO state code (US states only) | Optional | Developer defined |
| redirect | The page that the user is taken to once consent has been provided. Note: If your app is an SPA, you can leave this blank as there is typically no page to redirect to. | Yes, if not an SPA | Developer defined |
Passing Custom Geolocation
The SDK, by default, determines a country and region code for a user based on a geo-ip lookup to deliver a certain UI. If you choose to perform your own geolocation lookup, this is supported by using the countryCodeOverride and regionCodeOverride parameters mentioned above.
Cross Device Consent
Cross Device Consent requires an additional license, Consent Rate Optimization (CRO). If this is not in scope for your implementation, disregard this section.
Cross Device Consent is an optional feature. These parameters are not required for setting up the SDK to fetch and display Banners and Preference Centers to users.
If you are enabling the Cross Device Consent functionality, each of these parameters are required to sync user profile data with the latest values on OneTrust servers.
| Parameter | Description | Required for Cross Device? |
|---|---|---|
| syncProfile | Tells the SDK to attempt Cross Device Consent profile syncing. | Yes |
| syncProfileAuth | Use this to pass the pre-signed JWT auth token required to perform Cross Device. | Yes |
| identifier | Sets the identifier value used to create a user profile server-side. | Yes |
Unified Profile
The Unified Profile feature is supported on this platform. More information here.
- Identify the user. This can be done using your authentication methods.
- Pass the identifier and additional information in the oneTrustTV.Settings.
oneTrustTV.Settings({
key: '',
languageCode: '',
version: '',
storageLocation: '',
countryCodeOverride: '', //optional
regionCodeOverride: '', //optional
redirect: '' //optional if app is an SPA
// Cross Device Consent parameters
syncProfile: true
syncProfileAuth: "[Insert JWT Token Here]",
identifier:"[Insert User ID Here]"
});
The following API can be used to get user consent preferences Get Preferences
API Response codes
| Code | Message | Description |
|---|---|---|
| 200 | Success | Response body contains a list of preferences with the current consent status for a data subject. |
| 204 | No Content | Cross domain/device not in use |
| 304 | Failure | "not necessarily a failure" Consent has not been modified ( E-tag response matching) |
| 401 | Failure/ Unauthorised access | Profile is not returned or a parameter is passed incorrectly in JWT or formatting is incorrect |
FAQs
Does the client need to implement a backend component for generating JWTs for OneTrust? Does OneTrust have any recommendations/advice on that matter?
As a security best practice, yes, we recommend using a backend for generating JWTs as OneTrust does not support this functionality today. The JWT.io site has a lot of great resources if you scroll down the page.
Does the client need to implement differentiate JWTs generated for different types of users? (i.e. web vs. mobile vs. CTV)
No, a JWT auth token is user-specific and tied to their unique identifier. Since you are likely using the same identifier to sync a user's consent between mobile to CTV or web to CTV, there is no need to change the JWT auth token in this scenario.
Updated 5 months ago