Clickwrap Web Integration

Minimal sample, in plain HTML and vanilla JavaScript (no framework, no bundler), showing how to integrate the ClickWrap consent widget into a web page and how to send the user's consent on form submit.

It reproduces the pattern used internally in ClickWrap.Web.Sample, simplified and commented to serve as a reference for anyone integrating ClickWrap into a third-party site.

Structure

index.html          sample form + widget container
css/style.css        styling
js/configFetcher.js  reads config.json
js/app.js            ClickWrap integration logic
config.json           integration parameters (library URL, guid, environment)

How the integration works

1. Configuration. config.json holds three values provided by the ClickWrap backoffice for your agreement:

   • clickwrapLibraryUrl: URL of the namirial_wrap.js script to load at runtime.
   • cwGuid: identifier of the agreement/consent version configured in ClickWrap.
   • environment: which ClickWrap environment to query (e.g. staging, production).

2. Loading the library. The ClickWrap library isn't installed via npm: it's imported as an ES module at runtime from the URL in the configuration:

   const { clickWrap } = await import(config.clickwrapLibraryUrl);

3. Rendering the widget. clickWrap.render(options, selector) mounts the consent text and the required checkboxes inside the element given by selector (in the sample, #namirial__click-wrap).

4. Waiting for the render. ClickWrap fires a global CustomEvent named namirial-renderAgreement once the widget is ready. Use it to hide a loading placeholder and avoid showing the user an empty container before the text arrives.

5. Validating on submit. Before submitting the form, clickWrap.isValidCheck(selector) checks that all required checkboxes are ticked. If not, ClickWrap shows its own message (configured via messageValidation) and the submit is aborted.

6. Sending the consent. clickWrap.sendingConsents(email, true) records the user's consent on the ClickWrap side, associated with the email provided in the form. It's asynchronous (it makes a real network call), so it must be awaited before treating the submission as successful.

All of these steps are commented directly in js/app.js.

Running the sample

npm start

Opens the page at http://localhost:8080. config.json already points to a real test agreement on the demo environment (test-agreement-01, cwGuid dc79a8ce-606d-44bf-978b-0fcc34e2f7f8), so the sample works right away with no changes.

Where to find clickwrapLibraryUrl and cwGuid for your own agreement

In the ClickWrap backoffice, open the agreement and go to the Code tab: it shows a ready-made snippet with clickwrapLibraryUrl (the URL in the import) and cwGuid for that specific agreement/environment. It's the same snippet reproduced in js/app.js, just using a dynamic import() instead of a static <script type="module">.

To integrate your own real agreement, replace clickwrapLibraryUrl and cwGuid with the ones for your environment:

Environment	clickwrapLibraryUrl
demo	https://clickwrap-demo.namirial.app/namirial_library/namirial_wrap.js
test	https://clickwrap-test.namirial.app/namirial_library/namirial_wrap.js
production	https://clickwrap.namirial.app/namirial_library/namirial_wrap.js

cwGuid is specific to the agreement configured in the ClickWrap backoffice and differs per environment/agreement: the ClickWrap team provides it together with the URL above.

Notes

• The widget requires cwGuid to match an agreement actually configured in the given ClickWrap environment: with a non-existent guid, the render never emits namirial-renderAgreement.
• sendingConsents makes a network call to the ClickWrap backend: every submission is a real consent record, not a simulated one.
• The form fields' id/name matter. The agreement's Forms Elements tab (in the ClickWrap backoffice) lists the fields the library expects to read from the hosting form (in our test agreement: name, surname, email). The inputs in index.html use these same name attributes — otherwise ClickWrap can't associate the values with the submitted consent.
• The CORS policy on the ClickWrap API side only allows requests from specific origins (e.g. *.namirial.app domains, plus a few whitelisted local ports such as http://localhost:8080). If the widget fails to render with a CORS error in the console, the origin you're serving the sample from isn't in that allowlist.