Using the Manage Widget

The stateful manage widget allows a Citizen to view and modify their current Permissions and Preferences. Unlike the stateless sign-up widget, the manage widget requires backend integration to generate a Citizen token.

This guide is divided into two sections: Backend Steps (where you'll handle token generation) and Frontend Steps (where you'll embed the widget). Let's go through it step by step.

Prerequisites

Before you start, make sure you have:

1. 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.

2. The Citizen must already exist in your system.

Backend Steps

You'll need a small backend process to generate a Citizen token, which is necessary for the widget to display and manage their Permissions and Preferences.

Step 1: Authentication

Before generating a token, you need to set up authentication. Follow the steps in the API Authentication guide to authenticate with the DataGuard CPM platform.

Step 2: Create a Citizen Token

Once authenticated, use the on-demand access token endpoint to generate a token for the Citizen. This token is required for the widget to function. The following parameters are necessary:

• applicationId: Your application's id, available on the Credentials page in the CPM UI.
• externalRef: The unique reference for the Citizen in your system.
• expiryDate: Set an expiry date far enough into the future to ensure the Citizen can interact with the form. Typically, setting it for an hour or day is sufficient.

Make sure you use the correct API URL depending on your environment. Refer to the Environments page to find the right API URL.

Step 3: Return the Token to the Frontend

After generating the token, pass it to the frontend. You can include it in the query string or pass it in any way that suits your application.

Frontend Steps

Now that the backend has generated a token, you can integrate the manage widget into your page. Here’s how:

1. Add an HTML Div

In your HTML page, add an empty div where the widget will be rendered. For example:

<div id="dataguard-widget"></div>

2. Insert the Script Tag

Next, include the script tag that loads the widget code into your HTML page:

<script src="<scripts-url>/capture-point.min.js" async=""></script>

Replace <scripts-url> with the appropriate URL for your environment, found on the Environments page.

3. Configure the Widget

Configure the widget to display inside the div element by calling the load function and passing in the Citizen token you generated earlier. Example configuration:

<script>
    window.addEventListener('load', () => {
        const urlParams = new URLSearchParams(window.location.search);

        StatefulWidget.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.
            token: urlParams.get('token'), // The token generated in the backend steps.
            display: {
                location: 'inside',
                closeOnSubmit: false,
            },
        });
    });
</script>

Success!

Once you've completed these steps, the widget will be displayed on your page. Citizens can interact with it, and their Permissions and Preferences will automatically sync with DataGuard CPM. You can manage and query the Citizen's state directly through the CPM platform.

Full Code Examples

Backend Example (Node.js)

Here’s a complete backend example for generating the Citizen token. It includes the necessary environment variables.

Environment Variables:

• DATAGUARD_URL: The <api-url> for your environment, found on the Environments page.
• DATAGUARD_APP_ID: Available on the Credentials page in the CPM UI.
• DATAGUARD_API_KEY: Follow the API Authentication guide to create an API Key.

import axios from 'axios';

const serveRequest = async (reference) => {
    const tomorrow = new Date();
    tomorrow.setDate(tomorrow.getDate() + 1);

    const { data } = await axios.post(
        `${process.env.DATAGUARD_URL}/v1/access-tokens/tokens`,
        {
            applicationId: process.env.DATAGUARD_APP_ID,
            externalRef: reference,
            expiryDate: tomorrow.toISOString(),
        },
        {
            headers: {
                'X-API-Key': process.env.DATAGUARD_API_KEY,
            }
        }
    );

    return data.token;
}

This code generates a Citizen token valid for 24 hours, which can be passed to the frontend for rendering the widget.

Frontend Example (HTML)

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;
        }
    </style>
    <title>Manage Widget</title>
</head>

<body>
<h1>Manage Widget Example</h1>
<div id="dataguard-widget"></div>

<script src="<scripts-url>/capture-point.min.js" async=""></script>
<script>
    window.addEventListener('load', () => {
        const urlParams = new URLSearchParams(window.location.search);

        StatefulWidget.load({
            id: 'dataguard-widget',
            templateId: '<template-id>',
            token: urlParams.get('token'),
            display: {
                location: 'inside',
                closeOnSubmit: false,
            },
        });
    });
</script>
</body>
</html>