Migrating from Web SDK

OneTrust is sunsetting the Web SDK product July 31, 2021. For more information on the deprecation plans, please see myOneTrust article.

Migration Workflow Steps

• Integrate the SDK
• Initialize SDK & Download Data
• Presenting a Banner or Preference Center
• UI Interaction Listeners
• Actioning on Consent
• IAB TCF
• IAB CCPA US Privacy
• Methods

Before You Begin

Make sure to re-publish

The Web SDK publish is a separate action from the Native SDK publish. If you publish changes to Web SDK, they will not be reflected on Native SDK. You’ll need to republish your application in the OneTrust account. Publishing creates a series of JSON files on the OneTrust CDN for the Native SDK to retrieve.

Things to know about Native SDK versioning

In the Native SDK, versioning is very important. The version of the SDK that is implemented on your application needs to match the version of the JSON published from the OneTrust account.

For example: If you publish a 6.12.0 JSON, you must use the 6.12.0 SDK. Once implemented and live in production, the OneTrust admin UI allows you to publish updates to previously published versions. This means that if you need to make changes from the OneTrust admin UI (e.g. templates, geolocation rules) and have them update in your live in production app, you can publish those changes to a previously published version of the SDK for those changes to be reflected to your users, in most cases, without an update to the SDK or your app.

Integrate the SDK

iOS

You will need to integrate the SDK directly from the .framework or .XCFramework file, or from Cocoapods. The import statements will need to be changed to:

import OTPublishersHeadlessSDK

Android

Integrate the OneTrust SDK directly from the .aar file, or with mavenCentral per the our developer documentation.

Note the Native SDK has different dependencies than the Web SDK.

// Legacy Web SDK Dependencies
implementation 'com.squareup.retrofit2:converter-scalars:2.8.1'
implementation 'androidx.work:work-runtime:2.3.4'
implementation 'androidx.browser:browser:1.2.0'

// New Native SDK Dependencies
implementation 'com.squareup.retrofit2:converter-scalars:2.6.1'
implementation 'androidx.work:work-runtime:2.3.4'
implementation 'com.google.android.material:material:1.1.0'
implementation 'com.github.bumptech.glide:glide:4.9.0'
implementation 'androidx.browser:browser:1.2.0'

Because this is a new package, the import statements will change as well. Remove the old dependencies, such as import com.onetrust.otpublisherssdk.OTPublishersSDK; add the new import statements as needed.

For example:

import com.onetrust.otpublishers.headless.Public.OTCallback;
import com.onetrust.otpublishers.headless.Public.OTPublishersHeadlessSDK;

Initialize SDK & Download Data

In the Web SDK, initialization and data downloads were two separate functions. In the Native SDK, these are combined into a single function startSDK().

In the Web SDK, there were 2 different ways to initialize and download data:

• downloadOneTrustData()
• loadPreferenceCenter(false)

In this section, we will describe how to migrate both of these approaches for both iOS and Android.

Before You Begin

The initialization arguments for the Web SDK vary slightly from the Native SDK.

In the Web SDK, you pass these values:

• JSURL
• Application ID

In the Native SDK, you need to pass these values:

• StorageLocation
  • The StorageLocation can be gathered from the JSURL's hostname. If your JSURL is https://cdn.cookielaw.org/scripttemplates/otSDKStub.js, your StorageLocation is cdn.cookielaw.org.
  • For other StorageLocation values, further information can be found here.
• Application ID (which is same as above)
• Language Code (example “en” for English, this is to translate content).
• Params These are additional options to modify the initialization. In order to migrate consent given in the Web SDK to the Native SDK, an additional call will have to be added. See below for more detail.

Migrating downloadOneTrustData() to startSDK()

iOS Web SDK

//Legacy Code
OTPublishersSDK.shared.initializeOneTrustPublishersSDK(jsUrl: "[yourJSURL]", applicationId: "[YourAppId]")
OTPublishersSDK.shared.downloadOneTrustData() { (status, error)
	in NSLog("SDK Download status \(status) and error \(String(describing: error))")
}

Replace with this in iOS Native SDK:

OTPublishersHeadlessSDK.shared.startSDK(
	storageLocation: "[yourStorageLocation]",
	domainIdentifier: "[yourAppId]",
	languageCode: "en",
	params: params) { response in
		print("status: \(response.status)")
		print("result: \(response.responseString ?? "")")
		print("error: \(response.error ?? "")")
	}

