Installation

This plugin is available in NPM.

Application Requirements

For Android implementations, the AndroidX dependency is required. Add the following to your config.xml file, inside of your Android platform tag.

<preference name="AndroidXEnabled" value="true" />

SDK Version Requirements

Note that the version of the SDK must match the version of the JSON that you have published from your OneTrust instance. For example, if you have published your JSON with version 6.10.0, you must use the 6.10.0 version of the OneTrust plugin. It is recommend that a static version is specified to prevent automatic updates, as a JSON publish will need to occur with every update.

Install Command

To install the OneTrust Cordova Plugin, use the following command.

cordova plugin add [email protected]

Uninstalling

To uninstall, run the following in your project folder.

cordova plugin remove cordova-plugin-onetrust-cmp

Initialization

The OneTrust SDK retrieves an object that contains all the data needed to present a UI to a User to collect consent for the SDKs used in your application. The data returned is determined by the configurations made in the OneTrust Admin console.

Import OneTrust

OneTrust methods can be accessed via window.OneTrust or cordova.plugins.OneTrust.

startSDK

This method is the initialization method for the SDK. It makes between 1-2 network calls, depending if an IAB2 template is fetched or not.

In 6.21, a breaking change was introduced that requires a params argument to be passed in. This is nullable, but as the position of the arguments is not arbitary, unexpected behavior may occur if there is no argument in the params position.

window.OneTrust.startSDK(storageLocation,domainIdentifer,languageCode,params,(status) => {
    console.log("SDK Downloaded Successfully!")
},(error) =>{
  console.log("SDK Failed to initialize! Error = "+error)  
})

Arguments

Initialization Params

The values below can be placed in a JSON object and passed into the params argument of startSDK to provide additional configurations.

Example

const params = {
  syncParams: {
    identifier: '[email protected]',
    syncProfileAuth:'eyJhb...',
  },
  countryCode:"US",
  regionCode: "CA",
  androidUXParams: uxJson
}

Sync Params

Cross-Device Consent is an optional feature. The parameters below are not required for initializing the SDK. Each of the parameters are required to sync the user's consent.

Display User Interfaces

Banner

The banner can be shown by calling

window.OneTrust.showBannerUI()

Determine if a banner should be shown

You can determine whether or not a banner should be shown by calling

window.OneTrust.shouldShowBanner((result)=>{
    console.log("A banner should be shown = "+result)
})

This returns a boolean that determines whether or not the banner should be displayed to the user. See this page for the logic used to determine the result of shouldShowBanner().

Example

Below is an example of how to combine the initialization success handler with the shouldShowBanner function to automatically show a banner, if required, once the SDK download has completed.

window.OneTrust.startSDK(storageLocation,domainId,langCode, params, (status) =>{
  window.OneTrust.shouldShowBanner((shouldShow) => {
    if(shouldShow){
      window.OneTrust.showBannerUI()
    }
  })
}, (error) =>{
  console.log(error)
})

Preference Center

The preference center can be shown by calling

window.OneTrust.showPreferenceCenterUI()

Force Close UI

If the UI needs to be dismissed programmatically, simply call

window.OneTrust.dismissUI()

App Tracking Transparency Pre-Prompt

The App Tracking Transparency Pre-Prompt can be shown by calling the below function. OneTrust.devicePermission.idfa is an enum for the type of permission. On Android and iOS versions < 14, requesting permission of type ifda will resolve a promise with a value of -1 every time.

window.OneTrust.showConsentUI(window.OneTrust.devicePermission.idfa, status =>{
    console.log(`The new ATT Status is ${status}`)
})

Android - Custom styling with UXParams JSON

OneTrust allows you to add custom styling to your preference center by passing in style JSON in a certain format. Build out your JSON by following the guide in the OneTrust Developer Portal.

Add the JSON to the params argument of the startSDK method when initializing.

iOS - Custom Styling with UXParams Plist

Custom styling can be added to your iOS Cordova application by using a .plist file in the iOS platform code. In addition to adding the .plist file (which can be obtained from the OneTrust Demo Application) to your bundle, there are a few changes that need to be made in the platform code, outlined below. Review the guide in the OneTrust Developer Portal.

In appDelegate.h, import OTPublishersHeadlessSDK and make sure that AppDelegate conforms to the OTUIConfigurator protocol.

#import <Cordova/CDVViewController.h>
#import <Cordova/CDVAppDelegate.h>
#import <OTPublishersHeadlessSDK/OTPublishersHeadlessSDK.h>

@interface AppDelegate : CDVAppDelegate <OTUIConfigurator>{}

@end

