Web SDK (Deprecated)
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.
- The StorageLocation can be gathered from the JSURL's hostname. If your JSURL is https://cdn.cookielaw.org/scripttemplates/otSDKStub.js, your
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()
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()
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 theshouldShowBanner
logic and decides whether or not to show/hide the banner once the data has been successfully downloaded. - With the Native SDK,
setupUI()
considers theshouldShowBanner
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:
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 theBroadcastReceiver
, you will now need to listen for individual category IDs.
- If you were previously listening for the
- On Android, the
BroadcastServiceKeys.EVENT_STATUS
constant has remained the same inside of theBroadcastReceivers
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
Web SDK Prefix | Native SDK Prefix |
---|---|
OTPublishersSDK.shared | OTPublishersHeadlessSDK.shared |
The methods below can be called on the singleton classes above.
Web SDK | Native SDK |
---|---|
shouldShowBanner() | Same |
isBannerShown() | Same |
getConsentStatusForGroupId("[CatId]") | getConsentStatus(forCategory: “[CatID]“) |
getConsentStatus(sdkId:"[SDK GUID]") | getConsentStatus(forSDKId: “[SDKGuid]“) |
overrideDataSubjectIdentifier(“dsi”) | Same |
setDataSubjectIdentifier(“dsi”) | Same |
writeLogsToFile() | Same |
optIntoSaleOfData() | Same |
optOutOfSaleOfData() | Same |
Android
Web SDK | Native SDK |
---|---|
new OTPublishersSDK(this) | new OTPublishersHeadlessSDK(this) |
The below methods can be called on an instance of either class above.
Web SDK | Native SDK |
---|---|
shouldShowBanner() | Same |
isBannerShown() | Same |
getConsentStatusForGroupId("[CatId]") | Same |
getConsentStatusForSDKId("[SDK GUID]") | Same |
overrideDataSubjectIdentifier(“dsi”) | Same |
setDataSubjectIdentifier(”dsi”) | Same |
optOutOfSaleOfData() | Same |
optInToSaleOfData() | Same |
writeLogsToFile(false,false) | Same |
Updated 8 months ago