Manage Widget

The Manage Widget in DataGuard CPM is designed for use on pages where the user is authenticated, meaning a Citizen already exists and may have existing Permissions and Preferences recorded. This widget is ideal for scenarios such as my account pages or unsubscribe pages.

For step by step setup instructions, refer to the Using the Manage Widget how-to guide. Once you have done the initial setup, use this page as a reference for the various configuration properties available for the Manage Widget.

Insert the Script

To add the Manage Widget to your page, insert the following script tag in your HTML:

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

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

Load the Widget

Once the script is added, you need to call the widget load function. Ensure this is done inside a "load" event to make sure the widget code script has fully loaded before running the widget load function:

<script>
    window.addEventListener('load', () => {
        StatefulWidget.load({ ... });
    });
</script>

Replace the ... with your desired configuration. Below are the configuration options:

Required Properties

• id: Set this to the id of the div where the widget should be rendered, e.g., <div id="dataguard"></div>. This should always be an empty div as the widget will replace any existing content.
• templateId: The id of the template to be used to render the widget.
• token: Manage Widgets require a token that identifies and authorises a Citizen. Refer to the Citizen Token documentation for more information.

Optional Properties

• ruleId: The id of a Rule Set that enables features like progressive consent or mandatory preferences.
• locale: Specifies the locale to render. This is only necessary if using a localised template. The locale must exist on the template; otherwise, the default language will be rendered. See Localisation for more information.
• submitAsPending: Enables double opt-in for this widget. If enabled, new consents will be marked as pending double opt-in instead of granted. See the Double Opt-In documentation for more information.
• campaign: Adds a campaign tag to all transactions created from Citizens interacting with this widget. See the Campaigns documentation for more information.

Optional Properties for CRM Widget Functionality

• channel: Records which channel the change was made through. The default is web, but you may override this to something else, e.g., crm, email, telephone.
• displayName: Overrides the name of the person who made the change. By default, this is the Citizen's own external reference. If an employee is making the change on behalf of a customer, set this to their employee reference or id.
• clientName: Overrides the client name that made the change. The default is "Access Token," indicating it was made using a Citizen token. You can use this for custom identifiers, e.g., Salesforce or your proprietary CRM platform.

Display Configuration

The display section controls how the widget is rendered on the page:

• display.applyDefaultStyle: Controls whether the default stylesheet is loaded to apply basic styles or if it should be left unstyled so you can apply your own styles.
• display.location: Specifies where the widget is rendered on the page. The default is centre, which renders the widget in a pop-up. Often you will want to override the default to inside instead to render it the flow of a form. Options include: inside, top-left, top-right, bottom-left, bottom-right, centre.
• display.displayButtons: If set to false, the close, cancel, and submit buttons will be hidden, allowing you to use your own buttons. Use the submit action (see the Actions section below) to submit a form without buttons.
• display.displayCancelButtons: If set to false, the close and cancel buttons will be hidden, leaving only the submit button.
• display.displayAllNoneOptions: If set to true, "all/none" buttons will be displayed, allowing users to opt-in or opt-out of all Permissions and Preferences shown in the widget.
• display.displayValueCards: If set to false, value cards (additional information shown when a user opts in or out) will be hidden.
• display.closeOnSubmit: If set to false, the widget will show a success message after submission instead of it being hidden.

Events

The events section lets you set up listeners for various events, allowing you to react to changes in the widget:

• events.onUpdate: Fires when the widget first loads or when a user modifies the state (e.g., selecting a Permission or Preference).
• events.onSuccess: Fires when the user successfully submits the form, providing the request and response bodies.
• events.onFailure: Fires when the form submission fails, providing the error response and the request body.
• events.onLoadError: Fires if the widget fails to load when fetching initial data from the DataGuard platform, providing the error.
• events.onEmptyLoad: Fires when the widget loads but has no Permissions or Preferences to render, providing the current state and template details.

Actions

The widget load function returns an object with three actions: submit, cancel and isValid. Here is how to get the widget object: const widget = StatefulWidget.load({ ... });

• widget.submit: An asynchronous function that submits the widget, should be used when the buttons are hidden. On success, it returns the same information as the onSuccess event; on failure, it throws an error containing the same information as the onFailure event.
• widget.cancel: A function that hides the widget, equivalent to the user clicking the "cancel" or "close" button.
• widget.isValid: A function that returns the validity of the widget. This function returns an object of the following format: { isValid: boolean, errors: object }. If the widget is not valid, the errors object will contain more information about which fields are not valid. Note that it isn't possible to submit an invalid widget, so this function can be used to determine if the widget is ready to be submitted.

Styling

The widget look and feel is completely customisable using CSS. For more information on styling the widget, visit the Customise Widget Styling page.