In appDelegate.m, set the UIConfigurator to self. Then conform to the shouldUseCustomUIConfig and customUIConfigFilePath protocol methods.

#import "AppDelegate.h"
#import "MainViewController.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    self.viewController = [[MainViewController alloc] init];
    [OTPublishersHeadlessSDK.shared setUiConfigurator:self]; //set UIConfigurator to Self
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}


- (BOOL)shouldUseCustomUIConfig { //conform to shouldUseCustomUIConfig
    return true;
}

- (NSString *)customUIConfigFilePath{ //conform to filepath protocol method
    NSString * configFile = [[NSBundle mainBundle] pathForResource:@"OTSDK-UIConfig-iOS" ofType:@"plist"]; //find path for config file
    return configFile;
}

@end

UI Interaction Event

After the UI is dismissed from your application, a document event is broadcast. You can listen for this event to detect the UI dismissed.

document.addEventListener('allSDKViewsDismissed', () =>{
    console.log("All OneTrust Views dismissed")
}, false)

Get UI Data as JSON

After initialization, the data used to build a preference center or banner can be retrieved easily using the following methods. Each has a success and error handler, so if the download fails and there is no cached data, errors can be handled gracefully. This can also be used to determine whether or not OneTrust has the data required to operate offline (eg. if getBannerData does not return an error, at least one download has completed successfully and the required data is present to render a banner.)

window.OneTrust.getBannerData((data) => {
  console.log(`Banner Data = ${JSON.stringify(data)}`)
}, (error) => {
  console.error(`No banner data! \n Error: ${error}`)
})

window.OneTrust.getPreferenceCenterData((data) => {
  console.log(`Preference Center Data = ${JSON.stringify(data)}`)
}, (error) => {
  console.error(`No Preference Center data! \n Error: ${error}`)
})

When Consent Changes

There are two ways to get consent values:

• Query for Consent
• Listen to events for changes

Consent Values

OneTrust universally uses the following values for consent status:

Querying for Consent

To obtain the current consent status for a category, use the getConsentStatusForCategory method, which returns an Int.

window.OneTrust.getConsentStatusForCategory("C0004", (status) => {
  console.log("Queried consent status for C0004 is "+status)
})

Listening for Consent Changes

The OneTrust SDK emits events as consent statuses change. You must tell the platform code which events to listen for. Call this method for each category you wish to start observing.

window.OneTrust.observeChanges("C0004")

Once a category is being observed, an event will be fired whenever the consent for that category changes. The listener carries a payload with the categoryId as a string and the consentStatus as an integer.

document.addEventListener('C0004',(payload) => {
    console.log("The new status of "+payload.categoryId+" is now"+payload.consentStatus)
}, false)

Stop listening for consent changes by calling the following for each category you'd like to cancel.

window.OneTrust.stopObservingChanges("C0004")

Retrieving the Cached Data Subject Identifier

The Data Subject Identifier that OneTrust sets can be retrieved by calling the following method. If Consent Logging is enabled, you will be able to retrieve the receipt for any consent choices made by the user inside the Consent module.

window.OneTrust.getCachedIdentifier((identifier) => {
  console.log(`Data Subject Identifier is ${identifier}.`)
})

Pass OneTrust Consent to a WebView

If your application uses WebViews to present content and the pages rendered are running the OneTrust Cookies CMP, you can inject a JavaScript variable, provided by OneTrust, to pass consent from the native application to your WebView.

The JavaScript must be evaluated before the Cookies CMP loads in the webview, therefore, it is recommended to evaluate the JS early on in the WebView load cycle.

window.OneTrust.getOTConsentJSForWebview((js) => {
  //inject javascript into webview
})

Troubleshooting

Android minCompileSdk (31) challenges

As of May 31, 2022, Cordova only supports a minCompileSdk (30) however the underlying OneTrust Android SDK as of 6.36.0 release requires minCompileSdk (31). We've received reports that this discrepancy will cause builds to break during development.

OneTrust recommends utilizing pre-6.36.0 versions of the Android SDK that supports minCompileSdk (30) until Cordova is able to support this.

Unable to access OneTrust SDK methods after installing the plugin via NPM

Please verify you can view the OneTrust.js file located under the path: Plugins > cordova-plugin-onetrust-cmp > www > OneTrust.js. If you do not see that file, that is the root cause of the issue. To rectify, try removing and re-adding the plugin via npm.

For background, on download from npm, a Plugin.xml file should be included which sets up the window.OneTrust object to call methods on.

// exerpt from Plugin.xml

<js-module name="OneTrust" src="www/OneTrust.js">
  <clobbers target="OneTrust" />
  <merges target="cordova.plugins.OneTrust" />
</js-module>