Init Best Practices

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 a 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: LiveRamp requires App Tracking Transparency (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.

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 U.S. Initialization (CCPA)

The CCPA string (usp_string) is not required for SDK operation in the U.S. 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 initialization from New York are the same to the SDK. For instance, if the user has opted out (as indicated in the device's UserDefaults 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 testing)
`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 U.S.) that have been enabled by your LiveRamp representative below:

Argentina
Australia
Canada
Japan
Singapore
Brazil

Note

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 method, 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 use 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 U.S., call the method for setHasConsentForNoLegislation prior to initialization.
If you plan to operate the SDK in geolocations other than the U.S. 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();