Using the Sign Up Widget

The stateless sign-up widget provides a simple way to integrate a consent capture point for new users on your web page. It is specifically designed for new users, while for existing users, you can use the stateful manage widget.

Prerequisites

Before you start, make sure you have a Template created in DataGuard CPM that specifies the Permissions and Preferences you want to display.

Create this Template using the CPM UI. The same Template can be reused across multiple platforms, ensuring consistency.
Any changes to the Template are reflected instantly across all capture points that use it.

Integration Steps

The sign-up widget is designed to be integrated smoothly into your existing application. The example below demonstrates how to integrate the widget with a plain HTML page.

1. Add the HTML Structure

Start by creating an HTML form that includes an email input field, a placeholder div for the widget, and a submit button.

<form>
    <div>
        <label for="email">Email</label>
        <input type="text" id="email"/>
    </div>
    <div id="dataguard-widget"></div>
    <button id="register" type="button">Register</button>
</form>

2. Insert the Script Tag

Add the script tag to your HTML page to load the widget code:

<script src="<scripts-url>/history-widget.min.js" async=""></script>

Replace <scripts-url> with the correct URL for your environment. You can find the appropriate URL by checking the Environments page.

3. Configure the Widget

Configure the widget to display inside the div element by calling the load function. Example configuration:

<script>
    window.addEventListener('load', () => {
        let userId;
  
        const widget = ExpressStatelessCapturePoint.load({
            id: 'dataguard-widget', // This must be the id of the div from step 1.
            templateId: '<template-id>', // The id of the Template you created earlier.
            uniqueReference: () => userId, // A function that returns the user reference.
            display: {
                location: 'inside',
                closeOnSubmit: false,
                displayButtons: false, // Hide the buttons to allow the form's buttons to be used instead.
            },
        });
    });
</script>

4. Set the Citizen Reference

To ensure that both your system and DataGuard CPM have a common reference for the user, use the user’s id as the Citizen reference. Here’s an example of how to handle this by submitting the user id from your backend after the registration form is filled:

const submitForm = async () => {
    const response = await submitToYourOwnBackend();
    userId = response.userId;
    await widget.submit();
}

const submitToYourOwnBackend = async () => {
    // Replace this with your own backend submission logic
    return await fetch('', { method: 'POST', body: '{}' });
}

Alternatively, you can pass the email address in the contactDetails.verification.emailAddress field or use an agreed-upon id that is submitted both to your backend and DataGuard.

5. Submit the Form

Call the submitForm function when the user submits the registration form:

document
    .getElementById('register')
    .addEventListener('click', submitForm);

Success!

After completing these steps, the widget will submit the Citizen's Permissions and Preferences to DataGuard CPM. You can now manage their state directly through the platform.

Full HTML Example

Below is an example of how to embed the widget into your frontend. Make sure to replace the placeholders with the correct values.

Placeholder Values:

<scripts-url>: Found on the Environments page.
<template-id>: The id of the Template you created earlier.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <style>
        h1 {
            font-family: sans-serif;
            font-weight: 100;
        }

        form {
            max-width: 350px;
            margin: 0 auto;
        }
    </style>
    <title>Sign Up Widget</title>
</head>

<body>
<h1>Sign Up Widget Example</h1>
<form>
    <div>
        <label for="email">Email</label>
        <input type="text" id="email"/>
    </div>
    <div id="dataguard-widget"></div>
    <button id="register" type="button">Register</button>
</form>

<script src="<scripts-url>/capture-point.min.js" async=""></script>
<script>
    window.addEventListener('load', () => {
        let userId;
  
        const widget = ExpressStatelessCapturePoint.load({
            id: 'dataguard-widget',
            templateId: '<template-id>',
            uniqueReference: () => userId,
            display: {
                location: 'inside',
                closeOnSubmit: false,
                displayButtons: false,
            },
        });

        const submitForm = async () => {
            const response = await submitToYourOwnBackend();
            userId = response.userId;
            await widget.submit();
        }

        const submitToYourOwnBackend = async () => {
            // Replace this with your own backend submission logic
            return await fetch('', { method: 'POST', body: '{}' });
        }

        document
            .getElementById('register')
            .addEventListener('click', submitForm);
    });
</script>
</body>
</html>