Skip to content

UsercentricsCore API

Initialization

Init

UsercentricsCore.configure(options: <UsercentricsOptions>)
Usercentrics.initialize(appContext, <UsercentricsOptions>)
Inputs Type Notes
options* UsercentricsOptions Defines the configuration of the SDK.

isReady

UsercentricsCore.isReady { <UsercentricsReadyStatus> in
    // Handle status
} onFailure: { <Error> in
    // Handle error
}
Usercentrics.isReady({
    // Handle status
}, {
    // Handle error
})
Completion Blocks Type Notes
status UsercentricsReadyStatus Provides information needed to know what action to take next. Show CMP banner to collect consent or apply already collected consent.
error Error Error object with non-localized description.

Reset

UsercentricsCore.reset()
Usercentrics.reset()
Usercentrics.reset();
Usercentrics.reset();
Resetting the SDK

Use reset() to clean all local storage and release the initialized instance. You will need to initialize the SDK again after a reset. Make sure you validate the expected behaviour, before using reset in production.

Features

restoreUserSession

UsercentricsCore.shared.restoreUserSession(controllerId: <String>, onSuccess: <(UsercentricsReadyStatus) -> Void>, onFailure: <(Error) -> Void>)
Usercentrics.instance.restoreUserSession(controllerId = <String>, onSuccess = <(UsercentricsReadyStatus) -> Unit>, onFailure = <(Throwable) -> Unit>)
Input Type Notes
controllerID String A Usercentrics generated ID, used to identify a specific user.
onSuccess Callback SDK has restored the user's consent attached to the controllerID provided. See Restore User Session
onFailure Callback Handle non-localized error

getUserSessionData

UsercentricsCore.shared.getUserSessionData()
Usercentrics.instance.getUserSessionData()
Outputs Type Notes
userSessionData String String used to pass consent to a WebView. See WebView Consent Continuity

changeLanguage

UsercentricsCore.shared.changeLanguage(language: <String>, onSuccess: <() -> Void>, onFailure: <(Error) -> Void>)
Usercentrics.instance.changeLanguage(language = <String>, onSuccess = <() -> Unit>, onFailure = <(Throwable) -> Unit>)
Input Type Notes
language String Language for content to be loaded on. e.g. "en", "de", "fr".
onSuccess Callback Re-render your UI, as usual with the CMP data. Content now will be on the new language.
onFailure 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

UsercentricsCore.shared.getABTestingVariant()
Usercentrics.instance.getABTestingVariant()

setABTestingVariant

UsercentricsCore.shared.setABTestingVariant(variant: <VariantName>)
Usercentrics.instance.setABTestingVariant(<VariantName>)

Build your own UI

getCMPData

let CMPData = UsercentricsCore.shared.getCMPData()
val CMPData = Usercentrics.instance.getCMPData()
Outputs Type Notes
CMPData UsercentricsCMPData Data needed to building your own UI.

acceptAll

let consents = UsercentricsCore.shared.acceptAll(consentType: <UsercentricsConsentType>)
val consents = Usercentrics.instance.acceptAll(consentType = <UsercentricsConsentType>)
Input Type Notes
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 [UsercentricsServiceConsent] List of Services with consent choices.

denyAll

let consents = UsercentricsCore.shared.denyAll(consentType: <UsercentricsConsentType>)
val consents = Usercentrics.instance.denyAll(consentType = <UsercentricsConsentType>)
Input Type Notes
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 [UsercentricsServiceConsent] List of Services with consent choices.

saveDecisions

let consents = UsercentricsCore.shared.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>)
val consents = Usercentrics.instance.saveDecisions(decisions = <[UserDecision]>, consentType = <UsercentricsConsentType>)
Input Type Notes
decisions [UserDecision] List of every service's templateID and the consent as a Bool.
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 [UsercentricsServiceConsent] List of Services with consent choices.

Interaction Analytics

Track

UsercentricsCore.shared.track(event: <[UsercentricsAnalyticsEventType]>)
Usercentrics.instance.track(<UsercentricsAnalyticsEventType>)
Input Type Notes
event [UsercentricsAnalyticsEventType] Track analytics events for Custom UI

Events

