Presenting the Banner

In order to collect user's consent, it' very important that you do so in a transparent and user-friendly way. To accomplish this, we have created an easy to integrate, out of the box banner solution, that owns all the complexity of compliance, while at the same time giving you endless customization options.

Banner API v2 🎉

Available starting v2.2.0

Content Switch on Banner API V1 starting v2.2.0

Please be aware that starting v2.2.0, the implementation of Banner API v1 will switch to using the content of the Second Layer given in the Admin Interface.

The main goal of Banner API v2 is to provide a highly customizable First Layer, that is friendly to end-users and promotes transparency, while having all compliance complexity delegated to a Second Layer.

The First Layer offers 3 different layout options:

Popup

Sheet

Full

These layouts can be customized via our Admin Interface for a straightforward brand integration:

or you can also take full advantage of our programmatic customization options and enable A/B Testing via our SDK API.

When should you collect consent?

You are free to decide when to collect consent. What is important, is that you do NOT enable any third party services or tracking technologies before the user has provided consent.

Once you are ready to collect consent, you may call isReady to make sure the SDK has fully initialized and use the UsercentricsReadyStatus object to know if you should show the banner or not.

iOS

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

Android

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

Flutter

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

React Native

try {
    const status = await Usercentrics.status();

    if (status.shouldCollectConsent) {
        showBanner();
    } else { 
        // Apply consents with status.consents
    } 
} catch(e) { 
    // Handle non-localized error 
}

Let's define what showBanner() should do...

Showing the Banner

You can decide to present the First Layer or Second Layer as you deem necessary for your user experience. However, we recommend to:

• Use the First Layer when collecting consent for the first time. Remember that user's will be able to navigate from the First Layer to the Second Layer.
• Use the Second Layer for when customers want to review their choices. e.g. In your app's settings.

Presenting the First Layer

iOS

let banner = UsercentricsBanner(bannerSettings: BannerSettings(firstLayerSettings: <FirstLayerStyleSettings>))
banner.showFirstLayer(hostView: self, // Host UIViewController 
                      layout: <UsercentricsLayout>, //.full, .sheet, .popup) { userResponse in
    // Handle userResponse
}

Deprecated UINavigationController as hostView on iOS

In versions v2.2.0 and v2.2.1, hostView is of type UINavigationController, and you can pass: self.navigationController!

Android

val banner = UsercentricsBanner(<Context>, BannerSettings(firstLayerSettings = <FirstLayerStyleSettings>))
banner.showFirstLayer(
    layout = <UsercentricsLayout> // FULL, SHEET, POPUP
) { userResponse ->
    // Handle userResponse
}

Use a valid Context

We are using the Dialog Android API for the Banner implementation. It is recommended to use a Context that is an Activity or derived/wrapper from it. Note that the Activity has to be alive for the dialog to be displayed.

Flutter

final userResponse = await Usercentrics.showFirstLayer(
    layout: <UsercentricsLayout>, // .full, .sheet, .popup
    logo: <UsercentricsImage>,
    font: <UsercentricsFont>,
    links: <LegalLinksSettings>, // .firstLayerOnly, .secondLayerOnly, .both, .none
    firstLayerSettings: <FirstLayerStyleSettings>,
    secondLayerSettings: <SecondLayerStyleSettings>,
);
// Handle userResponse

React Native

const options: FirstLayerOptions = { 
    layout: <UsercentricsLayout>, // .full, .sheet, .popup
    bannerSettings: {
        <BannerSettings>
        firstLayerSettings: <FirstLayerStyleSettings>
    }
};

const userResponse = await Usercentrics.showFirstLayer(options);
// Handle userResponse

Presenting the Second Layer

iOS

let banner = UsercentricsBanner(bannerSettings: BannerSettings(secondLayerSettings: <SecondLayerStyleSettings>))
banner.showSecondLayer(hostView: <UIViewController>) { userResponse in
    // Handle userResponse
}

