Skip to main content

Getting Started

The Osano ConsentSDK for React Native is a 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.

How do I use it?​

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'

// ...

<Osano
    customerId={customerId}
    configId={configId}
    hideDisclosures={hideDisclosures}
    onConfigLoadSuccess={handleConfigLoadSuccess}
    onConfigLoadFailure={handleConfigLoadFailure}
    onLangLoadSuccess={handleLangLoadSuccess}
    onLangLoadFailure={handleLangLoadFailure}
    setLoggingEnabled={__DEV__}
    overrides={{
        flavor: flavor ? flavor : undefined,
        locale: locale ? locale : undefined,
        palette: palette ? palette : undefined,
    }}
	extUsrData="unique_user_id"
>
   <YourAppHere>
</Osano>

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

Using extUsrData allows you to associate an external user identifier (such as a user ID from your own system) with the consent record. This parameter is required for cross-device consent, which ensures that a user's consent preferences are recognized consistently across multiple apps, devices, or browser sessions.

For example, if a user logs into your service on both web and mobile, providing the same external ID ensures that their consent preferences are unified and respected across all environments.

Important! It is not advisable to use any personally identifiable information as your extUsrData in order to avoid any privacy violations. Additionally, the provided extUsrData will not be stored in a consent record unless cross-device consent is enabled.

You can use the OsanoContext to access the ConsentManager object and its public methods:

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

The SDK will inherit any text customizations created in the CMP configuration. To update any translations in our supported languages, log into my.osano.com and update the corresponding CMP configuration used by the SDK.

Public API Methods​

getConsent(category?: ConsentCategory): boolean | ConsentCategory[]​

Retrieves the user's consent preferences. This method can be used in two ways:

  • With a specific category: Returns true if the user has consented to that particular category, false otherwise.
  • Without parameters: Returns an array of all consented categories.
// Check if user consented to analytics
const hasAnalyticsConsent = getConsent('ANALYTICS'); // Returns: boolean

// Get all consented categories
const allConsents = getConsent(); // Returns: ['ESSENTIAL', 'ANALYTICS', ...] or []

Available consent categories: ESSENTIAL, ANALYTICS, MARKETING, PERSONALIZATION, OPT_OUT

clearConsent(): void​

Clears all stored consent data, both locally and remotely. This resets the user's consent state and triggers Google Consent Mode updates if configured. After clearing, only essential cookies will be allowed.

// Clear all user consent
clearConsent();
getDeviceId(): string​

Returns the unique device identifier used for consent tracking across sessions. This ID helps maintain consent preferences even if the app is reinstalled or data is cleared.

const deviceId = getDeviceId(); // Returns: unique device identifier string
locale: string​

A read-only property that returns the currently active language/locale for the consent UI. The locale determines which language is used for consent messages and interfaces.

console.log(locale); // Returns: 'en', 'es', 'fr', etc.
setLocale(locale: string): void​

Changes the language/locale for the consent UI. The SDK will attempt to load the specified language and update all text accordingly. Supported locales depend on your Osano CMP configuration.

// Set language to Spanish
setLocale('es');

// Set language to French  
setLocale('fr');
showBanner(): void​

Displays the consent banner dialog. The appearance and behavior of this dialog varies based on the user's geographic location to comply with local privacy laws (GDPR, CCPA, etc.). In some regions, the banner may automatically timeout and grant consent.

// Show the consent banner
showBanner();
showDrawer(): void​

Displays the detailed consent preferences drawer where users can granularly control their consent for different categories. This interface requires explicit user interaction and will not automatically timeout.

// Show the consent preferences drawer
showDrawer();
isReady: boolean​

A read-only property that indicates whether the consent manager has finished loading configuration and is ready to accept user interactions. You should check this before calling other methods.

if (isReady) {
  // Safe to show consent UI or check consent status
  const consent = getConsent();
}

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 be 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 showBanner method from the OsanoContext:

<Pressable onPress={showBanner}>
	<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.

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 use the view controller and show it, use the method showDrawer

<Pressable onPress={showDrawer}>
	<Text>Show Consent 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;