Initialization

To successfully initialize and use the iOS and Android SDK, you must be aware of the requirements for each geographical location. Follow the recommendations in this article so you can deploy the ATS SDK quicker and faster with confidence.

Initialization

You must initialize the SDK prior to calling the SDK API. See the following guides to learn how:

Consent Requirements

Our SDK performs a geolocation check on an initialization attempt and uses that to determine internal logic.

  • For EU: In the EU consent is required and must be set (preferably by a CMP). Without consent, the SDK will not initialize and envelopes cannot be fetched from our backend. Our backend will drop requests with no consent.
  • For U.S.: Currently in the U.S. consent is not required. The SDK will read the value of the IAB CCPA string if it is set or provided. Our backend will allow requests with AND without the CCPA value. If CCPA value is provided, the SDK and backend will honor the value.
  • For other countries: LiveRamp provides an API that can be called to inform the SDK to proceed with initialization.
  • For iOS Only: In the coming version release of the iOS SDK, LiveRamp will require ATT consent to operate the traditional ATS workflow (fetching an envelope). If ATT consent for iOS is not explicitly granted by the user, the SDK will not fetch envelopes. In this case, on-device workflow for the SDK will be used instead. Keep yourself up-to-date for when this change will be implemented by checking out the Changelog.

Where Does the SDK Look for Consent?
LiveRamp follows the agreed-upon convention for storage/lookup of consent strings as outlined by the IAB.
In iOS, we check for consent values in NSUserDefaults / UserDefaults: https://developer.apple.com/documentation/foundation/nsuserdefaults
In Android, we check for consent values SharedPreferences : https://developer.android.com/reference/android/content/SharedPreferences
See "Use Cases" below to learn which values we consult for based on the location.

Use Cases

1. Handling EU Initialization (GDPR)

GDPR consent (mainly the TCFv2 string) is required for SDK operation in the EU. We do not support TCFv1.
Without a provided TCFv2 consent string available, the SDK will not initialize and our backend will drop all requests.
The following supported locations are considered as "EU" (more countries will be added):

  • France
  • Germany
  • Netherlands
  • Spain
  • United Kingdom
  • Italy
  • Romania
  • Poland
  • Belgium

If the SDK determines that you are initializing the SDK in one of the above locations, it will check for the below standard IAB values in the agreed upon specified location:

Value

Sample Values (Do not use outside of testing)

IABTCF_TCString

CPKZ42oPKZ5YtADABCENBlCgAP_AAAAAAAAAA wwAQAwgDDABADCAAA.YAAAAAAAA4AA

IABTCF_PurposeConsents

1111111111

IABTCF_VendorConsents

0000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000001

If any of the above values are not set, the SDK will not initialize and you will not be able to retrieve envelopes.

2. Handling US Initialization (CCPA)

The CCPA string (usp_string) is not required for SDK operation in the US. LiveRamp will respect and process the string only if it is provided.

  • If you choose to operate the SDK and require the CCPA string, note that we will check for the string regardless of what state the user is located in.
  • An SDK initialization from California and an initialization from New York are the same to the SDK. For instance, if the user has opted out (as indicated in the device'sUserDefaults or SharedPreferences), the SDK will initialize, and the envelope request will happen. However, the returned response will be empty.

Value

Sample Value (Do not use outside of testingt)

IABUSPrivacy_String

1YNN

If this value is not set, the SDK will not initialize and you will not be able to retrieve envelopes.

If you wish to operate the SDK without providing the CCPA string, see the third option below.

3. Handling All Other Initialization

This is the "catch-all" for the SDK, allowing you to initialize and operate the SDK with an "alternative" form of consent, where you provide the value to the SDK: true or false.
This method doesn't ensure you will get valid envelopes - our backend will only return envelopes for supported countries (not EU and US) that have been enabled by your LiveRamp representative below:

  • Argentina
  • Australia
  • Canada
  • Japan
  • Singapore
  • Brazil

📘

More Countries To Be Added

We are always working to expand into more countries. If you plan on operating the SDK in a country that is not listed above, please consult your LiveRamp account manager for more details.

If you're using this option, SDK will assume that you've somehow obtained user consent for that current location, and it's okay to initialize.
Android (java):
LRAtsManager.INSTANCE.setHasConsentForNoLegislation(true);
iOS (swift):
LRAts.shared.hasConsentForNoLegislation = true

Once this is set, you may then initialize the SDK.

If you wish to revoke consent at any time (like on a future SDK initialization), you may disallow future SDK initializations by setting the boolean value to false.
Android (java):
LRAtsManager.INSTANCE.setHasConsentForNoLegislation(false);
iOS (swift):
LRAts.shared.hasConsentForNoLegislation = false

Suggested Approach (Pseudocode)

To successfully utilize the SDK, we recommend the following:

  • Always call the SDK initialization method. The SDK will check to ensure it is allowed to load for that current geolocation.
  • If you don't plan on checking for CCPA in the US, call the method for setHasConsentForNoLegislation prior to initialization.
  • If you plan to operate the SDK in geos other than the US or the EU, call setHasConsentForNoLegislation prior to initialization.
if (doNotRequireCCPACheckInUS || supportOtherGeos) {
        setHasConsentForNoLegislation(true);
}
// Always call SDK initialization before you process
// an authentication event in your app.
initializeSDK();