Android Web SDK

//Legacy Code
otPublishersSDK = new OTPublishersSDK(this);
otPublishersSDK.initializeOneTrustPublishersSDK("[yourJSURL]", "[yourAppID]");
otPublishersSDK.downloadOneTrustData(this);

Replace with this in Android Native SDK:

OTPublishersHeadlessSDK otPublishersHeadlessSDK = new OTPublishersHeadlessSDK(this);

otPublishersHeadlessSDK.startSDK("[yourStorageLocatoin]", "[yourAppId]", languageCode, null, new OTCallback() {
	@Override
		public void onSuccess(@NonNull OTResponse otSuccessResponse) {
			// Optional: Save the entire response data in a App variable
			String otData = otSuccessResponse.getResponseData();
		}
	
	@Override
		public void onFailure(@NonNull OTResponse otErrorResponse) {
			int errorCode = otErrorResponse.getResponseCode();
			String errorDetails = otErrorResponse.getResponseMessage();

			// Optional: Print the entire error response to Logs
			Log.i(LOG_TAG, otErrorResponse.toString());
		}
});

Migrating loadPreferenceCenter(false) to startSDK()

iOS Web SDK

OTPublishersSDK.shared.initializeOneTrustPublishersSDK(jsUrl: "[yourJSURL]", applicationId: "[YourAppId]")
OTPublishersSDK.shared.loadPreferenceCenter(false) { (status, error) in
	NSLog("SDK status \(status) and error \(String(describing: error))")
}

Replace with this in iOS Native SDK:

OTPublishersHeadlessSDK.shared.startSDK(
	storageLocation: "[yourStorageLocation]",
	domainIdentifier: "[yourAppId]",
	languageCode: "en",
	params: params) { response in
		print("status: \(response.status)")
		print("result: \(response.responseString ?? "")")
		print("error: \(response.error ?? "")")

		if (response.status) {
			// Common: Use setupUI() method to show a banner to user if shouldShowBanner = true
			// Note: setupUI() computes shouldShowBanner. No need to call shouldShowBanner().
			OTPublishersHeadlessSDK.shared.setupUI([currentViewController], UIType: .banner)
		}
	}

Android Web SDK

otPublishersSDK = new OTPublishersSDK(this);
otPublishersSDK.initializeOneTrustPublishersSDK("[yourJSURL]", "[yourAppID]");
startActivityForResult(new OTPublishersSDK(this).loadPreferenceCenter(false), 1);

Replace with this in Android Native SDK:

OTPublishersHeadlessSDK otPublishersHeadlessSDK = new OTPublishersHeadlessSDK(this);

otPublishersHeadlessSDK.startSDK("[yourStorageLocation]", "[yourAppId]", languageCode, null, new OTCallback() {
	@Override
	public void onSuccess(@NonNull OTResponse otSuccessResponse) {
		// Common: Use setupUI() method to show a banner to user if shouldShowBanner = true
		// Note: setupUI() computes shouldShowBanner. No need to call shouldShowBanner().
		otPublishersHeadlessSDK.setupUI([currentAppCompatActivity],UIType.BANNER)
	}
	
	@Override
	public void onFailure(@NonNull OTResponse otErrorResponse) {
		int errorCode = otErrorResponse.getResponseCode();
		String errorDetails = otErrorResponse.getResponseMessage();

		// Optional: Print the entire error response to Logs
		Log.i(LOG_TAG, otErrorResponse.toString());
	}
});

Migrating Consent from Web SDK to Native SDK

Note: This method change is available in versions 6.17.0 or above.

The syncWebSDKConsent property of the OTSdkParams object handles the migration of consent from the Web SDK to the Native SDK. Once this property is set, any users' consent gathered previously via the Web SDK will be migrated and reflected in Preference Center of the Native SDK. The migration will also prevent a banner from being shown again if the user's Web SDK consent is still valid.

iOS

let sdkParams = OTSdkParams()
sdkParams.syncWebSDKConsent(true)
//in startSDK call, pass this in as the params argument

Android

OTSdkParams sdkParams = OTSdkParams.SdkParamsBuilder.newInstance()
	.setSyncWebSDKConsent(true)
	.build();
//in startSDK call, pass this in as the params argument

