Getting Started

Before jumping into the integration, let's have a quick overview of when and how should you collect consent.

When should you collect consent?

In general, you are free to decide when to collect consent from your users. e.g. Right after app launch, after login, during app onboarding, etc.

There are only 2 requirements when collecting consent:

Requirement 1

Do NOT enable any data tracking from 3^rd party services/SDKs before a user has given explicit consent. This would otherwise be a breach of data protection regulations, which can result in heavy fines.

Requirement 2

Don't forget Requirement 1.

Integrating Usercentrics

1. Import Usercentrics, configure your options and initialize the SDK:

   Swift_iOSKotlin_AndroidDart_FlutterTypescript_{React Native}

   // On AppDelegate
   import Usercentrics
   
   let options = UsercentricsOptions(settingsId: <SettingsID>)
   UsercentricsCore.configure(options: options)
   

   // On Application
   import com.usercentrics.sdk.*
   
   val options = UsercentricsOptions(settingsId = <SettingsID>)
   Usercentrics.initialize(this, options)
   

   // e.g place this inside the [initState] of the Entry Point Widget
   import 'package:usercentrics_sdk/usercentrics_sdk.dart';
   
   Usercentrics.initialize(
       settingsId: <SettingsID>,
   );
   

   // On your App entrypoint
   import { Usercentrics, UsercentricsOptions } from '@usercentrics/react-native-sdk';
   
   // React hooks
   useEffect(() => {
       let options = new UsercentricsOptions(<SettingsID>);
       Usercentrics.configure(options);
   }, []);
   
   // Or via constructor
   constructor(props: any) {
       super(props)
   
       let options = new UsercentricsOptions(<SettingsID>)
       Usercentrics.configure(options)
   }
   

   First Init

   We recommend initializing the SDK in the background as soon as possible after app launch to avoid any loading delays. After the first init, the SDK will cache essential data and following initializations will be immediate.

   Resetting the SDK

   Use reset() to clean all local storage and release the initialized instance. You will need to initialize the SDK again after a reset. Make sure you validate the expected behaviour, before using reset in production.

   Switching SettingsIDs

   If you need to switch SettingsIDs during runtime, just reinitialize the SDK with the new SettingsID. This will automatically trigger a reset(), and initialize the new configuration.

2. Use isReady to fetch the latest consent status. This status will let you know if you need to show the banner to collect consent or only apply the already collected consent.

   Swift_iOSKotlin_AndroidDart_FlutterTypescript_{React Native}

   import Usercentrics
   
   UsercentricsCore.isReady { [weak self] status in
       guard let self = self else { return }
       if status.shouldCollectConsent {
           // Show banner to collect consent
       } else {
           // Apply consent with status.consents
       }
   } onFailure: { error in 
       // Handle non-localized error
   }
   

   import com.usercentrics.sdk.*
   
   Usercentrics.isReady({ status ->
       if (status.shouldCollectConsent) {
           // Show banner to collect consent
       } else {
           // Apply consent with status.consents
       }
   }, { error ->
       // Handle non-localized error
   })
   

   import 'package:usercentrics_sdk/usercentrics_sdk.dart';
   
   try {
       final status = await Usercentrics.status;
       if (status.shouldCollectConsent) {
           // Show banner to collect consent
       } else {
           // Apply consent with status.consents
       }
   } catch (error) {
       // Handle non-localized error
   }
   

   import { Usercentrics } from '@usercentrics/react-native-sdk';
   
   try {
       const status = await Usercentrics.status();
       if (status.shouldCollectConsent) {
           // Show banner to collect consent
       } else {
           // Apply consent with status.consents
       }
   } catch(error) {
       // Handle error
   }
   

   Wait for isReady

   It is required that you wait until isReady is called to use any SDK methods. Not doing so could lead to a crash, as methods called when the SDK has not finished initializing will return an exception.

3. Once you are ready to collect consent, use the status object returned in isReady to know if you shouldCollectConsent or if consent has already been collected.

   iOSAndroidFlutterReact Native

   UsercentricsCore.isReady { [weak self] status in
       guard let self = self else { return }
       if status.shouldCollectConsent {
           self.collectConsent()
       } else {
           // Apply consent with status.consents
       }
   } onFailure: { error in
       // Handle non-localized error
   }
   

   Usercentrics.isReady({ status ->
       if (status.shouldCollectConsent) {
           collectConsent()
       } else {
           // Apply consent with status.consents
       }
   },{ error ->
       // Handle non-localized error
   })
   

   try {
       final status = await Usercentrics.status;
       if (status.shouldCollectConsent) {
           collectConsent();
       } else {
           // Apply consent with status.consents
       }
   } catch (error) {
       // Handle non-localized error
   }
   

   try {
       const status = await Usercentrics.status();
   
       if (status.shouldCollectConsent) {
           collectConsent();
       } else { 
           // Apply consents with status.consents
       } 
   } catch(e) { 
       // Handle non-localized error 
   }
   

Inside collectConsent(), you will be presenting the consent banner, and we offer different ways to do this, depending on your needs:

UsercentricsUI

An out-of-the-box UI component, that owns all the complexity of compliance, designed to be highly customizable. Continue to UsercentricsUI.

Build you own UI

Use our SDK as a data source and render your own consent banner from scratch. Continue to Build your own UI.

Hybrid

If you need a "in between" solution, we encourage you to mix these two approaches to get the best of both worlds.

e.g. Create your own first layer banner, and let UsercentricsUI take care of the complexity on a second layer.