ketch-react-native

This repository contains the Ketch React Native package in the /package folder and an example app in the /example folder.

Prerequisites

• node - We use node v20.11.1 (LTS).
  • It's recommended to use Node Version Manager (NVM) to manage your Node.js versions.

Usage (Non-Expo Apps)

For a working example, see the example directory.

1. Install core dependency

npm install @ketch-com/ketch-react-native --registry=https://npm.pkg.github.com --legacy-peer-deps

When running the above command, you may see a 401 Unauthorized response. This occurs because Github packages require authentication through a personal access token (PAT). See their Authentication to Github Packages document to set this up.

2. Install peer dependencies

npm install react-native-default-preference react-native-webview

3. (IOS) Install Pods

cd ios && pod install

4. Use the <KetchServiceProvider/> component

<KetchServiceProviderorganizationCode="YOUR_ORGANIZATION_CODE"propertyCode="YOUR_PROPERTY_CODE"identities={{YOUR_IDENTIFIER_NAME: "YOUR_IDENTIFIER_VALUE"}}>{/* The rest of your app code here */}</KetchServiceProvider>

Where YOUR_ORGANIZATION_CODE, YOUR_PROPERTY_CODE, YOUR_IDENTIFIER_NAME, and YOUR_IDENTIFIER_VALUE are replaced with those configured within the Ketch application.

See our Getting Started and Technical Documentation documentation for further usage instructions.

Usage (Expo Apps Only)

For a working example, see the example-expo directory.

1. Install core dependency

npm install @ketch-com/ketch-react-native --registry=https://npm.pkg.github.com --legacy-peer-deps

When running the above command, you may see a 401 Unauthorized response. This occurs because Github packages require authentication through a personal access token (PAT). See their Authentication to Github Packages document to set this up.

2. Install peer dependencies

npx expo install expo-shared-preferences react-native-webview

3. (Android) Configure SharedPreferences import

Create a separate SharedPreferences.android.ts file:

// Place this in a separate .android.ts file so it is only imported on Androidimport*asSharedPreferencesfrom"expo-shared-preferences";exportdefaultSharedPreferences;

Next, import it in the file where you will use KetchServiceProvider:

// then when setting up KetchServiceProviderimportSharedPrefencesfrom'./SharedPreferences';<KetchServiceProvider// ...preferenceStorage={SharedPreferences}>

4. Setup a Development Build

To run through Expo on Android, you must use a development build. See the Expo Documentation for steps to create a development build.

5. (IOS) Install Pods

cd ios && pod install

6. Use the <KetchServiceProvider/> component

<KetchServiceProviderorganizationCode="YOUR_ORGANIZATION_CODE"propertyCode="YOUR_PROPERTY_CODE"identities={{YOUR_IDENTIFIER_NAME: "YOUR_IDENTIFIER_VALUE"}}>{/* The rest of your app code here */}</KetchServiceProvider>

Where YOUR_ORGANIZATION_CODE, YOUR_PROPERTY_CODE, YOUR_IDENTIFIER_NAME, and YOUR_IDENTIFIER_VALUE are replaced with those configured within the Ketch application.

See our Getting Started and Technical Documentation documentation for further usage instructions.

API

useKetchService() returns the service from anywhere inside the provider.

const{ showConsentExperience, trigger, getRegion }=useKetchService();

Experiences — showConsentExperience(), showPreferenceExperience(options?), dismissExperience(), load(), updateParameters(params), setCssOverride(css).

Rule triggers

trigger(TriggerName.Custom,'managePrivacy');

Returns false if the function name is invalid or an experience is already showing. Returns true when the call is accepted — either injected into a booted WebView or queued. Queued calls fire on onConfigLoaded; if the tag never finishes loading, the queue is not drained and there is no later error callback. A later trigger() supersedes an earlier pending one.

Reading values — getConsent() reads the cached consent state. getRegion() and getJurisdiction() resolve those codes, preferring anything you passed as a prop over a network lookup. getTCFTCString(), getUSPrivacyString(), getGPPHDRGppString(), and getSavedString(key) read the IAB privacy strings the tag wrote to native storage. All return promises.

Headless — fetchConsent, setConsentOnServer, invokeRight, getBootstrapConfiguration, getFullConfiguration, getSubscriptions, setSubscriptions, and preferenceQRUrl hit the CDN directly, for consent operations that need no WebView.

Provider props worth knowing beyond the required codes: dataCenter (selects the server, and therefore which build of the Ketch tag is used — US and EU are production, UAT is the UAT environment), languageCode, regionCode, jurisdictionCode, environmentName, logLevel, autoLoad, ketchMobileSdkUrl, webResourceUrlOverrides, and the on* event callbacks.

Running

See the example app README, or the example expo app README.

Contributions

See the package README.