Deprecated UINavigationController as hostView on iOS

In versions v2.2.0 and v2.2.1, hostView is of type UINavigationController, and you can pass: self.navigationController!

Android

val banner = UsercentricsBanner(<Context>, BannerSettings(secondLayerSettings = <SecondLayerStyleSettings>))
banner.showSecondLayer() { userResponse ->
    // Handle userResponse
}

Use a valid Context

We are using the Dialog Android API for the Banner implementation. It is recommended to use a Context that is an Activity or derived/wrapper from it. Note that the Activity has to be alive for the dialog to be displayed.

Flutter

final userResponse = await Usercentrics.showSecondLayer(
    logo: <UsercentricsImage>,
    font: <UsercentricsFont>,
    links: <LegalLinksSettings>, // .firstLayerOnly, .secondLayerOnly, .both, .none
    secondLayerSettings: <SecondLayerStyleSettings>,
);
// Handle userResponse

React Native

const bannerSettings: BannerSettings = {
    secondLayerSettings: {
        showCloseButton: true
    }
};
const options = new SecondLayerOptions(bannerSettings);

const userResponse = await Usercentrics.showSecondLayer(options);
// Handle userResponse

Handling User Response

After a user provides their consent choices, you will receive a UsercentricsConsentUserResponse object in the banner presentation callback. This object will provide you with all the information you need in order to apply consent, make decisions based on the user's interaction or store the user's ControllerID if you wish to support Cross-Device Consent Sharing.

What's next?

Now that you are able to present the banner and collect consent, let's continue with customizing the banner and applying consent.

Banner API v1 ⚠️

Deprecated

As Banner API v2 is now live, we have discontinue support for Banner API v1. Please consider:

• Banner API v2 fully replaces v1 and adds a lot more capabilities and functionality. We highly recommend upgrading.
• If you do not have time or resources to upgrade, please stick to v2.1.0 or lower to avoid any unexpected content or behaviour changes,
• Banner API v1 has been removed starting v2.3.0.

iOS

Once you are ready to present the CMP, call isReady to make sure the SDK is fully initialized. The callback will return a status to let you know if the CMP should be shown or not.

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

The next steps will define what showCMP() should do...

1. Request an instance of UsercentricsUI by calling getPredefinedUI():

   GDPR / CCPA / LGPD

   import UsercentricsUI
   
   var usercentricsUI: UIViewController?
   usercentricsUI = UsercentricsUserInterface.getPredefinedUI { ... }
   

   TCF 2.0

   import UsercentricsUI
   
   var usercentricsUI: UINavigationController?
   usercentricsUI = UsercentricsUserInterface.getPredefinedUI { ... }
   

2. Present the CMP and provide a dismiss block.

   usercentricsUI = UsercentricsUserInterface.getPredefinedUI { userResponse in
       // Apply Consent
       self.applyConsent(with: userResponse.consents)
   
       // Dismiss CMP
       self.usercentricsUI?.dismiss(animated: true, completion: nil)
   }
   
   // Present CMP
   guard let ui = usercentricsUI else { return }
   self.present(ui, animated: true, completion: nil)
   

   Presenting Modals in iOS 13 or later

   In most cases, you do not want to allow users to dismiss the CMP with a swipe down, if your UIViewController is presented modally in iOS 13 or later. You can disable this feature with the following line of code:

   if #available(iOS 13.0, *) { usercentricsUI.isModalInPresentation = true }
   

   Modal Presentation Styles

   Take advantage of the modalPresentationStyle property in order to modify the presentation style of the UI:

   usercentricsUI.modalPresentationStyle = .overFullScreen // UIModalPresentationStyle
   

   Pushing UIViewController

   To push a UIViewController instead of presenting it modally, use the following line:

   self.navigationController?.pushViewController(usercentricsUI, animated: true)
   

3. Use userResponse to know the user's interaction, consent choices or store the user's controllerID¹.

