This article is a reference for the methods available in the Core API for the following platforms:
iOS
Android
Flutter
React Native
For reference documentation of the Event API for the same platforms, see Event API for apps.
For reference documentation for Unity, see Unity Core API or Unity Event API.
Initialization
initialize
Initialize SDK, loading configurations from the backend. After successfully completed consents can be collected. Should use isReady method to ensure initialization was successfuly complete(see below).
UsercentricsCore.configure(options: <UsercentricsOptions>)Usercentrics.initialize(appContext, <UsercentricsOptions>)Usercentrics.initialize(<UsercentricsOptions>);Usercentrics.configure(<UsercentricsOptions>);Usercentrics.Instance.Initialize((status) => { // Success: Returns UsercentricsReadyStatus object}, (errorMessage) => { // Failure: Returns non-localized error});Input parameters:
Inputs | Type | Notes |
|---|---|---|
options* | Defines the configuration of the SDK. | |
appContext [Android] | ApplicationContext | Application context |
For Unity:
Completion Blocks | Type | Notes |
|---|---|---|
status | Provides information needed to know what action to take next (show CMP banner to collect consent or apply already collected consent). | |
error | String | String with non-localized description. |
isReady
Asynchronous function checks if the Usercentrics SDK initialization is completed, safely handling both success and failure cases by invoking the appropriate callback.
UsercentricsCore.isReady { <UsercentricsReadyStatus> in
// Handle status
} onFailure: { <Error> in
// Handle error
}Usercentrics.isReady({
// Handle status
}, {
// Handle error
})final usercentricsReadyStatus = await Usercentrics.status;const usercentricsReadyStatus = await Usercentrics.status;Completion Blocks | Type | Notes |
|---|---|---|
status | This object provides a snapshot of the user's current consent status. | |
error [Android, iOS] | Error | Error object with non-localized description. |
Flutter and React Native
Completion Blocks | Type | Notes |
|---|---|---|
status | This object provides a snapshot of the user's current consent status. |
Features
restoreUserSession
Restore a user session from another Usercentrics supported platform.
UsercentricsCore.shared.restoreUserSession(controllerId: <String>, onSuccess: <(UsercentricsReadyStatus) -> Void>, onFailure: <(Error) -> Void>)Usercentrics.instance.restoreUserSession(controllerId = <String>, onSuccess = <(UsercentricsReadyStatus) -> Unit>, onFailure = <(Throwable) -> Unit>)final status = await Usercentrics.restoreUserSession(controllerId: <String>);const status = await Usercentrics.restoreUserSession(controllerId: <String>);Input | Type | Notes |
|---|---|---|
controllerID | String | A Usercentrics generated ID, used to identify a specific consent interaction. |
onSuccess | Callback<UsercentricsReadyStatus> | SDK has restored the user's consent attached to the controllerID provided. See Restore User Session |
onFailure | Callback | Handle non-localized error. |
Flutter and React Native
Outputs | Type | Notes |
|---|---|---|
status | This object provides a snapshot of the user's current consent status. See Restore User Session |
clearUserSession
Clears current user session without needing to initialize the SDK again.
UsercentricsCore.shared.clearUserSession(onSuccess: <(UsercentricsReadyStatus) -> Void>, onError: <(Error) -> Void>)Usercentrics.instance.clearUserSession(onSuccess = <(UsercentricsReadyStatus) -> Unit>, onError = <(Throwable) -> Unit>)final status = await Usercentrics.clearUserSession();const status = await Usercentrics.clearUserSession();Input | Type | Notes |
|---|---|---|
onSuccess | Callback<UsercentricsReadyStatus> | SDK has cleared the user's consent attached to the current session. See Clear User Session |
onError | Callback | Handle non-localized error. |
Flutter and React Native
Outputs | Type | Notes |
|---|---|---|
status | This object provides a snapshot of the user's current consent status. See Clear User Session |
getUserSessionData
Get the User's Session Data that can be injected in a WebView with Usercentrics Browser SDK.
let userSessionData = UsercentricsCore.shared.getUserSessionData()val userSessionData = Usercentrics.instance.getUserSessionData()final userSessionData = await Usercentrics.userSessionData;const userSessionData = await Usercentrics.getUserSessionData();Outputs | Type | Notes |
|---|---|---|
userSessionData | String | String used to pass consent to a WebView. See WebView Consent Continuity |
changeLanguage
Change the language of the texts on the banner to supported languages. See Select your language hierarchy.
UsercentricsCore.shared.changeLanguage(language: <String>, onSuccess: <() -> Void>, onFailure: <(Error) -> Void>)Usercentrics.instance.changeLanguage(language = <String>, onSuccess = <() -> Unit>, onFailure = <(Throwable) -> Unit>)await Usercentrics.changeLanguage(language: <String>);await Usercentrics.changeLanguage(language: <String>);Input | Type | Notes |
|---|---|---|
language | String | Language for content to be loaded on. e.g. "en", "de", "fr". |
onSuccess [Android, iOS] | Callback | Re-render your UI, as usual with the CMP data. Content now will be on the new language. |
onFailure [Android, iOS] | Callback | Handle non-localized error |
Always change language before rendering your UI
If you call this method after the UsercentricsUI has already been created, the new language will not be applied.
getABTestingVariant
Get the A/B testing active variant of the CMP, see A/B testing.
let testingVariant = UsercentricsCore.shared.getABTestingVariant()val testingVariant = Usercentrics.instance.getABTestingVariant()final testingVariant = await Usercentrics.aBTestingVariant;const testingVariant = await Usercentrics.getABTestingVariant();Outputs | Type | Notes |
|---|---|---|
testingVariant | String? | Get the A/B testing active string variant of the CMP. |
setABTestingVariant
Set the A/B testing active variant of the CMP, see A/B testing.
UsercentricsCore.shared.setABTestingVariant(variant: <String>)Usercentrics.instance.setABTestingVariant(variant: <String>)Usercentrics.setABTestingVariant(variant: <String>);await Usercentrics.setABTestingVariant(variant: <String>);Input | Type | Notes |
|---|---|---|
variant | String | Set the A/B testing active variant of the CMP. |
Build your own UI
getCMPData
Get all the available CMP Data which is necessary to build a custom UI CMP frontend.
let cmpData = UsercentricsCore.shared.getCMPData()val cmpData = Usercentrics.instance.getCMPData()final cmpData = await Usercentrics.cmpData;const cmpData = await Usercentrics.getCMPData();Outputs | Type | Notes |
|---|---|---|
CMPData | Data needed to building your own UI. |
acceptAll
Consent to all services.
let consents = UsercentricsCore.shared.acceptAll(consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.acceptAll(consentType = <UsercentricsConsentType>)final consents = await Usercentrics.acceptAll(consentType: <UsercentricsConsentType>);const consents = await Usercentrics.acceptAll(consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
denyAll
Reject consent to all services.
let consents = UsercentricsCore.shared.denyAll(consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.denyAll(consentType = <UsercentricsConsentType>)final consents = await Usercentrics.denyAll(consentType: <UsercentricsConsentType>);const consents = await Usercentrics.denyAll(consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
saveDecisions
Saves consent decisions and allows partial consent, i.e. consent to some services and reject consent for some services.
let consents = UsercentricsCore.shared.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.saveDecisions(decisions = <[UserDecision]>, consentType = <UsercentricsConsentType>)final consents = await Usercentrics.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);const consents = await Usercentrics.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
decisions | [UserDecision] | List of every service's templateID and the consent as a Bool. |
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
Interaction Analytics
Track
Track user events if you are building your own UI, and want to see these events in the Usercentrics Analytics Dashboard.
let consents = UsercentricsCore.shared.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.saveDecisions(decisions = <[UserDecision]>, consentType = <UsercentricsConsentType>)final consents = await Usercentrics.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);const consents = await Usercentrics.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
event | UsercentricsAnalyticsEventType | Track analytics events when building a Custom UI or you wish to track events with a third party tool. |
UsercentricsAnalyticsEventType
List of trackable events.
Event | Event | Notes |
|---|---|---|
CMP_SHOWN | cmpShown | The banner was displayed to the user. It doesn't matter which layer. |
ACCEPT_ALL_FIRST_LAYER | acceptAllFirstLayer | The Accept All button was pressed from the first layer. |
DENY_ALL_FIRST_LAYER | denyAllFirstLayer | The Deny All button was pressed from the first layer. |
SAVE_FIRST_LAYER | saveFirstLayer | The Save button was pressed from the first layer. Save is mainly used for granular decisions. |
ACCEPT_ALL_SECOND_LAYER | acceptAllSecondLayer | The Accept All button was pressed from the second layer. |
DENY_ALL_SECOND_LAYER | denyAllSecondLayer | The Deny All button was pressed from the second layer. |
SAVE_SECOND_LAYER | saveSecondLayer | The Save button was pressed from the second layer. Save is mainly used for granular decisions. |
IMPRINT_LINK | imprintLink | The Imprint link/button was pressed. |
MORE_INFORMATION_LINK | moreInformationLink | The More Information link/button was pressed. This button is usually used to navigate from first layer to second layer. |
PRIVACY_POLICY_LINK | privacyPolicyLink | The Privacy policy link/button was pressed. |
CCPA_TOGGLES_ON | ccpaTogglesOn | The CCPA toggle was set to on. |
CCPA_TOGGLES_OFF | ccpaTogglesOff | The CCPA toggle was set to off. |
TCF 2.2-specific methods
getTCFData
Get the data that needs to be disclosed to the end-user if TCF is enabled.
UsercentricsCore.shared.getTCFData() { tcfData in
// handle data
}Usercentrics.instance.getTCFData { tcfData ->
// handle data
}final tcfData = await Usercentrics.tcfData;const tcfData = await Usercentrics.getTCFData();Outputs | Type | Notes |
|---|---|---|
TCFData | IAB's Transparency & Consent CMP Content. See IAB Data Source |
getAdditionalConsentModeData
Get Google's Additional Consent Mode Data, see Google Cosent Mode.
let additionalConsentData = UsercentricsCore.shared.getAdditionalConsentModeData()val additionalConsentData = Usercentrics.instance.getAdditionalConsentModeData()final additionalConsentModeData = await Usercentrics.additionalConsentModeData;const additionalConsentModeData = await Usercentrics.getAdditionalConsentModeData();Outputs | Type | Notes |
|---|---|---|
additionalConsentData | Retrieves the Google's Additional Consent String and the List of consented and not consented Ad Tech Providers. |
setCMPId
Set the CMP ID value required by IAB for custom UI.
UsercentricsCore.shared.setCMPId(id: <String>)Usercentrics.instance.setCMPId(id = <String>)await Usercentrics.setCmpIdForTCF(id: <String>);await Usercentrics.setCMPId(id: <String>);Inputs | Type | Notes |
|---|---|---|
CMPId | Int | When building your own UI for TCF 2.2. You need to pass the CMPID given to you by the IAB, in order for your solution to be compliant. |
acceptAllForTCF
Consent to all services, used only for TCF framework.
let consents = UsercentricsCore.shared.acceptAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.acceptAllForTCF(fromLayer = <TCFDecisionUILayer>, consentType = <UsercentricsConsentType>)final consents = await Usercentrics.acceptAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>);const consents = await Usercentrics.acceptAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
fromLayer | Enum | Layer in which consent was collected: firstLayer: First banner layer. secondLayer: Second banner layer. |
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
denyAllForTCF
Reject consent to all services, used only for TCF framework.
let consents = UsercentricsCore.shared.denyAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>) val consents = Usercentrics.instance.denyAllForTCF(fromLayer = <TCFDecisionUILayer>, consentType = <UsercentricsConsentType>)final consents = await Usercentrics.denyAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>);const consents = await Usercentrics.denyAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
fromLayer | Enum | Layer in which consent was collected: firstLayer: First banner layer. secondLayer: Second banner layer. |
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
saveDecisionsForTCF
Saves consent decisions and allows partial consent, i.e. consent to some services and reject consent for some services, used only for TCF framework.
let consents = UsercentricsCore.shared.saveDecisionsForTCF(tcfDecisions: <TCFUserDecisions>, fromLayer: <TCFDecisionUILayer>, serviceDecisions: <[UserDecision]>, consentType: <UsercentricsConsentType>)val consents = Usercentrics.instance.saveDecisionsForTCF(tcfDecisions = <TCFUserDecisions>, fromLayer = <TCFDecisionUILayer>, serviceDecisions = <[UserDecision]>, consentType = <UsercentricsConsentType>)final consents = await Usercentrics.saveDecisionsForTCF(tcfDecisions: <TCFUserDecisions>, fromLayer: <TCFDecisionUILayer>, serviceDecisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);const consents = await Usercentrics.saveDecisionsForTCF(tcfDecisions: <TCFUserDecisions>, fromLayer: <TCFDecisionUILayer>, serviceDecisions: <[UserDecision]>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
tcfDecisions | [TCFUserDecision] | List of every purpose and specialFeature with values for consent and legitimate interest as Bool and respective Vendors. |
fromLayer | Enum | Layer in which consent was collected: firstLayer: First banner layer. secondLayer: Second banner layer. |
decisions | [UserDecision] | List of every service's templateID and the consent as a Bool. |
consentType | Enum |
|
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
CCPA-specific methods
getUSPData
Get the User's CCPA consent data.
let uspData = UsercentricsCore.shared.getUSPData()val uspData = Usercentrics.instance.getUSPData()final ccpaData = await Usercentrics.ccpaData;const ccpaData = await Usercentrics.getCCPAData();Outputs | Type | Notes |
|---|---|---|
USPData | CCPAData | US Privacy String information |
saveOptOutForCCPA
Save service and CCPA decisions.
let ccpaConsents = UsercentricsCore.shared.saveOptOutForCCPA(isOptedOut: <Bool>, consentType: <UsercentricsConsentType>)val ccpaConsents = Usercentrics.instance.saveOptOutForCCPA(isOptedOut = <Bool>, consentType = <UsercentricsConsentType>)final ccpaConsents = await Usercentrics.saveOptOutForCCPA(isOptedOut: <Bool>, consentType: <UsercentricsConsentType>);const ccpaConsents = await Usercentrics.saveOptOutForCCPA(isOptedOut: <Bool>, consentType: <UsercentricsConsentType>);Input | Type | Notes |
|---|---|---|
isOptedOut | Bool | Pass the user's response to the statement: "Do Not Sell My Personal Information". True: Do not track or sell user's information. False: You are allowed to track and sell user's information. |
consentType | Enum | Explicit: Consent was collected from a explicit action from the user. e.g. Button action. Implicit: Consent was collected without a explicit action of the user. e.g User can close or ignore the banner without giving a choice. Please make sure you consult with your Data Protection Officer before using this case. |
Output | Type | Notes |
|---|---|---|
consents | List of services with consent choices. |
Helpers
shouldCollectConsent
This method returns true or false depending if the consent needs to be collected from the user.
UsercentricsCore.shared.shouldCollectConsent()Usercentrics.instance.shouldCollectConsent()Outputs | Type | Notes |
|---|---|---|
shouldCollectConsent | Bool | True, if consent has never been collected or some service has changed thus requiring a consent update. False, if consent has been collected and no update is required. |
getConsents
Retrieves list with consents.
UsercentricsCore.shared.getConsents()Usercentrics.instance.getConsents()await Usercentrics.consents;await Usercentrics.getConsents();Outputs | Type | Notes |
|---|---|---|
consents | List of Services with consent choices. |
getControllerId
Retrieves a Usercentrics generated ID that can uniquely identify a consent, can be correlated with specific users. See Restore User Session.
UsercentricsCore.shared.getControllerId()Usercentrics.instance.getControllerId()await Usercentrics.controllerId;await Usercentrics.getControllerId();Outputs | Type | Notes |
|---|---|---|
controllerID | String | A Usercentrics generated ID, used to identify a specific consent session. |
Objects
UsercentricsOptions
CMP configuration. Use the empty or [settingsId] constructor for convenience.
Property | Type | Notes |
|---|---|---|
settingsID | String | A Usercentrics generated ID, used to identify a unique CMP configuration. |
defaultLanguage | String | Selected based on our language selection hierarchy. This property defines the language used to render the banner. e.g. "en", "de", "fr". |
version | String | To freeze the configuration version shown to your users, you may pass a specific version here. You may find an overview of all versions in the Admin Interface under Configuration > History > Settings History > Version (Column) or Implementation > Script Tag > Version History. e.g. "3.0.4". Passing "latest" (default) will fetch the latest version of your CMP configuration. Passing "preview" will fetch the latest draft of your CMP configuration. |
timeoutMillis | Int | Timeout for network requests in milliseconds. We do NOT recommend overwriting this field unless absolutely necessary or for debugging reasons, as well as using any values under 5,000 ms (5s). Default is 10,000 ms (10s). |
loggerLevel | Enum | Provides a set of logs for operations being executed in the SDK. debug: includes every other level, warning: non-problematic operations, error: relevant logs to any blocking problems and none (default). |
rulesetId | String | A Usercentircs generated ID, used to identify a bundle of CMP configurations (Ruleset) to be used depending on the user's location. |
consentMediation | Bool | Enable Consent Mediation, an automated way to pass consent to 3rd party frameworks. |
initTimeoutMillis | Int | Timeout for SDK initialization. Minimum value is 5,000ms (5s) and the Default value is 10,000 ms (10s). |
UsercentricsReadyStatus
This object provides a snapshot of the user's current consent status.
Property | Type | Notes |
|---|---|---|
shouldCollectConsent | Bool | True, if consent has never been collected or some service has changed thus requiring a consent update. False, if consent has been collected and no update is required. |
consents | List of Services with consent choices. | |
geolocationRuleset | Object containing information about Geolocation Rulesets, when enabled in the account. | |
location | Current location of User. |
UsercentricsServiceConsent
The current consent status of a specific service.
Property | Type | Notes |
|---|---|---|
templateId | String | ID used to match a service with frameworks running on your app. See Applying Service Consent. |
status | Bool | Consent status given to this specific service. |
dataProcessor | String | Name of entity processing the data that was collected via this service. |
version | String | Legal template version. See Service Settings. |
category | String | The corresponding category of this service |
GeolocationRuleset
Contains information about Geolocation Rulesets, when enabled in the account.
Property | Type | Notes |
|---|---|---|
activeSettingsId | String | Given a Ruleset can contain multiple Settings IDs, this property will have the value of the active one, chosen given User's location. |
bannerRequiredAtLocation | Bool | Rulesets can be configured to not show the CMP in some locations, this property will indicate wether the banner is required to be displayed or not. |
UsercentricsLocation
Contains information about the current location of the user.
Property | Type | Notes |
|---|---|---|
countryCode | String | The country associated with the User's IP address. This is a Unicode CLDR region code, such as US or FR. (For most countries, these codes correspond directly to ISO-3166-2 codes. |
regionCode | String | Region, e.g. a province or state, of the country associated with the User's IP address. This is a Unicode CLDR subdivision ID, such as USCA or CAON. (These Unicode codes are derived from the subdivisions defined by the ISO-3166-2 standard. |
UsercentricsCMPData
Contains CMP related data. This data can be used to build a custom UI CMP frontend.
Property | Type | Notes |
|---|---|---|
settings | UsercentricsSettings | CMP settings and content properties needed to render your own UI. See Building your own UI. |
services | [UsercentricsService] | List of services. |
categories | [UsercentricsCategory] | List of categories. |
userLocation | Object exposing user's general location: regionCode, countryCode and countryName. | |
legalBasis | Object containing Legal Basis localization data. | |
activeVariant | Enum | Provides active Legal Framework: default solution for GDPR, LGPD, etc., ccpa solution for ccpa (California/US), tcf solution for IAB's Transparency & Consent Framework 2.0. |
LegalBasisLocalization
Contains information about translation of CMP text as well of a map of the legal basis.
Property | Type | Notes |
|---|---|---|
labelsAria | TranslationAriaLabels | An object that contains description for some of the UI labels . |
data | Map | The key-value map represents pairs where each key is a shorthand reference to a specific legal ground or regulation, |
AdditionalConsentModeData
Contains Google's Additional Consent Mode Data.
Property | Type | Notes |
|---|---|---|
acString | String | A String that represents the consented and disclosed Google Ad Technology Providers (ATPs), as defined by Google. |
adTechProviders | List<AdTechProvider> | Represents the List of the defined ATPs. |
TCFData
TCF framework related data.
Inputs | Type | Notes |
|---|---|---|
CCPA Data
CCPA framework related data.
Inputs | Type | Notes |
|---|---|---|
AdTechProvider
Contains information about an Ad Tech Provider.
Property | Type | Notes |
|---|---|---|
id | Int | ATP Identifier. |
name | String | ATP Name. |
privacyPolicyUrl | String | ATP Privacy Policy URL. |
consent | Boolean | Consent given to the ATP. |