Headless widgets

Headless widgets enable you to create fully customizable widgets in terms of both design and behavior. These widgets rely on the Didomi’s widgets engine, so they feature authentication management, analytics, content rendering, purpose and preference choices, and saving upon clicking or after user confirmation.
The following set of elements, events and methods are available for generating the widget and collecting end-user consent and preference choices.

Custom elements

Custom elements are HTML components used to display the content of your widget as well as wrap your own HTML elements to handle specific communication with the Didomi API. Please refer to this documentation for more information about custom elements.
Please refer to our dedicated documentation on Didomi custom Elements for more information.

Custom events

Custom events are synthetic events in Javascript that can be dispatched to our SDK.
Use custom events to communicate with our custom elements to wrap your code and handle all logic, analytics and API requests.
Please refer to our dedicated documentation on custom events for more information.

Public Methods

Public methods are SDK methods that are made available to facilitate your interactions with our SDK, including getting information from the widget configuration and from the current user consent state.
Please refer to our dedicated documentation on public methods for more information.

Event listeners

Event listeners are JavaScript methods that set up a function to run whenever the specified event is delivered to the target.
You can use event listeners to provide UI feedback to your end-users, handle retries, and more. Since custom events don't support callbacks, this is how you can know the current state (loading, success, error) of an action that has been emitted.
Please refer to our dedicated documentation on event listeners for more information.

Setup

Widget format

To use a Headless widget, set the format to embeddable when creating the widget via the API.
Once created, the widget can be edited in the Didomi Console or using API. All sections are supported by a Headless widget, except for Look and Feel.
POST https://api.didomi.io/widgets?organization_id=YOUR_ORG_ID
{
"name": "My Headless widget",
"format": "embeddable"
}
Please refer to our dedicated documentation to learn how to create a widget using API.

Load SDK

To use a Headless widget, you first need to load our SDK. We recommend integrating the SDK loader at the top of your HTML.
💡 The SDK loader code to embed is available in the Didomi Console once you have created an embeddable widget.
Headless widget offers two ways to read the token:
Parameter
Description
shouldReadTokenFromLocalStorage
The widget searches in the local storage to retrieve the token and authenticate the end-user using the API. If you handle authentication yourself, use shouldReadTokenFromLocalStorage to read the token from local storage. You need to set the token as didomi_auth_token as described here.
shouldReadTokenFromURL
The widget searches in the URL to retrieve the token and authenticate the end-user using the API. If you handle authentication by email through Didomi, use shouldReadTokenFromURL to read the token from the URL included in the email.
<script>
window.didomiConfig = {
apiKey: "YOUR_API_KEY",
app: { apiKey: "YOUR_API_KEY" },
components: {
version: 2,
},
// to read the token from URL, use shouldReadTokenFromURL
// to read the token from local storage, use shouldReadTokenFromLocalStorage
user: { shouldReadTokenFromURL: true },
widgets: [],
};
</script>
<script
type="text/javascript"
async="true"
charset="utf-8"
src="https://sdk.privacy-center.org/v2/loader.js"
></script>

Load the Headless widget and its entities when the SDK is ready

After the SDK is ready, you can access the widget configuration and the entities enabled within the widget.
To access the configuration and obtain the entities, you can use our public methods.
To display the Headless widget once the container and entities are loaded you need to add the didomi-container-headless custom element.
window.didomiWidgetsOnReady = window.didomiWidgetsOnReady || [];
window.didomiWidgetsOnReady.push(async (DidomiWidgets) => {
const container = await DidomiWidgets.getContainerById("widgetId");
const entities = await container.getEntities();
});
<didomi-container-headless id="widgetId">
// Add your HTML here
</didomi-container-headless>
To avoid a flickering effect while the SDK is loading, you can use this CSS snippet. This can be applied to any custom element:
didomi-if-authenticated:not(:defined) {
display: none;
}
didomi-if-not-authenticated:not(:defined) {
display: none;
}

Elements

Example