[iOS] Event [Android] Event Notes
.cmpShown .CMP_SHOWN The banner was displayed to the user. It doesn't matter which layer.
.acceptAllFirstLayer .ACCEPT_ALL_FIRST_LAYER The Accept All button was pressed from the first layer.
.denyAllFirstLayer .DENY_ALL_FIRST_LAYER The Deny All button was pressed from the first layer.
.saveFirstLayer .SAVE_FIRST_LAYER The Save button was pressed from the first layer. Save is mainly used for granular decisions.
.acceptAllSecondLayer .ACCEPT_ALL_SECOND_LAYER The Accept All button was pressed from the second layer.
.denyAllSecondLayer .DENY_ALL_SECOND_LAYER The Deny All button was pressed from the second layer.
.saveSecondLayer .SAVE_SECOND_LAYER The Save button was pressed from the second layer. Save is mainly used for granular decisions.
.imprintLink .IMPRINT_LINK The Imprint link/button was pressed.
.moreInformationLink .MORE_INFORMATION_LINK The More Information link/button was pressed. This button is usually used to navigate from first layer to second layer.
.privacyPolicyLink .PRIVACY_POLICY_LINK The Privacy policy link/button was pressed.

TCF 2.0 Specific Methods

getTCFData

UsercentricsCore.shared.getTCFData() { tcfData in
    // handle data
}
Usercentrics.instance.getTCFData { tcfData ->
    // handle data
}
Outputs Type Notes
TCFData TCFData IAB's Transparency & Consent CMP Content. See IAB Data Source

getTCString

UsercentricsCore.shared.getTCFData() { tcfData in
    let tcString = tcfData.tcString
}
Usercentrics.instance.getTCFData { tcfData ->
    val tcString = tcfData.tcString
}
Inputs Type Notes
TCString String IAB's Transparency & Consent String

setCMPId

UsercentricsCore.shared.setCMPId(id: <String>)
Usercentrics.instance.setCMPId(id = <String>)
Inputs Type Notes
CMPId Int32 When builing your own UI for TCF 2.0. You need to pass the CMPID given to you by the IAB, in order for your solution to be compliant.

acceptAllForTCF

let consents = UsercentricsCore.shared.acceptAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>)
val consents = Usercentrics.instance.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 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 [UsercentricsServiceConsent] List of Services with consent choices.

denyAllForTCF

 let consents = UsercentricsCore.shared.denyAllForTCF(fromLayer: <TCFDecisionUILayer>, consentType: <UsercentricsConsentType>)
 val consents = Usercentrics.instance.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 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 [UsercentricsServiceConsent] List of Services with consent choices.

saveDecisionsForTCF

let consents = UsercentricsCore.shared.saveDecisions(decisions: <[UserDecision]>, consentType: <UsercentricsConsentType>)
val consents = Usercentrics.instance.saveDecisions(decisions = <[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 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 [UsercentricsServiceConsent] List of Services with consent choices.

CCPA Specific Methods

getUSPData

let USPData = UsercentricsCore.shared.getUSPData()
val USPData = Usercentrics.instance.getUSPData()
Outputs Type Notes
USPData CCPAData US Privacy String information

saveDecisions

let ccpaConsents = UsercentricsCore.shared.saveOptOutForCCPA(isOptedOut: <Bool>, consentType: <UsercentricsConsentType>)
val ccpaConsents = Usercentrics.instance.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 [UsercentricsServiceConsent] List of Services with consent choices.

Helpers

shouldCollectConsent

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

UsercentricsCore.shared.getConsents()
Usercentrics.instance.getConsents()
Outputs Type Notes
consents [UsercentricsServiceConsent] List of Services with consent choices.

getControllerId

UsercentricsCore.shared.getControllerId()
Usercentrics.instance.getControllerId()
Outputs Type Notes
controllerID String A Usercentrics generated ID, used to identify a specific user. See Restore User Session

Objects

UsercentricsOptions

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. 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 to be used depending on the user's location.
consentMediation Bool Enable Consent Mediation, an automated way to pass consent to 3rd party frameworks.

UsercentricsReadyStatus

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 [UsercentricsServiceConsent] List of Services with consent choices.

UsercentricsServiceConsent

Property Type Notes
templateId String ID used to match a service with frameworks running on your app.
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.

UsercentricsCMPData

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 UsercentricsLocation Object exposing user's general location: regionCode, countryCode and countryName.
legalBasis LegalBasisLocalization 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.