> For the complete documentation index, see [llms.txt](https://cmp.docs.sirdata.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cmp.docs.sirdata.net/en/mobile-apps-native-sdk/mobile-sdk/reference.md). # Android — Reference Every method and event exposed by the Android SDK. Setup and the recommended integration order live in [Setup](/en/mobile-apps-native-sdk/mobile-sdk/setup.md). ## Android SDK — `SirDataCMPApi` The primary interface for Android publishers. All methods delegate to the `SirDataCMPManager` singleton. Call `initialize` once per process, from the main thread, before any other SDK call. The methods marked "needs an initialized SDK" below throw `IllegalStateException` when called before `initialize` — for `showConsentBanner`, the consent screen throws when it opens. ### Initialization | Method | Signature | Description | | --------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize` | `fun initialize(context: Context, partnerId: Int, configId: String)` | Initialize with partner credentials. Main thread only. Writes `IABTCF_CmpSdkID`, `IABTCF_CmpSdkVersion` and `IABTCF_PolicyVersion` immediately, then loads the publisher configuration asynchronously; the keys written once it has loaded, before any choice, are listed in [Setup](/en/mobile-apps-native-sdk/mobile-sdk/setup.md), step 5. Throws `IllegalStateException` if the SDK is already initialized: call `shutdown()` first. | | `initialize` | `fun initialize(context: Context, config: SirDataCMPConfig)` | Same, with a full configuration object — see `SirDataCMPConfig` below. | | `isInitialized` | `fun isInitialized(): Boolean` | Returns `true` as soon as `initialize` has been called, before the configuration has loaded. | | `getInitError` | `fun getInitError(): StateFlow` | `null` while the configuration loads and after it loaded; the error message once a load has failed (unknown config ID, network down…). Cleared by the next `initialize`. The same failure is logged as `Config load failed: …` — see [Logging](/en/mobile-apps-native-sdk/mobile-sdk/logging.md). | | `shutdown` | `fun shutdown()` | Clears in-memory state and cancels a configuration load in flight. Stored consent stays in SharedPreferences. Main thread only. | ### Consent Banner | Method | Signature | Description | | ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `showConsentBanner` | `fun showConsentBanner(activity: ComponentActivity)` | Launches `ConsentActivity` with Compose UI, in the workflow the display decision selected. Fires `cmpuishown` event. Needs an initialized SDK. | | `showConsentBanner` | `fun showConsentBanner(activity: ComponentActivity, workflow: Workflow)` | Same, in an explicit workflow. Pass `Workflow.MANUAL_DISPLAY` when re-opening from a settings screen: the banner shows the close cross at the top and a "Reject all" button whatever the refusal type the publisher configured, restarts the `cappingInDays` window, and is reported as `load:revisit`. | | `shouldCollectConsent` | `fun shouldCollectConsent(): Boolean` | Whether the banner should be presented, per the web `checkConsent()` cascade. Answers immediately, so before the config lands it is provisional. | | `getConsentDisplayDecision` | `fun getConsentDisplayDecision(): ConsentDisplayDecision` | `shouldDisplay` + `workflow` + `reason`, same cascade, also immediate. See [Display decision](#display-decision). | | `awaitConsentDisplayDecision` | `suspend fun awaitConsentDisplayDecision(): ConsentDisplayDecision` | Waits for the config, then decides — the order the web CMP has by construction. Prefer this at startup. | | `awaitConsentDisplayDecision` | `suspend fun awaitConsentDisplayDecision(timeoutMillis: Long): ConsentDisplayDecision` | Same, bounded; past the deadline the decision may be provisional. | | `recordAskLater` | `fun recordAskLater()` | Records an explicit "ask me later": the banner is not shown again for **one hour**, a fixed duration (not `cappingInDays`). Records no consent. Does nothing before `initialize`. | ### Consent Submission All four need an initialized SDK. | Method | Signature | Returns | Description | | --------------- | -------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------- | | `acceptAll` | `suspend fun acceptAll(): ConsentResult` | `ConsentResult` | Accept all purposes, vendors, and features. Persists to SharedPreferences. | | `rejectAll` | `suspend fun rejectAll(): ConsentResult` | `ConsentResult` | Reject all purposes, vendors, and features. Persists to SharedPreferences. | | `saveConsent` | `suspend fun saveConsent(): ConsentResult` | `ConsentResult` | Save current selections (partial consent). | | `submitConsent` | `suspend fun submitConsent(userAction: UserActionResponse): ConsentResult` | `ConsentResult` | Records the current selections and reports them with the given answer. | Each recorded choice fires `useractioncomplete` to TCF and GPP listeners and forwards the Google consent signals to the [consent adapters](/en/mobile-apps-native-sdk/mobile-sdk/sharing-consent.md#consent-adapters). The result and state types (`ConsentResult`, `ConsentState`, `ConsentData`, `UserActionResponse`) are shared with iOS and listed at the end of [Reference — iOS](/en/mobile-apps-native-sdk/mobile-sdk/reference-1.md). ### Consent State Queries The string getters read SharedPreferences and return `""` before `initialize`. | Method | Signature | Returns | Description | | ---------------------- | ------------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `getTcString` | `fun getTcString(): String` | `String` | IAB TC String (base64-encoded, encoded on the device). | | `getGppString` | `fun getGppString(): String` | `String` | Global Privacy Platform string. | | `getUspString` | `fun getUspString(): String` | `String` | CCPA/USP string (e.g., `"1YN-"`). Empty when no decision has been recorded — `"1---"` is an explicit assertion that US Privacy does not apply, not a neutral default. | | `getAddtlConsent` | `fun getAddtlConsent(): String` | `String` | Google Additional Consent string. | | `isGdprApplies` | `fun isGdprApplies(): Boolean` | `Boolean` | GDPR applicability. Once the config is loaded, `context.gdprApplies` as served by the API, as is: the server already folds `forceGdpr` into it, so the SDK no longer adds it on top. Device geo only before that. | | `isCcpaApplies` | `fun isCcpaApplies(): Boolean` | `Boolean` | US Privacy applicability. Once the publisher configuration has loaded, `context.ccpaApplies` as served by the API (from the visitor's country and US state); device geo only before that. | | `getConsentState` | `fun getConsentState(): StateFlow` | `StateFlow` | Observable consent state flow. Needs an initialized SDK. | | `getConsentData` | `fun getConsentData(): ConsentData` | `ConsentData` | Full consent data object. Needs an initialized SDK. | | `getConsentUpdates` | `fun getConsentUpdates(): StateFlow` | `StateFlow` | Counter bumped on every change to the selections — each toggle in the consent UI, before the user saves, as well as each recorded choice. It emits its current value when collected. Use it as a signal to re-read the stored values, not as a count of decisions. A US choice (the US screen, or `setCcpaOptOut`) does not bump it: re-read `getUspString()` and `getGppString()` when the consent UI closes. Needs an initialized SDK. | | `getLastTcStringError` | `fun getLastTcStringError(): String?` | `String?` | Outcome of the last server archive of a recorded choice (`/consent-string`): `null` when it succeeded or none has run, otherwise a message starting with `/consent-string`. The archive runs in the background after the choice is stored, so the value is set after `submitConsent` returns. Despite its name, it does not report on the TC string, which is encoded on the device. Needs an initialized SDK. | | `getPurposeConsents` | `fun getPurposeConsents(): String` | `String` | Purpose consents bit field from SharedPreferences. | | `getVendorConsents` | `fun getVendorConsents(): String` | `String` | Vendor consents bit field from SharedPreferences. | | `hasPurposeConsent` | `fun hasPurposeConsent(purposeId: Int): Boolean` | `Boolean` | Check if specific purpose (1-indexed) has consent. | | `hasVendorConsent` | `fun hasVendorConsent(vendorId: Int): Boolean` | `Boolean` | Check if specific vendor (1-indexed) has consent. | ### Google Consent Mode and adapters All three need an initialized SDK. `GoogleConsentState` is `com.sirdata.cmp.adapter.GoogleConsentState`. | Method | Signature | Returns | Description | | ------------------------------ | --------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- | | `getGoogleConsentState` | `fun getGoogleConsentState(): GoogleConsentState` | `GoogleConsentState` | The Google consent signals computed from the current selections: what the adapters would receive. | | `getLastForwardedConsentState` | `fun getLastForwardedConsentState(): GoogleConsentState?` | `GoogleConsentState?` | What was actually forwarded to the adapters, or `null` when no choice has been recorded since `initialize`. | | `getRegisteredAdapters` | `fun getRegisteredAdapters(): List` | `List` | The adapters whose SDK is in the app: `"Firebase Analytics"`, `"AppsFlyer"`, `"Adjust"`, `"Branch"`. | `GoogleConsentState` carries `adStorageGranted`, `analyticsStorageGranted`, `adUserDataGranted`, `adPersonalizationGranted`, `personalizationStorageGranted`, `functionalityStorageGranted`, `securityStorageGranted`, `isSubjectToGDPR`, `hasConsentForDataUsage` and `adSignalsFromTcf` — `true` when the configuration leaves the three ad signals to Google, in which case the Firebase adapter does not send them. See [Sharing consent with vendor SDKs](/en/mobile-apps-native-sdk/mobile-sdk/sharing-consent.md). ### IAB API Access | Method | Signature | Returns | Description | | -------- | -------------------------- | ------------ | ------------------------------------ | | `tcfApi` | `fun tcfApi(): TcfApiImpl` | `TcfApiImpl` | IAB TCF CMP API v2 in-app interface. | | `gppApi` | `fun gppApi(): GppApiImpl` | `GppApiImpl` | GPP API implementation. | | `uspApi` | `fun uspApi(): UspApiImpl` | `UspApiImpl` | USP/CCPA API implementation. | **TCF commands** ```kotlin // TcfApiImpl fun execute( command: String, version: Int, callback: (Any?, Any?, Boolean) -> Unit, parameter: Any? = null, ) ``` The callback receives the data, a listener ID (or `null`) and a success flag, on the main thread. Only version `2` is supported: any other version, and any unknown command, calls back with `success = false` (`ping` answers whatever the version). | Command | Parameter | Callback data | | ----------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ping` | — | `cmpId` (92), `cmpVersion`, `cmpStatus` (`stub` until the configuration has loaded, then `loaded`), `cmpLoaded`, `tcfPolicyVersion`, and `gdprApplies` once it is determined | | `getTCData`, `getInAppTCData` | ignored | The TC data read from the stored keys. `success = false` until the configuration has loaded | | `addEventListener` | — | See [the in-app command API](/en/mobile-apps-native-sdk/mobile-sdk/sharing-consent.md#the-in-app-command-api): the callbacks carry no `eventStatus` in 2.0.0 | | `removeEventListener` | Listener ID (`Int`, `Long`, `Double` or `String`) | The listener ID; `success` says whether a listener was removed | | `getVendorList` | — | `gvlSpecificationVersion`, `vendorListVersion`, `tcfPolicyVersion`, `lastUpdated`, `purposes`, `vendors`. `success = false` until the configuration has loaded | **GPP commands** ```kotlin // GppApiImpl fun execute( command: String, parameter: Any? = null, callback: (Any?, Boolean) -> Unit, ) ``` | Command | Parameter | Callback data | | --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ping` | — | `gppVersion` (1), `gppString`, `gppSid`, `applicableSections`, `cmpStatus`, `cmpLoaded` | | `hasSection` | Section name: `tcfeuv2` or `uspv1` | `true` when the section is in `IABGPP_GppSID` | | `getSection` | Section name: `tcfeuv2` or `uspv1` | The section's fields, or `null` when it is absent | | `getGppData` | — | `gppVersion`, `gppString`, `gppSid`, `applicableSections` | | `addEventListener` | — | First the listener ID, then for each event a map with `eventName` (`useractioncomplete`, `cmpuiclosed`), `gppString`, `gppSid` and `applicableSections` | | `removeEventListener` | Listener ID | — | `hasSection` and `getSection` do not know the US National section (`usnat`, ID 7) in 2.0.0: read it from `IABGPP_7_String`. **USP command** ```kotlin // UspApiImpl fun execute( command: String, version: Int, callback: (Map?, Boolean) -> Unit, parameter: Any? = null, ) ``` `getUspData` is the only command: `version`, `uspString`, `notice`, `optOut` and `lspa`. It reports the stored string when US Privacy applies, and `1---` otherwise. ### CCPA Opt-Out | Method | Signature | Description | | ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `setCcpaOptOut` | `fun setCcpaOptOut(optedOut: Boolean)` | Records the user's "Do Not Sell" choice: writes `IABUSPrivacy_String` and re-encodes the GPP string (sections 6 and 7). Call it from a control the user operates, never on their behalf. Main thread only. Does nothing before `initialize`. The consent UI's US screen calls it when the user saves. Does not bump the `getConsentUpdates()` counter. | | `isCcpaOptedOut` | `fun isCcpaOptedOut(): Boolean` | Returns `true` if user opted out of sale. | ### Data Management | Method | Signature | Description | | -------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clearConsent` | `fun clearConsent()` | Clears ALL persisted consent from SharedPreferences. For testing, or an explicit user data deletion request. Does nothing before `initialize` or after `shutdown()`. | *** ## `SirDataCMPConfig` — Android Configuration ```kotlin data class SirDataCMPConfig( val partnerId: Int, // your Sirdata partner ID (required) val configId: String, // your Sirdata config ID (required) val language: String? = null, // accepted, no effect in 2.0.0 val theme: CmpTheme = CmpTheme.Default, // accepted, no effect in 2.0.0 val apiRoot: String = "https://api.consentframework.com/api/v1/public", val cacheApiRoot: String = "https://choices.consentframework.com/api/v1/public", val consentApiRoot: String = "https://mychoice.consentframework.com/api/v1/public", val debugMode: Boolean = false, // main-thread violations throw instead of logging val certificatePins: CertificatePins? = null, val gdprDefaultApplies: Boolean = true, // GDPR assumption, see below ) ``` * **`language`** is accepted but read by nothing in 2.0.0. The UI language is the one pinned in the publisher configuration in the [Sirdata Console](https://cmp.sirdata.io), if any; otherwise the device language, when the SDK supports it; otherwise the configuration's default language; otherwise English. * **`theme`** is accepted but read by nothing in 2.0.0 — see [`CmpTheme` Enum](#cmptheme-enum). * **`debugMode`** only changes the main-thread contract: a call to `initialize`, `shutdown` or `setCcpaOptOut` off the main thread throws instead of being logged. Enable it in debug builds only — see [Logging](/en/mobile-apps-native-sdk/mobile-sdk/logging.md). * **`certificatePins`** (`com.sirdata.cmp.api.CertificatePins`) maps a host name to its `sha256/…` public-key pins, applied to the SDK's own HTTPS requests. A wrong pin blocks the requests to that host — on the `cacheApiRoot` host, the configuration then fails to load. * **`gdprDefaultApplies`** is the answer `isGdprApplies()` gives before the publisher configuration has loaded, when the device reports no country. Once the configuration has loaded, the API decides. ### Builder ```kotlin val config = SirDataCMPConfig.Builder(partnerId, configId) .apiRoot("https://api.consentframework.com/api/v1/public") // default api host .cacheApiRoot("https://choices.consentframework.com/api/v1/public") // default choices host .consentApiRoot("https://mychoice.consentframework.com/api/v1/public") // default consent host .gdprDefaultApplies(true) .debugMode(BuildConfig.DEBUG) // your app's BuildConfig: debug builds only .build() SirDataCMPApi.initialize(applicationContext, config) ``` With the Android Gradle Plugin 8, your app's `BuildConfig` class is generated only when `buildFeatures { buildConfig = true }` is set in its module. The builder also has `language(...)`, `theme(...)` (no effect in 2.0.0) and `certificatePins(CertificatePins(mapOf(host to listOf("sha256/…"))))`. ### `CmpTheme` Enum | Value | Description | | --------- | ---------------------------- | | `Default` | Accepted, no effect in 2.0.0 | | `Dark` | Accepted, no effect in 2.0.0 | | `Light` | Accepted, no effect in 2.0.0 | The consent UI takes its colors from the theme configured in the Sirdata Console, in its light or dark version according to the device's dark mode setting. When the configuration defines no dark version, the light one is used in dark mode too. *** ## Display decision `ConsentDisplayDecision` (`com.sirdata.cmp.workflow`) is what `getConsentDisplayDecision()` and `awaitConsentDisplayDecision()` return: ```kotlin data class ConsentDisplayDecision( val shouldDisplay: Boolean, val workflow: Workflow, // pass it to showConsentBanner(activity, workflow) val reason: DisplayReason, ) ``` ### `Workflow` `com.sirdata.cmp.model.Workflow`. | Value | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `MAIN` | The standard banner. Also the workflow of every decision that does not display. | | `APPLY_CHOICES` | Returned when the stored choice is missing only partners: the banner asks only about what is left to decide. | | `COOKIEWALL` | Returned when the configuration enables the cookie wall and the stored choice does not grant purpose 1. | | `COOKIEWALL_MODIFY` | Set by the consent UI itself when the user modifies their choices from the cookie wall. The decision never returns it. | | `MANUAL_DISPLAY` | Re-opening from a settings screen, passed by the app. The decision never returns it. See `showConsentBanner` above. | ### `DisplayReason` `com.sirdata.cmp.workflow.DisplayReason`. | Value | `shouldDisplay` | Meaning | | ------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GDPR_NOT_APPLIES` | `false` | GDPR does not apply — as the server answered, or, before the configuration has loaded, as estimated from the device. | | `CONSENT_REQUIRED` | `true` | Something is left to ask. | | `CAPPING_ACTIVE` | `false` | A capping window is running on a stored choice that does not grant purpose 1. | | `CAPPING_ASK_LATER` | `false` | Nothing is stored, and "ask me later" was recorded less than an hour ago. | | `CONSENT_OK` | `false` | The stored choice needs nothing more, or a capping window is running on a choice that grants purpose 1. | | `CONFIG_NOT_LOADED` | `true` or `false` | Provisional: the configuration had not loaded, so only GDPR applicability, estimated from the device, and the presence of a stored TC string were evaluated. When that estimate says GDPR does not apply, the reason is `GDPR_NOT_APPLIES` instead. | *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://cmp.docs.sirdata.net/en/mobile-apps-native-sdk/mobile-sdk/reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.