Skip to content

Setup and integration

To begin, set up your dedicated configuration with widgets and your Preference Center by following these steps.

Login

Login using Auth0 authentication to the Usercentrics Preference Manager's admin interface: https://app.preference-management.usercentrics.eu/

Configurations management

The Configuration serves as the core component of the setup, acting as a container for all widgets (capture points).

The widgets then will be the building blocks for the Preference Center page.

Configurations list
Configurations list

The Usercentrics team is responsible for creating new Configurations for you and making them accessible to you (the customer) as the designated Owners of those Configurations.

Once a new configuration is created, the Owners can access and modify the Configuration according to their requirements.

The General Settings page within each Configuration contains the primary content field, which also corresponds to the end user's Preference Center page. This section includes the following elements:

  • Configuration Title -- this field represents the name of the Configuration and is used as the header for the corresponding Preference Center

  • Description -- this field accommodates free text that will be displayed on the Preference Center page

Each Configuration is assigned a unique ID, referred to as pacId. An example ID is: f0e1bc09-8b14-47a3-9aa2-ef40075f8c9a.

General Settings Tab

Once the Configuration is created, new widgets can be configured to capture end user's preferences.

You can delete a Configuration. In order to do so, all widgets associated with that Configuration should be deleted first.

Widgets management

The Widget is the core element acting as a capture point that the end users interacts with to save their preference data.

The Widgets tab is dedicated to widget management, where you can create, delete or update the capture points in use.

Widgets Tab

On the widgets list page, you can create a new widget or specify the visibility of the widget and the order in which the widget will be displayed in your Preference Center.

Each widget consists of the following main elements:

  • Widget Title -- the header of the widget that is displayed on top

  • Widget Description --the supportive text to provide the context and the basis of capturing a specific set of preference data

  • Preference Topic --this can be referred to as a question the user is asked and provides the logical group of data to be captured

  • Preference Option --the list of answers that end users can select from to specify their preferences. It can be introduced as single-select (radio buttons or drop-down) or multi-select list.

Widget - How end-user will see it

Each topic/set of options is limited to the selected widget and cannot be shared with or referred to from other widgets.

To create a new widget, click Add Widget and proceed with the Widget Configuration Wizard.

Edit Widget Screen 1

Edit Widget Screen 2

Within Widgets it is possible to create topics by clicking Add topic.

Each topic consists of a mandatory Name field, along with an optional Description text. The Description text enables you to provide valuable supplementary information about the stated question, enhancing the user's understanding.

This text field is fully customizable, enabling you to choose the right text to accompany the collection of data --- including legal texts, when necessary --- and also include link outs to external documents like your T&C or Privacy Policy.

Additionally, the Topic settings encompass the Selection Type and Mandatory flag. When the Mandatory flag is selected, users must provide at least one answer to the Topic before they can submit data for the entire widget.

A Topic must include a minimum of one Preference Option.

In addition, our widget configuration offers the flexibility to specify the order in which Topics and their corresponding points are rendered within the Widget.

This empowers you to organize the Widget's appearance according to specific preferences.

You can also define the default state of the Preference Option (checked/unchecked) by selecting the appropriate checkbox in the default column of the Options list. This initial state will affect the widget's appearance when an end user first encounters it, though it won't impact any implicit choices. Your end users are still required to save their selections to create a new preference object in the database.

Upon creating a Widget, a unique ID parameter is assigned, serving as a reference to the Widget. For example, the Widget ID: 6cedc12a-ea98-4628-8104-655ec452c4f2 uniquely identifies a specific Widget within our system.

You can have up to 10 unique Widgets per single Configuration.

Within our system, both the Widget and its corresponding translations can be edited at any given time, ensuring the flexibility to refine and enhance their content. However, it is important to note that once a Widget receives preference data from a user, specifically when preferences are saved under a specific Topic, that cannot be changed. In other words, editing the Topic type after preference data has been recorded will not be possible. Similarly, the deletion of Topics and Options is restricted to maintain data consistency and integrity.

Our platform offers additional opportunities for modification and expansion. You can add new Topics and Options to enrich the Widget's offerings, and the order of elements can be adjusted to suit your desired presentation. These functions enable you to continue to tailor the Widget to best meet the evolving needs of your users.

Implementation of the Preference Center into the website/app

The UC Preference Manager offers flexible integration options into your application, catering to various needs. You can seamlessly incorporate it through the following methods:

  1. Stand-alone Preference Center: Direct users via link to the stand-alone Preference Center app, that provides users 360-view over their preferences using a set of pre-configured widgets.

  2. Individual Embedded Widget: Embed specific widgets directly into your website for a more integrated user experience.

  3. Custom UI with Public API: Implement your custom user interface, interacting with the UC Preference Manager backend using Public API end-points.

  4. Front-end integration with existing website form: using a dedicated end-point to capture preference submission through existing forms, without the need to authenticate user in advance.

To facilitate operations in any of these scenarios, acquiring a JWT (JSON Web Token) access token is essential for each end-user interacting with the widget(s) under a specific Configuration ID. More detailed information on how to generate JWT token via UC PM Public API endpoins you can find under dedicated Public API section of this manual.

Stand-alone Preference Center

The Usercentrics'-hosted Preference Center web app serves as the primary touch point for end users to interact with a set of preconfigured widgets and manage all the preferences and permissions saved previously.

With each Configuration setup, a distinct Preference Center is created, accessible via a unique URL, that can be placed anywhere on your website or mobile app:

https://app-preference.preference-management.usercentrics.eu/?token=[JWT_TOKEN]&lng=[LANG_CODE]