Presenting a Banner or Preference Center

• With the Web SDK, loadPreferenceCenter(false) considers the shouldShowBanner logic and decides whether or not to show/hide the banner once the data has been successfully downloaded.
• With the Native SDK, setupUI() considers the shouldShowBanner logic and you have flexibility to decide to render a .banner, .preferenceCenter, or .none once the data has been successfully downloaded.

iOS Native SDK

Showing a Banner based on shouldShowBanner

OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .banner) 
// Here, self is an instance of UIViewController

On iOS, you must call setupUI() at least once before any views Banner/PC views are rendered. This is so SDK knows what view controller to present its UI on.

Showing a Preference Center:
For Web SDK, showing a Preference Center is done using loadPreferenceCenter(true).
For Native SDK, showing a Preference Center is done using showPreferenceCenterUI().
Similarly, you can also call showBannerUI to present the banner again manually.

OTPublishersHeadlessSDK.shared.showBannerUI() //show banner
OTPublishersHeadlessSDK.shared.showPreferenceCenterUI() //show preference center

Android Native SDK

In order to populate the cookie banner and preference center, you must pass in an instance of AppCompatActivity or FragmentActivity.

Showing a Banner based on shouldShowBanner

new OTPublishersHeadlessSDK(this).setupUI(RenderNativeUIActivity.this, UIType.BANNER);

Showing a Preference Center:
For Web SDK, showing a Preference Center is done using loadPreferenceCenter(true).
For Native SDK, showing a Preference Center is done using showPreferenceCenterUI().
Similarly, you can also call showBannerUI to present the banner again manually. Again, both require an AppCompatActivity or a FragmentActivity.

new OTPublishersHeadlessSDK(this).showBannerUI(RenderNativeUIActivity.this); //show cookie banner
new OTPublishersHeadlessSDK(this).showPreferenceCenterUI(RenderNativeUIActivity.this); //show preference center

UI Interaction Listeners

The Native SDK includes a wide selection of UI interaction listeners to allow more flexibility to developers to perform actions when certain aspects of the UI have been interacted with. For more information, see the following:

• iOS Interaction Listeners
• Android Interaction Listerners

It's not recommended for developers to use UI Interaction Listeners to action on a User's consent updates. Instead, we recommend following the Listening for Consent Changes section below.

Actioning on Consent

Listening for Consent Changes

If your application is listening for consent changes with NotificationObservers or BroadcastReceivers, minimal changes are needed to continue the same functionality.

UI Interaction Listeners may be useful if you are listening for changes to the UI state. This is net new functionality, but often provides a level of customization that the Web SDK did not (iOS/Android documentation.)

iOS

• No changes should be required in iOS
• Notifications with Notification.Name equal to the category ID or SDK ID are sent after the user confirms their choices

Android

• On Android, the Native SDK continues broadcasting with an Intent equal to the SDK GUID (these GUIDs will remain unchanged).
  • If you are only listening to intents with the value of an SDK GUID, no changes are required
• The Native SDK introduces a broadcast by Category ID (eg. C0002).
  • If you were previously listening for the BroadcastServiceKeys.USER_INTERACTION_STATUS and querying for the category status inside of the BroadcastReceiver, you will now need to listen for individual category IDs.
• On Android, the BroadcastServiceKeys.EVENT_STATUS constant has remained the same inside of the BroadcastReceivers you are registering.

Querying for Consent

The query for consent methods have direct counterparts in Web and Native. They all continue to return integers and can be directly replaced. See the Methods section below for more info.

IAB TCF

If your application previously used the Web SDK for IAB TCF, IAB TCF setup is configured by template using the Template Builder. The Native SDK takes care of the rest based on user interaction.

See here for more information.

IAB CCPA

If your application is utilizing the IAB CCPA US Privacy String, the initialization and update methods can be removed from your code base entirely. The Native SDK (as of version 6.12.0), manages writing the IAB's US Privacy String based on your IAB CCPA template configuration using Template Builder.

See here for more information.

Methods

The following methods have a 1:1 matchup between the Web and Native SDKs. You might not be using all these methods with Web SDK today, however it's important to see where the differences are in case you do, otherwise there will be build issues. Most of the methods are the same as before, while some have minor differences in naming convention.

iOS

The methods below can be called on the singleton classes above.

Android

The below methods can be called on an instance of either class above.