@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
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 withCookieChimpProvider and your account ID from the dashboard.
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.
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.country="DE"orcountry="US-CA"always wins. Pass it when your app already knows the user’s country, for example from your own backend.- Otherwise, with
geolocationand anaccountId, 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. - 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.
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
Reading and changing consent
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 callsonStart when consent allows it and onStop when consent is
withdrawn. Nothing starts before consent where consent is required.
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:
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
Setui={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 withbold,italicand safehrefvalues;plainText(html)strips the markup. useConsentDraft()keeps changes local untilsave(). Switching a category switches its services; required categories cannot be switched off. Each category hasserviceswithappDatalabels;text.messages.dataType(key)andtext.messages.purpose(key)name them in the user’s language.
<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 apt-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.
Consent records
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.
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.