3. Call the APIs

This page guides you through the Mobile SDK APIs you can utilize to help you retrieve envelopes more efficiently.

The SDK includes a standardized forced refresh mechanism that fetches fresh envelopes every 24 hours. You can also check the envelope settings in Console to see the envelope expiration time, enable logging mode, and others. See our Console documentation on Implementing ATS Mobile SDK to learn more.

📘

Need help with ATS Mobile SDK? Contact [email protected] to talk to a LiveRamp representative.

Methods

See all available methods you can use with ATS Mobile SDK below. Some methods listed are part of beta features and are not available out-of-the-box. Talk to your LiveRamp representative to learn more about these features.

To view the list of error codes and how to troubleshoot them, see "ATS Mobile SDK Error Codes".

getEnvelope

This method returns an envelope for the specified identifier. Note that phone numbers need to be normalized before passing to the SDK.

To retrieve a valid envelope, your ATS placement must already be approved. If the placement is unapproved, the SDK will return fake data which should only be used for testing. Information regarding the placement status can be found in the log output of the SDK.

❗️

LRCustomIdentifier not available for all publishers

Due to the complexity of the custom ID mapping process, LRCustomIdentifier is only available for selected publishers who must go through an extensive onboarding process. Please note that you cannot use this API out-of-the-box.

Parameters

Returns
No return parameter

Example

LRAtsManager.getEnvelope(
    LREmailIdentifier("[email protected]"),
    object : LREnvelopeCallback {
        override fun invoke(envelope: Envelope?, error: LRError?) {
            logD("getEnvelopeAPI: ${envelope?.envelope}")
        }
})

LRAtsManager.INSTANCE.getEnvelope(new LREmailIdentifier("[email protected]"), new LREnvelopeCallback() {
    @Override
    public void invoke(@Nullable Envelope envelope, @Nullable LRError lrError) {
        Log.d("Here's your envelope! ", envelope.getEnvelope());
    }
});

📘

You can verify if an envelope has been successfully fetched by using a network HTTP proxy tool (such as Charles), and filter for the api.rlcdn call.

getEnvelope(callback: LREnvelopeCallback)

This method returns stored envelope without passing any identifiers. To use this method, the envelopes must already be stored in the local database.

getDealIDs

🚧

This Method is Only Available in Closed Beta

ATS On-device is only available in closed beta and their methods will not work out-of-the-box.

If you want to be part of the closed beta release, contact your LiveRamp administrator to get ATS On-device enabled.

This method returns a list of Deal IDs and Deal ID status for the specified email. To retrieve valid Deal IDs, your ATS placement must already be approved. If the placement is unapproved, the SDK will return fake data which should only be used for testing. Information regarding the placement status can be found in the log output of the SDK.

An Integration Key generated in Console is required to retrieve a Deal ID for active deals.

Parameters

Returns

No return parameter

syncFilters

🚧

This Method is Only Available in Closed Beta

ATS On-device is only available in closed beta and their methods will not work out-of-the-box.

If you want to be part of the closed beta release, contact your LiveRamp administrator to get ATS On-device enabled.

This method starts the synchronization process of the library and updates the data used for generating Deal IDs.

Parameters

Returns

No return parameter

setHasConsentForNoLegislation

This method allows you to set consent flags for countries outside of EU and U.S. that are configured in Console.

Parameter

Returns
No return parameter

hasConsentForNoLegislation

This method returns a consent flag for countries outside of the U.S. and UK/EU that are configured in Console for the ATS placement. If the value is true, SDK will proceed without checking for consent.

The default value is false.

To set the value to true, refer to setHasConsentForNoLegislation.

Parameter
No parameter

Returns
Boolean

getSdkStatus

This method returns the current SDK state.

Returns
SDK status.

isDisabled

This property is used to control the status of the SDK. When set to ​true​​, the SDK becomes disabled. As a result, the APIs will not function and API calls will not be possible. Setting the property to ​false​ changes the SDK status to ​notInitialized​​ and re-initialization is required before API calls can be made again.

The default value is false.

Parameter

Returns
No return parameter

setAtsManagerCallback

This method sets callback for ATS Manager that is used for receiving events.

Parameter

Returns
No return parameter.

removeAtsManagerCallback

This method removes callback for ATS Manager that is used for receiving events.

Parameters
No parameter

Returns
No return parameter

resetSdk

This method resets SDK to its initial state.

Parameters
No parameter

Returns
No return parameter

getSdkVersion

This method returns current version of the SDK.

Parameter
No parameter

Returns
String

logeCSTForEnvelope

This method logs Enhanced Client-Side Tag (eCST) data to the server. To call this method successfully, the SDK must be in ready state and an envelope must be present.

Parameters

invalidateCache

📘

This method is only available from v3.1.0 onwards.

This method clears all cached envelope data= maintained by the SDK, forcing it to fetch fresh data. This method can be useful when you need the SDK to retrieve updated envelopes without performing a full reset. It uses a mutex to ensure that only one cache invalidation operation can run at a time. If the SDK is disabled, it logs a warning.

🚧

Use with Caution

The InvalidateCache method should be used with caution, as frequent cache invalidation may lead to increased network usage due to more frequent envelope fetches.

Parameters
No parameter

Returns
No return parameter

Classes

LRAtsConfiguration

This class is used to configure LRAts SDK during initialization.

LRAtsConfiguration object can be instantiated using one of the following constructors.

Using a constructor that accepts configID as a string:

LRAtsConfiguration(configID: String)

Using a constructor that accepts configID and apiKeyas strings:

LRAtsConfiguration(configID: String, apiKey: String?)

Using a constructor that accepts configID and apiKey as strings, and isTestMode and logToFileEnabled as boolean values:

LRAtsConfiguration(configID: String, apiKey: String?, isTestMode: Boolean, logToFileEnabled: Boolean)

Envelope

This class used to return envelopes for the specified identifier.