Overview

The helper script is meant to facilitate the embedding process of the LegalConsent widget into your form as a controlled iFrame. The helper’s interface allows you to adjust some styles and listen to various events related to user interaction with the LegalConsent widget.

Usage

Minimal Implementation

The minimal implementation requires only specifying the CONSENT_URL of the consent page you received from Get Legal Consent. Add the script to your HTML page.

<script src="https://sandbox.signup.nmi.com/build/consent-helper-1.0.0.umd.js"></script>
<script>
    LegalConsent.load('<CONSENT_URL>', { selector: '#consent' });
</script>

The selector defines the container where the <iframe> will be embedded (id, class, etc.). If not specified, it be appended to the HTML document body.

Advanced Implementation

For more control, you can leverage configuration options and event handlers.

<script src="https://sandbox.signup.nmi.com/build/consent-helper-1.0.0.umd.js"></script>
<script>
    LegalConsent.load(
        '<CONSENT_URL>',
        { selector: '#consent', overlay: 'transparent' },
        {
            onLoad: () => console.log('onLoad'),
            onAccepted: ({ accepted }) => console.log('onAccepted', accepted),
            onError: ({ message }) => console.log('onError', message),
        }
    );
</script>

API Reference

`LegalConsent.load(url, config, events)`

The main function to initialize the embed consent widget.

Parameters

Parameter	Type	Required	Description
url	String	Yes	The URL of the consent page to embed
config	Object	No	Configuration options for embedding (see Config Options table)
events	Object	No	Event handlers for various lifecycle events (see Events table)

Config Options

Property	Type	Required	Default	Description
selector	String	No	Body Element	CSS selector for the container where the iframe will be embedded
overlay	String	No	transparent	Background color (e.g., 'transparent', color names, hex codes)

Events

Event	Parameters	Description
onLoad	N/A	Triggered when the consent page is fully loaded
onAccepted	{accepted: boolean}	Triggered when the legal consent document: Is fully signed: accepted = true Signature is reset after been signed: accepted = false
onError	{message: string}	Triggered when an error occurs during loading or operation

Event

Parameters

Description

onLoad

N/A

Triggered when the consent page is fully loaded

onAccepted

{accepted: boolean}

Triggered when the legal consent document:

Is fully signed: accepted = true
Signature is reset after been signed: accepted = false

onError

{message: string}

Triggered when an error occurs during loading or operation

`LegalConsent.destroy()`

A function to clean up the embedded consent form by removing the iframe and event listeners.

Usage

// Load the consent form
LegalConsent.load('<CONSENT_URL}>);

// Later, when you need to remove it
LegalConsent.destroy();

Description

This method:

Removes the iframe created by LegalConsent.load()
Cleans up all event listeners attached to the iframe
Frees memory resources
Useful when integrating with single-page applications like React

📘
It is recommended to call LegalConsent.destroy() when removing the component from the DOM.

Example Scenarios

Embedding into a specific container

<div id="consent-container"></div>

<script src="https://sandbox.signup.nmi.com/build/consent-helper-1.0.0.umd.js"></script>
<script>
    LegalConsent.load(
        '<CONSENT_URL>',
        { selector: '#consent-container' }
    );
</script>

Disable form’s submit button until the consent is accepted using Events

<div id="consent-container"></div>
<button id="submit-button" disabled>Submit</button>

<script src="https://sandbox.signup.nmi.com/build/consent-helper-1.0.0.umd.js"></script>
<script>
    // Get reference to the submit button
    const submitButton = document.getElementById('submit-button');
    
    LegalConsent.load(
        '<CONSENT_URL>',
        { selector: '#consent-container' },
        {
            onAccepted: ({ accepted }) => {
                // Enable or disable the submit button based on consent status
                submitButton.disabled = !accepted;
                
                if (accepted) {
                    submitButton.classList.add('active');
                } else {
                    submitButton.classList.remove('active');
                }
            },
            onError: () => {
                // Disable button when an error occured
                submitButton.disabled = true;
                submitButton.classList.remove('active');
            }
        }
    );
</script>

Using with React Components

import React, { useEffect } from 'react';

const ConsentForm = () => {
  useEffect(() => {
    // Load the consent form when component mounts
    LegalConsent.load(
      '<CONSENT_URL>',
      { selector: '#react-consent-container' },
      { 
          onLoad: () => { ... },
          onAccepted: ({ accepted }) => { ... }, 
          onError: ({ message }) => { ... }
      }
    );
    
    // Clean up when component unmounts
    return () => {
      LegalConsent.destroy();
    };
  }, []);
  
  return <div id="react-consent-container"></div>;
};

export default ConsentForm;