Osano CMP React Native

Necessary Software Setup

1. Xcode
2. Android Studio
3. Xcode command-line tools
4. Node

Corepack

This project uses corepack to manage and link dependencies. To install corepack, run the following commands:

corepack enable
corepack install # installs yarn

Running Locally

The repo is made up of a root folder and 2 important sub folders. The first is packages, which is the actual SDK. The second is examples, which includes different implementations of the SDK in a test app to demonstrate and test integration.

From the root folder, run the following:

corepack yarn install
corepack yarn prepare
cd example/ios && pod install && cd ../..
cd example/ios && echo export NODE_BINARY=$(command -v node) > .xcode.env && cd ../.. # do once
cp example/.env.example example/.env # do once
corepack yarn example android # or ios

# alternatively
cd example && corepack yarn start android # or ios

Specifying run destination

iOS

corepack yarn example ios --simulator "iPhone 15 Pro"

Android

// TODO

Running Tests

Testing should be done through both the example integration and the package itself.

Testing the package

1. From the packages/osano-comp-react-native folder run the following. This specifically runs the tests associated with the main package

npm test /src/__tests__

1. In order to test all test files in the package, including IAB, run the following from the packages/osano-comp-react-native folder

npm test

Testing the examples

Build the test applications from local builds

• iOS

1. Run the iOS application locally via yarn example ios
2. Open the Derived Data in your XCode folder ~/Library/Developer/XCode/DerivedData
3. One of the folders in the DerivedData folder will contain a Build folder
4. Open Build/Products/<device-type>
5. The .app file will be OsanoCMPExample with a file type Application

• Android

1. Run the android example application locally via yarn example android
2. In Android Studio under Project open app/build/outputs/apk/<release-or-debug>/ to get the apk file

Both files can be sent to coworkers with an ios simulator or android emulator to run for testing

Troubleshooting

1. If the run command fails saying there is no development project, make sure to open the relevant simulator/emulator before running.
2. If there are significant errors citing duplicates, it is likely you ran npm i in the packages folder. These files should be removed via rm -rf node_modules in the packages/osano-cmp-react-native folder from the command line
3. For initial developing and testing make sure you have a relatively recent simulator on iOS and emulator on Android. Old devices running old OS can cause unnecessary issues
4. Building the iOS example from Xcode might result in a Command PhaseScriptExecution failed with a nonzero exit code. This is caused by a missing .xcode.env file that contains an entry for NODE_PATH. Resolve by running echo export NODE_BINARY=$(command -v node) > .xcode.env from the example/ios directory.

=======

The Osano ConsentSDK for iOS is a native framework that integrates with the Consent Management Platform on the Osano Website. It is necessary to have an account, and a Cookie Consent configuration created and published in order for this SDK to be able to record end-user consents.

Installation

We use NPM to manage and install the SDK package.

1. At the top level of your project run npm install @osano/osano-cmp-react-native

Native iOS installation

NPM uses cocoapods to install the native iOS portion of modulesCocoaPods

1. Install Cocoapods using Cocoapods - Getting Started.
2. Run pod install from inside the iOS folder in your project

Native Android installation

1. Run a gradle sync after @osano/osano-cmp-react-native has been added to your package manager

Integration

How do I use it?

• ConsentManager
• UI Builder
  • 1. Dialog
  • 2. Drawer
• Using Custom UI

ConsentManager

First, you must create an instance of the Osano object. This object contains the general configuration parameters that will be used throughout the life of the application.

import { Osano, OsanoContext } from '@osano/osano-cmp-react-native'

// ...

const
<Osano
    customerId={customerId}
    configId={configId}
    hideDisclosures={hideDisclosures}
    onConfigLoadSuccess={handleConfigLoadSuccess}
    onConfigLoadFailure={handleConfigLoadFailure}
    onLangLoadSuccess={handleLangLoadSuccess}
    onLangLoadFailure={handleLangLoadFailure}
    overrides={{
        flavor: flavor ? flavor : undefined,
        locale: locale ? locale : undefined,
    }}
>
   <YourAppHere>
</Osano>

Note that the configId and customerId parameters are not optional, and must match the values of your configuration on the Osano website.

You can use the OsanoContext to access the ConsentManager object:

const {
	clearConsent,
	getConsent,
	getDeviceId,
	locale,
	setLocale,
	showBanner,
	showDrawer,
} = React.useContext(OsanoContext);

UI Builder

Now that you have created an instance of the ConsentManager, you can use it to create and show consent messages in your application. There are two types of dialogues available to show in the SDK, and (depending on the geo-location of your end-user) the UI for each will look different. This is due to legal requirements that are in place for the end-user's geo-location. Rest assured, these UI differences are intentional and necessary to maintain legal compliance for the location of your users.

Display Modes

The UI may de shown in 2 different ways:

Dialog

The Dialog View Controller allows you to show a consent message and the required data storage preferences based on the country the device is in. The SDK takes care of figuring out which consent variant must be shown based on the device's locale.

To create the dialogue and show it, use the showDrawer method from the OsanoContext:

<Pressable onPress={showDrawer}>
	<Text>Show Categories Dialog</Text>
</Pressable>

:::note

The dialog (depending on the end-user's geo-location) may have an automatic timeout, which will grant consent upon closure. This is normal functionality for specific global regions.

:::

:::caution Declined to Consent

If a the completion callback notifies you that the end-user declined to consent, this does not mean they denied consent. It simply means that they did not make a selection.

The Drawer UI will not allow the user to dismiss the modal without making a selection, but the Dialog UI (in some geo-locations) will allow the user to dismiss the modal without making a selection. This is why it is important to check the categories array in the completion callback to determine if the user has actually declined to consent.

:::

Drawer

The Drawer View Controller allows you to display all consent categories using a built-in UI. In this dialogue, the user can choose to enable or disable any of the consent categories. To user the view controller and show it, use the method showBanner

<Pressable onPress={showBanner}>
	<Text>Show Concent Banner</Text>
</Pressable>

Using Custom Implementation

If the SDK's built-in UI and implementation does not fit your requirements, you can use the ConsentManager's APIs and integrate them to your own app's UI:

const consentManager = useRef<ConsentManager>(new ConsentManager());
const [_state, dispatch, getState, addMiddleware, removeMiddleware] =
		useThunkReducer<OsanoState, OsanoAction>(
			reducer,
			{ configId, customerId },
			init,
			[],
		);
return(
    <OsanoPublicContext.Provider value={context}>
	    {<YourAppHere>}
	    <ConsentUiBuilder
		    addMiddleware={addMiddleware}
		    removeMiddleware={removeMiddleware}
		    dispatch={dispatch}
		    getState={getState}
		    cmp={consentManager}
		    hideDisclosures={hideDisclosures}
	    />
    </OsanoPublicContext.Provider>
)

To save (locally and remotely) new consent categories use:

recordConsent(consentManager.current, ConsentCategory.ESSENTIAL); //ESSENTIAL, ANALYTICS, MARKETING, PERSONALIZATION, OPT_OUT

To get the list of consented categories (local storage):

let consentedArray = consentManager.current.consent;
let consentedString = consentedArray.join(', ');
console.log(consentedString);

To get whether the user has already gone through the consent process:

let userConsented = consentManager.current.consent.length > 0;