Skip to main content
Documentation: React Native SDK. Consent banner, preferences screen, consent records and vendor control for React Native and Expo apps, built on the same @cookiechimp/core consent engine as the CookieChimp web SDK. This package is part of the coordinated CookieChimp SDK release. Keep any CookieChimp packages you use on matching versions. See release status.

What it does

  • Shows the banner and preferences you design in the CookieChimp dashboard as native screens, with your copy, translations, colors and button settings.
  • Picks the right banner for the user’s country or US state and applies GDPR (opt-in) or CCPA (opt-out) rules from the banner’s consent mode.
  • Stores the decision on the device and asks again when it expires or when you require re-consent in the dashboard.
  • Sends consent records to CookieChimp, queued and retried while offline.
  • Starts and stops your analytics and advertising SDKs as consent changes.
  • Needs no custom native code beyond AsyncStorage, so it works in Expo Go, development builds and bare React Native apps.

Install

With Expo, use npx expo install @cookiechimp/react-native @react-native-async-storage/async-storage. In a bare app, run npx pod-install afterwards. React Native 0.80 or newer (Expo SDK 54 or newer) and React 18 or newer are supported. Older React Native versions ship an incomplete URL implementation: install react-native-url-polyfill and import react-native-url-polyfill/auto first.

Quick start

Wrap your app with CookieChimpProvider and your account ID from the dashboard.
Your app renders immediately. The banner slides in once the stored decision and the dashboard config are loaded, and only when the user still needs to choose.

Connected and offline modes

Connected mode (accountId) downloads the dashboard config, caches it on the device and renders from the cache on later launches. It revalidates with an ETag in the background and again when the app returns to the foreground after five minutes, so dashboard changes reach users without an app release. Offline mode (config) uses a config file you download from the dashboard (Setup, Download Config) and ship inside the app. No config requests are made. Consent records are still delivered when the device is online.
To update an offline config, download the file again and ship an app update.

Region and language

The region selects which dashboard banner applies and whether its opt-out (CCPA) rules can be used. By default the SDK never looks up the user’s location.
  1. country="DE" or country="US-CA" always wins. Pass it when your app already knows the user’s country, for example from your own backend.
  2. Otherwise, with geolocation and an accountId, the SDK asks CookieChimp’s own first-party endpoint for the connection’s country (one small IP-based request on launch). No third-party location service is contacted and device location permissions are never used. This is off unless you opt in.
  3. Without a region, the dashboard’s default banner is shown with the safe GDPR fallback: optional categories stay off until the user chooses, even when the default banner is an opt-out banner.
Device locale (for example en-US) is a language setting, not a location, and is never used to choose the region. The language defaults to the device language and falls back to the first language the banner has. Override it with language="fr". See Translations for how missing copy is filled in.

Provider props

Use hooks inside the provider:
Or use the CookieChimp object anywhere, including outside React:
CookieChimp.run(options) starts the SDK without the provider, for example in index.js before React mounts. Render <CookieChimpProvider> without accountId or config to show the built-in UI for an SDK started this way.

Controlling vendor SDKs

Register each analytics or advertising SDK with the category it belongs to. The SDK calls onStart when consent allows it and onStop when consent is withdrawn. Nothing starts before consent where consent is required.
When the name matches a service in your dashboard, the user’s choice for that service applies; otherwise the category’s choice applies. Disable each SDK’s automatic collection in its native configuration so nothing is sent before onStart. getVendors(), isVendorRunning(name), startVendor(name), stopVendor(name) and unregisterVendor(name) are also available. Presets do this for Firebase, AppsFlyer, Adjust, Meta, Amplitude, Mixpanel, Branch, Braze and OneSignal, using the names from CookieChimp’s mobile SDK library:
On iOS, requestTrackingAfterConsent shows the App Tracking Transparency prompt after the user accepts marketing. See vendor SDKs, Firebase and App Tracking Transparency for every preset, the Firebase setup and ATT guidance.

Design settings

The built-in screens follow the banner design you set in the dashboard: Categories and vendors expand with an animation to show their purpose, the company and the privacy policy. Banners and preferences animate in and out, and animations are skipped when the device asks for reduced motion.

Vendor data labels

Mobile SDKs do not set cookies, so each vendor shows its data labels from the dashboard instead, in the same shape as Apple’s App Privacy details and Google Play’s Data safety section: SDKs added from the dashboard’s library come with these filled in, and you can edit them per SDK. The labels are shown in the banner’s language.

Headless mode

Set ui={false} to draw the banner and preferences yourself. The SDK still loads the config, picks the banner and regulation, stores decisions, sends consent records and starts and stops vendors; your screens read and change consent with hooks.
  • useBanner() opens when the user still needs to decide, exactly as the built-in banner would. Keep your banner on screen until a decision.
  • useConsentText() gives every string from the dashboard with translated fallbacks, the privacy policy URL, rtl, and whether the banner should show “Powered by CookieChimp” (banner.poweredBy). The preferences screen always shows it.
  • Descriptions are dashboard rich text. richText(html) returns paragraphs of spans with bold, italic and safe href values; plainText(html) strips the markup.
  • useConsentDraft() keeps changes local until save(). Switching a category switches its services; required categories cannot be switched off. Each category has services with appData labels; text.messages.dataType(key) and text.messages.purpose(key) name them in the user’s language.
You can also render the built-in <ConsentBanner /> and <ConsentPreferences /> yourself and replace only one of them.

Translations

Every piece of text comes from your dashboard first, in the selected language. When a field is empty, or for text the SDK draws itself (data labels, “Privacy policy”, “Your consent ID”, “Powered by”), the SDK uses its own copy in the same language, then the copy in the banner’s default language, then English. Optional copy such as the additional description is never borrowed from another language. Built-in copy is included for the 33 languages of the web SDK: Arabic, Bulgarian, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hungarian, Irish, Italian, Japanese, Korean, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese (Portugal and Brazil), Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish and Ukrainian. A device locale refines the dashboard language, so a pt-BR device sees Brazilian Portuguese with a pt banner. Replace any built-in string with translations. Define it outside your component, since a new object restarts the SDK:
messages(language) returns the SDK copy for any language, and SDK_LANGUAGES lists the built-in ones. Each decision is stored on the device first and then sent to CookieChimp (POST /api/v1/mobile-sdk/sync/{accountId}) with the platform (ios or android), banner, language, accepted and rejected categories and services, and the decision time. Device identifiers, user IDs and advertising IDs are never sent. Records wait in a queue of up to 50 while the device is offline, retry with backoff and are sent again when the app returns to the foreground. Delivery is idempotent, so a retry never creates a duplicate.

Storage

The decision, the cached config and queued records are stored in AsyncStorage under keys starting with @cookiechimp:. Pass storage to use another store with the same getItem, setItem, removeItem and getAllKeys methods.

Debugging

debug logs the selected banner, region, language, regulation and every decision to the console, and shows a small “CC debug” tab at the top of the screen. Tap it to open the debug panel:
  • SDK status, where the config came from (bundled file, device cache or network), config version, account, banner, language, region, regulation and the number of consent records waiting to be sent.
  • The stored decision: action, consent ID, time, and every category and service.
  • Registered vendors and whether each is running.
  • Recent activity: config loads, decisions, re-consent, vendor starts and stops, and record delivery.
  • Buttons to show the banner or preferences, accept all, reject all, reset consent and send records now.
Turn it off in release builds with debug={__DEV__}. useDebugEvents() returns the same activity log, and <DebugPanel /> renders the panel yourself (for example with CookieChimp.run). CookieChimp.reset() clears the stored decision so you can test the first-launch flow again. MIT licensed.