Where - [JWT_TOKEN] - JWT access token generated for specific UserID and ConfigurationID - [LANG_CODE] - optional parameter, that defines localisation variant Preference Center should be displayed. Language code should be provided in ISO 639-1 format (e.g., 'en').

Preference Center

To preview the recently configured Preference Center, use the the PREVIEW function, that will render a complete representation of the Preference Center, mirroring the end user's view. During this preview, the widgets will be disabled, enabling you to review the Center's layout and content without any data submission taking place. This enables you to evaluate and fine tune the end user experience before it goes live.

Please note, we use a caching mechanism for configuration settings. Normally the changes become available for the end users within 10-15 minutes.

Embedded widgets

Integrate specific widgets directly into your website using the following code snippet: 

<div class="embedded-preference-widget" data-token="[JWT_TOKEN]" data-widgetid="[WIDGET_ID]" data-language="[LANG_CODE]"></div> 

<link href="https://embeddings.preference-management.usercentrics.eu/latest/styles.css" rel="stylesheet"> 
<script src="https://embeddings.preference-management.usercentrics.eu/latest/bundle.js"></script>
<Parameters provided in the <div> above:

  • JWT Token:
    • In advance generated access token for the given UserID.
  • WidgetID:
    • The ID of the widget you want to display.
  • Lang code:
    • The ISO code of the localization version you want to use (“en” if not defined).

Front-end integration

For some cases, where server-side implementation is not possible, we offer an alternative way to capture preference submissions using the dedicated end-point in a simplified way. This end-point is protected with a separate type of API Key - Public API Key, that can be generated under Account Settings section of Admin Interface, and does not require in advance generated Token, so can be used for non-authenticated users.

Before setting up, ensure that your website includes a form with the following fields: - Email address (typically a text input field) - Preference checkbox, if you don't have any, you can either to add a new element, or you can use any existing checkbox that already represents such decision

An example form with fields for email address and a consent checkbox.
An example form with fields for email address and a consent checkbox.

To capture the required data from your website's form, follow these steps:

  1. Locate the IDs of the form elements: Access the website source code and find the form's elements. Specifically, find:
    • Form ID (e.g., data_form)
    • Email Field ID (e.g., user_email)
    • Consent Checkbox Field ID (e.g., consent_field)
  2. These fields can be identified using the browser's inspection tool. Right-click on the form field you are identifying, select "Inspect," and review the form's HTML code to find the IDs.
  3. If there is no unique ID element available for this field, you can either add one, or use any existing css-selector ( .theElementClass or #theElementClass)

Once you have identified these IDs, you will need to enter them d the next step of the onboarding process.

Example of field IDs location
Example of field IDs location

Open Implementation section of the Admin interface and locate open check the Implementation option to Capture preferences from existing HTML form with Javascript code.

Pre-generated code snippets to capture data from existing HTML forms
Pre-generated code snippets to capture data from existing HTML forms

Proceed with 2 steps from this code - copy and paste the Javascript code directly into your web page’s HTML:

  1. Copy the script tag below and paste it into the < head > section of your website. Make sure it is placed on all pages, that either contain the data submission forms or post-submission landing pages.

<script src="https://dc.preference-management.usercentrics.eu/latest/data-collector.js"></script>

  1. Add the generated pre-generated code snippet right after the data capture form, ensuring it is placed immediately after the form. By doing so, whenever a user submits the form and consents to data use, the information will be captured and transmitted to the appropriate Google Ads Customer List.
<script>
  // Attach the preference management event listener
  window.setupForm({
    event: {
      // The element selector that you want to listen for an event, can be a form, button, etc
      // Use CSS selectors like:
      // - .theElementClass
      // - #theElementId
      // - div.anything > form
      elementSelector: '#[INSERT_FORM-ID_HERE]', // The form to capture preferences
      eventType: "submit", // The event type, usually form submission
      observeDomChanges: false,
    },
    widgetId: "1234abcd-22bb-33cc-44dd-12345678abcd", // Unique widget ID
    pacId: "1234abcd-22bb-33cc-44dd-12345678abcd", // Configuration ID
    publicApiKey: "7b931a0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxa0d1", // Public API key to authenticate
    userId: {
      selector: '#[INSERT_USEREMAIL-FIELD-ID_HERE]' // Capture user ID (email)
    },
    inputs: [
      {
        selector: '#[INSERT_CONSENT-FIELD-ID_HERE]', // Element capturing user preferences
        optionUuid: "1234abcd-22bb-33cc-44dd-12345678abcd", // Option ID for preferences,
        validate: function () {
          // (optional) Return validation result to prevent submission
          return true;
        }
      }
    ]
  });
</script>
Code snippet and link to Preference Center page added into the page HTML
Code snippet and link to Preference Center page added into the page HTML

Important Notes:

  1. Preference Overwrite: Subsequent submissions overwrite the previous state of the preference data object. For ongoing data management, we recommend using endpoints secured with Private API keys or tokens.
  2. Data Security: The Public API Key allows access to the Preference Manager. Using a Public API Key on the front end can expose it to the public. That’s why this type of API key can only be used with this endpoint. In addition, we can recommend to consider activation of Double Opt-In setting for the widget, the data being submitted to, so every submission for the new user will be validated via email.
  3. Audit Trails: Ensure transparency with audit logs tracking changes based on the API key owner or acting user.

There is also an option to integrate this logic using Google Tag Manager - please refer to our Knowledge Base for more details.

Once you finish these steps, your Preference Center setup will be complete, enabling seamless data capture and permission management for your end users.

See also advanced features overview