UsercentricsUI¶

Usercentrics UI is a native UI component designed to own all the complexity of compliance, while also allowing different levels of customization.

This component consists of 2 Layers:

LeanBanner

First Layer¶

The First Layer is designed to be friendly to end-users, compact and highly customizable. This layer can be presented in 3 different ways:

PopupSheetFull

LeanBanner

Recommendation

Use the First Layer when collecting consent for the first time or when prompting updates to the consent services. Remember that user's will be able to navigate from the First Layer to the Second Layer.

To present the First Layer, simply create an instance of UsercentricsBanner, and call showFirstLayer(). Once the user provides their consent choices, a userResponse object will be returned.

iOSAndroidFlutterReact Native

let banner = UsercentricsBanner()
banner.showFirstLayer(hostView: self, // UIViewController
                        layout: <UsercentricsLayout>) { userResponse in
    // Handle userResponse
}

TODO - Check if snippet is correct. We do not want to show any customization options here

val banner = UsercentricsBanner(<Context>)
banner.showFirstLayer(layout = <UsercentricsLayout>) { 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.

final userResponse = await Usercentrics.showFirstLayer(
    layout: <UsercentricsLayout>
);
    // Handle userResponse

const firstLayerOptions: FirstLayerOptions = {
    layout: <UsercentricsLayout>,
    bannerSettings: {
        firstLayerSettings: <FirstLayerStyleSettings?>,
        secondLayerSettings: <SecondLayerStyleSettings?>,
        generalStyleSettings: <GeneralStyleSettings?>
    }
};

const userResponse = await Usercentrics.showFirstLayer(firstLayerOptions);

Second Layer¶

The Second Layer is designed to own all the complexity of compliance, declare all legally required information and allow for granular choices.

Second Layer

Recommendation

Use the Second Layer to allow users to review their choices from your apps settings.

To present the Second Layer, similarly create an instance of UsercentricsBanner, and call showSecondLayer(). The same userResponse object will be returned here as well.

iOSAndroidFlutterReact Native

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

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.

final userResponse = await Usercentrics.showSecondLayer( );
    // Handle userResponse

const secondLayerOptions: SecondLayerOptions = {
    bannerSettings: {
        secondLayerSettings: <SecondLayerStyleSettings?>,
    }
};
const userResponse = await Usercentrics.showSecondLayer(secondLayerOptions);

Handling UserResponse¶

The userResponse object provided in the callback of UsercentricsUI, contains the following information:

Properties	Type	Notes
consents	[UsercentricsServiceConsent]	List of the user's consent choices needed to apply consent.
userInteraction	Enum	Response given by user: AcceptAll: User accepted all services, DenyAll: User denied all service. Granular: User gave a granular choice, No Interaction: User dismissed the Banner with no response.
controllerId	String	A Usercentrics generated ID, used to identify a specific user. This value is required when using Cross-Device Consent Sharing.

You have successfully collected consent! 🚀

Now, it is fundamental that the user's privacy choices are applied to the 3^rd party SDKs on you App. Please continue to Apply Consent.

Customization¶

User experience is a relevant variable when collecting consent. We highly encourage you to take advantange of our customization features, in order to provide a branded and user friendly banner to your users.

Remote Customization¶

Use our Remote Customization options, for a quick out-of-the-box branding that covers all the basics.

LeanBanner

In the Appearance section of our Admin Interface, you will find the Layout and Styling tabs:

LayoutStyling

Under Display Options, you will find the following options:

Hide "Deny All" button
Hide Language switch

Showing the Language Switch

The language switch will only be shown in the Second Layer, and both of the following requirements need to be fulfilled:

Multiple visible languages are added in the Configuration section of the Admin Interface.
The "Hide language switch" option is disabled in the Appearance section of the Admin Interface, under the "Layout" tab.

Colors: Set individual colors by providing a specific HEX or using our color picker for the following banner elements:

Background Color
Text Color
Links Color
Tab Color
Accent Color
Button Colors
Tabs Color
Toggle Colors

Colors

Text Font and Size: Only supported via Programmatic Customization.

Logo: Set an image to appear at the top of your banner by providing a URL, as well as it's position:

Supported URL Image Formats

When passing a URL to fetch an image, the SDK supports: iOS: PNG and JPEG. Android: PNG, JPEG, BMP, GIF and WebP.

Supporting SVG Images

As SVG is not a format supported by mobile operating systems, we have provided an ad-hoc solution that requires the addition of dedicaded SVG libraries to your project.

iOSAndroid

Add SVG kit via Cocoapods:

pod 'SVGKit'

Add Pixplicity to your build.gradle:

implementation 'com.pixplicity.sharp:sharp:1.1.3@aar'

Once added, the Usercentrics SDK will make use of it when an SVG needs to be rendered.

Admin Interface

Any changes to the properties available here, will only take effect with a new init of the SDK and clean/updated cache.

Forcing configuration updates during Testing

You may force a configuration update by using the reset() function, or by deleting the app and installing it again. We only recommend doing this when integrating and testing the SDK.

Configuration updates in Production

The SDK caches essential data on device after the first successful init, in order to be efficient with resources and provide offline capabilities. This cache is kept for several days, depending on app usage. Which means user's will not get "Published" changes from the Admin Interface immediately, but we can guaranty changes will take effect for 100% of your user base latest within a week.

Programmatic Customization¶

Use our Programmatic Customization API, to create advance banner designs and run-time variants. Using this API unlocks features like A/B Testing & Dark Mode.

Compliance Note

Because the Programmatic API enables many customization options, it is important that your DPO (Data Protection Officer) reviews and approves the compliance of your design:

e.g.

A user should always have clear options to accept, deny or save granular choices available as call to actions in the 1^st or 2^nd layer.
The First Layer should always allow a path to the Second Layer.
Calls to action should be equally prominent.

Programmatic Customization

When creating the UsercentricsUI banner, a BannerSettings property will be available for you to customize any element of the banner.

iOSAndroidFlutterReact Native

let bannerSettings = BannerSettings(generalStyleSettings: <GeneralStyleSettings?>,
                                      firstLayerSettings: <FirstLayerStyleSettings?>,
                                     secondLayerSettings: <SecondLayerStyleSettings?>)

let banner = UsercentricsBanner(bannerSettings: bannerSettings)

val bannerSettings = BannerSettings(
    generalStyleSettings = <GeneralStyleSettings?>,
    firstLayerSettings = <FirstLayerStyleSettings?>,
    secondLayerSettings = <SecondLayerStyleSettings?>,
)

val banner = UsercentricsBanner(context, bannerSettings)

// First Layer
final response = await Usercentrics.showFirstLayer(
    layout: <UsercentricsLayout>,
    firstLayerSettings: <FirstLayerStyleSettings?>,
    secondLayerSettings: <SecondLayerStyleSettings?>,
    generalStyleSettings: <GeneralStyleSettings?>
);

// Second Layer
final response = await Usercentrics.showSecondLayer(
    secondLayerSettings: <SecondLayerStyleSettings?>,
    generalStyleSettings: <GeneralStyleSettings?>
);

// First Layer
const firstLayerOptions: FirstLayerOptions = {
    layout: <UsercentricsLayout>,
    bannerSettings: {
        firstLayerSettings: <FirstLayerStyleSettings?>,
        secondLayerSettings: <SecondLayerStyleSettings?>,
        generalStyleSettings: <GeneralStyleSettings?>
    }
};

const response = await Usercentrics.showFirstLayer(firstLayerOptions);

// Second Layer
const secondLayerOptions: SecondLayerOptions = {
    bannerSettings: {
        secondLayerSettings: <SecondLayerStyleSettings?>,
    }
};
const response = await Usercentrics.showSecondLayer(secondLayerOptions);

Dark Mode

Use the customization API to define both light and dark designs and use depending on device theme.

let lightBannerTheme = BannerSettings(...) // define light theme
let darkBannerTheme = BannerSettings(...) // define dark theme

let theme = (<Device Theme Dark?>) = darkBannerTheme : lightBannerTheme
let banner = UsercentricsBanner(theme)
banner.showFirstLayer(hostView: self, layout: <UsercentricsLayout>) { }

General Style Settings¶

General Style Settings values overwrite Remote Style values

Properties	Type	Notes
textColor	Color	Edit the text color for both First Layer and Second Layer.
layerBackgroundColor	Color	Edit the color of the First Layer and Header and Footer of the Second Layer.
layerBackgroundSecondaryColor	Color	Edit the color of the background in the content section.
linkColor	Color	Edit the color of all available links.
tabColor	Color	Edit the color of the Category and Services Tabs.
bordersColor	Color	Edit the color for the borders of the Category and Services content section, Category and Service components and Service Information Tags.
toggleStyleSettings	Object	Edit the toggle colors for: Active, Inactive and Disabled states.
font	Font	Pass both Regular and Bold fonts to be used in the banner.
logo	Image	Pass a local image to be rendered as a logo in both First Layer and Second Layer.
links	Enum	Customize the visibility of the legal links: .both (default), .firstLayerOnly, .secondLayerOnly and .none.

First Layer Style Settings¶

First Layer Style Settings values overwrite General Style Settings values.

Properties	Type	Notes
headerImage	Enum	Customize the layout of the image at the top of your banner: .logo (default), .extended or .hidden.
title	Object	Customize the appearance of the title label: Font, Text Color and Text Alignment.
message	Object	Customize the appearance of the message label: Font, Text Color, Text Alignment, Link Text Color and Link Text Underline.
buttonLayout	Enum	Customize the layout of the action buttons: .column (default), .grid, .row. You may also pass an array of [ButtonSettings] to define the order and appearance of the buttons.
backgroundColor	Color	Edit the color of the First Layer background.
cornerRadius	Float	Edit the corner radius of the banner.
overlayColor	Color	Edit the color of the First Layer overlay.

Second Layer Style Settings¶

Second Layer Style Settings values overwrite General Style Settings values.

Properties	Type	Notes
buttonLayout	Enum	Customize the layout of the action buttons: .column (default), .grid, .row. You may also pass an array of [ButtonSettings] to define the order and appearance of the buttons.
showCloseButton	Bool	Show a close button in the Second Layer to allow users to dismiss the banner without editing consent.

Swift UI¶

You can build your iOS interface with Swift UI.

Simply create a View with a body and design it however you like it, you can see more about SwiftUI here. Then call the UsercentricsBanner methods showFirstLayer() and showSecondLayer() to show the first and second layer respectively. These overloaded methods do not receive the hostView has mentioned in the sections above. The sdk finds the top most view of the app and uses that view to show the banner.

```
let banner = UsercentricsBanner()
banner.showFirstLayer(layout: <UsercentricsLayout>) { userResponse in
    // Handle userResponse
}
```

On iOS Sample App you can see an example of how to integrate with SwiftUI.