4. You have now collected consent, but you are not done yet. In the next section we will define applyConsent(...)

Android

Once you are ready to present the CMP, call isReady to make sure the SDK is fully initialized. The callback will return a status to let you know if the CMP should be shown or not.

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

The next steps will define what showCMP() should do...

There are two solutions to integrate the Predefined UI in Android:

• The Activity. A ready-to-use Android Activity.

• The View. A View instance that you can use in your layout.

Activity

This approach follow the official Android guidelines. In order to use it, the following steps are needed:

1. Register UsercentricsActivity in the fragment or activity where you want to use it. Save the ActivityResultLauncher in a member variable in order to use it later.

   private val usercentricsActivityLauncher = registerForActivityResult(UsercentricsActivityContract()) {
       // ...
   }
   

2. Launch UsercentricsActivity.

   usercentricsActivityLauncher.launch(UsercentricsUISettings())
   

3. Use userResponse to know the user's interaction, consent choices or store the user's controllerID¹.

4. You have now collected consent, but you are not done yet. In the next section we will define applyConsent(...)

   What to do in projects without AndroidX?

   You have to invoke manually startActivityForResult and process the result in the onActivityResult. You can still use UsercentricsActivityContract for that purpose:

   val intent = UsercentricsActivityContract().createIntent(context, UsercentricsUISettings())
   startActivityForResult(intent, requestCode)
   ...
   val result = UsercentricsActivityContract().parseResult(resultCode, result)
   

View

In order to use it, the following steps are needed:

1. Add UsercentricsPredefinedUI to the layout where you want to show the view.

   <com.usercentrics.sdk.UsercentricsPredefinedUI 
       android:id="@+id/usercentrics_view"
       android:layout_width="match_parent"
       android:layout_height="match_parent" />
   

2. Load the view and provide a onDismissView callback.

   private val usercentricsView by lazy { findViewById<UsercentricsPredefinedUI>(R.id.usercentrics_view) }
   ...
   // For example in the `onCreate` of your Activity/Fragment
   usercentricsView.load { userResponse ->
       applyConsent(userResponse?.consents)
   
       // Dismiss the CMP - finish your Activity/Fragment, remove the view, and so on
       finish()
   }
   

3. In order to provide a fully working navigation between layers, it is necessary to forward the Android's onBackPressed system event. TCF is the only variant that has multiple layers.

   override fun onBackPressed() {
       if (usercentricsView.onBackPressed()) return
       // ...
       super.onBackPressed()
   }
   

4. Use userResponse to know the user's interaction, consent choices or store the user's controllerID¹.

5. You have now collected consent, but you are not done yet. In the next section we will define applyConsent(...)

   Parent layout limitations

   We strongly recommend not using the view inside a complex layout. For example, inside a scroll view or a CoordinatorLayout.

Flutter

1. Present the CMP by calling showCMP():

   import 'package:usercentrics_sdk/all.dart';
   
   try {
     final response = await Usercentrics.showCMP();
     ...
   } catch (error) {
     // Handle non-localized error
   }
   

2. Use userResponse to know the user's interaction, consent choices or store the user's controllerID¹.

3. You have now collected consent, but you are not done yet. In the next section we will define applyConsent(...)

React Native

1. Present the CMP using Usercentrics.showCMP(<UsercentricsUIOptions>)

import { Usercentrics, UsercentricsUIOptions } from '@usercentrics/react-native-sdk';

try {
    let showCloseButton = false;
    let options = new UsercentricsUIOptions(showCloseButton);
    let response = await Usercentrics.showCMP(options);

...
} catch(error) {    
    // Handle Error
}

1. Use userResponse to know the user's interaction, consent choices or store the user's controllerID¹.

2. You have now collected consent, but you are not done yet. In the next section we will define applyConsent(...)

---

1. You should only store the controllerID if you are planning to use the Cross-Device Consent Sharing feature. ↩↩↩↩↩