Sign Up Widget

The Sign Up Widget in DataGuard CPM is designed for use on pages where a Citizen doesn't exist yet. This widget is ideal for scenarios such as sign up pages or data collection pages. When a user submits the Sign Up Widget, a Citizen is created with their newly selected Permissions and Preferences.

For step by step setup instructions, refer to the Using the Sign Up 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 Sign Up Widget.

Insert the Script

To add the Sign Up Widget to your page, first 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', () => {
        ExpressStatelessCapturePoint.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.
uniqueReference or contactDetails.verification.emailAddress: Sign Up Widgets require a way to identify the user once they are created. Use the uniqueReference field to provide a value for the Citizen's external reference. Or use the emailAddress field to provide an email address instead, the reference will then be auto-generated. Note you can supply a both a uniqueReference and and emailAddress if you would like. Both of these fields can take either a string or a function that returns a string that will be run on submit.

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 interacting with this widget. See the Campaigns documentation for more information.

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 two actions: submit and cancel. 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.

Styling

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