Spotdraft Clickthrough SDK Documentation

Introduction

Developers may include Clickthrough capabilities into their web applications quickly and efficiently using the JavaScript library provided by the Spotdraft Clickthrough SDK. Simplifying the process of obtaining user consent for contracts is SpotDraft Clickthrough. It enables you to demand that consumers acknowledge a contractual agreement before they can move forward.

You can incorporate the Spotdraft Clickthrough SDK into your application with the aid of this documentation. It will walk you through the procedure and notify you of the available configuration options and API methods.

Getting Started

Prerequisites

Make sure you have the following before starting:

• A Spotdraft Clickthrough account. If you don't have one, visit up at https://www.spotdraft.com/requestfordemo.
• Development environment with SSL enabled

Installation

Option A: NPM Package (recommended for modern apps)

Install the SDK via npm:

npm install @spotdraft/clickwrap-client

ES Modules (React, Angular, Vue, etc.)

import { SdClickthrough, SdClickthroughEvents } from "@spotdraft/clickwrap-client";

const sdk = new SdClickthrough({
  clickwrapId: "CLICKWRAP_ID_FROM_CONSOLE",
  hostLocationDomId: "my-clickthrough-host",
  baseUrl: "BASE_URL_FROM_CONSOLE"
});

await sdk.init();

sdk.on(SdClickthroughEvents.ACCEPTANCE_TOGGLED, (accepted) => {
  console.log("Acceptance changed:", accepted);
});

CommonJS

const { SdClickthrough } = require("@spotdraft/clickwrap-client");

const sdk = new SdClickthrough({
  clickwrapId: "CLICKWRAP_ID_FROM_CONSOLE",
  hostLocationDomId: "my-clickthrough-host",
  baseUrl: "BASE_URL_FROM_CONSOLE"
});

Browser (Script Tag from NPM)

<script src="node_modules/@spotdraft/clickwrap-client/browser/index.global.js"></script>
<script>
  const sdk = new SpotdraftClickwrap.SdClickthrough({
    clickwrapId: "CLICKWRAP_ID_FROM_CONSOLE",
    hostLocationDomId: "my-clickthrough-host",
    baseUrl: "BASE_URL_FROM_CONSOLE"
  });
  sdk.init();
</script>

Option B: Hosted CDN Script (legacy)

NOTE: All the following code snippets, with the right values for each, can be directly copied from the Spotdraft clickthrough console.

Add the following script tag to your HTML file (ideally in the head tag) to include the SDK:

<script type="module" src="https://sdk.spotdraft.com/clickwrap/v1/sdk.js"></script>

SdClickthrough will be attached to the window and the Spotdraft clickthrough will be loaded into your application.

Initialization

After installing the SDK, you must initialize it.

NPM Package

import { SdClickthrough } from "@spotdraft/clickwrap-client";

const sdClickthrough = new SdClickthrough({
  clickwrapId: "CLICKWRAP_ID_FROM_CONSOLE",
  hostLocationDomId: "HOST_ELEMENT_DOM_ID",
  baseUrl: "BASE_URL_FROM_CONSOLE"
});

await sdClickthrough.init();

Hosted CDN Script

window.addEventListener("sdClickthroughLoaded", function () {
  const sdClickthrough = new SdClickthrough({
    clickwrapId: "CLICKWRAP_ID_FROM_CONSOLE",
    hostLocationDomId: "HOST_ELEMENT_DOM_ID",
    baseUrl: "BASE_URL_FROM_CONSOLE"
  });
  sdClickthrough.init();
});

Display Modes

The SDK supports three layout modes via the displayConfig.layoutMode option:

| Mode | Description | | --------------------------- | -------------------------------------------------------- | | embedded-default | Renders checkboxes inline inside the host element | | embedded-agreement-viewer | Renders a full agreement viewer inside the host element | | modal | Opens a modal dialog with the agreement viewer on demand |

import { SdClickthrough, LayoutMode } from "@spotdraft/clickwrap-client";

const sdk = new SdClickthrough({
  clickwrapId: "CLICKWRAP_ID",
  baseUrl: "BASE_URL",
  displayConfig: {
    layoutMode: LayoutMode.MODAL,
    title: "Terms & Conditions",
    theme: {
      primaryColor: "#4F46E5"
    }
  }
});

await sdk.init();

// For modal mode, open the dialog when needed:
await sdk.openConsentDialog();

Creating Clickthrough Contract

The submit method enables you to create a clickthrough contract based on the provided agreement. Here's an example of how to use the submit method to create a clickthrough contract:

const payload = {
  user_identifier: "[email protected]", // required field
  first_name: "John",
  last_name: "Doe",
  user_email: "[email protected]"
};

sdClickthrough.submit(payload).then((data) => {
  // continue to submit the form
});

NOTE: user_identifier is a required field and can be any string (email, phone number etc) that uniquely identifies users across your platform.

Checking Clickthrough Agreement Acceptance

After showing the user the clickthrough agreement, you might want to restrict some operations, including submitting forms, until they have accepted the agreement. The isAccepted() method of the SDK enables you to determine whether a particular clickthrough agreement has been accepted by the user. Here is how to apply it:

if (sdClickthrough.isAccepted()) {
  // continue submitting your form
}

Passing Custom User Data

The Spotdraft Clickthrough SDK enables you to create clickthrough contracts in Spotdraft with customized payload data in addition to obtaining user approval. You can send a payload object to the submit method to be linked to the newly generated clickthrough contract. Any additional data or metadata pertinent to your application or operational procedures may be included in this payload.

As part of the submit payload:

const payload = {
  user_identifier: "123",
  additional_custom_information: {
    customField1: "Value 1",
    customField2: "Value 2"
  }
};

sdClickthrough.submit(payload).then((data) => {
  // continue to submit the form
});

Styling Clickthrough Elements

You can utilize the class names provided by the Spotdraft Clickthrough SDK to style the items that the SDK renders. To make these elements match the appearance and feel of your application, you can apply unique CSS styles. The list of class names includes:

• sd-clickthrough-checkbox: This class name can be used to target the checkbox element rendered by the SDK.
• sd-clickthrough-text: This class name can be used to target the text content displayed in the clickthrough agreement.

Event Handling

You can listen to events provided by the Spotdraft Clickthrough SDK in order to carry out particular tasks or react to user activities. To add event listeners to the SDK and record these events, use the on method. Here's an example:

import { SdClickthroughEvents } from "@spotdraft/clickwrap-client";

sdClickthrough.on(SdClickthroughEvents.CLICKWRAP_SDK_LOAD_SUCCESS, (data) => {
  console.log("clickthrough object loaded successfully!");
});

The following are the types of events you can listen to:

| Event | Description | | --------------------------- | ------------------------------------------------- | | acceptanceToggled | When users check/uncheck the checkbox | | acceptanceComplete | When all agreements are accepted | | sdClickthroughLoaded | When the clickthrough object successfully loads | | sdClickthroughLoadFailed | When the clickthrough object fails to load | | cancelClicked | When the cancel button is clicked (modal mode) |

Full Examples

NPM Package Example

import {
  SdClickthrough,
  SdClickthroughEvents,
  LayoutMode
} from "@spotdraft/clickwrap-client";

// Create and initialize
const sdk = new SdClickthrough({
  clickwrapId: "<CLICKWRAP_ID_FROM_CONSOLE>",
  hostLocationDomId: "my-clickthrough-host",
  baseUrl: "<BASEURL_FROM_CONSOLE>"
});

await sdk.init();

// Listen for acceptance changes
sdk.on(SdClickthroughEvents.ACCEPTANCE_TOGGLED, (accepted) => {
  document.getElementById("submit-button").disabled = !accepted;
});

// Submit handler
document.getElementById("form").addEventListener("submit", async (e) => {
  e.preventDefault();
  if (sdk.isAccepted()) {
    await sdk.submit({
      user_identifier: document.getElementById("email").value
    });
    e.target.submit();
  } else {
    alert("Please accept the policies to continue");
  }
});

Hosted CDN Script Example

<html lang="en">
  <body>
    <head>
      <script
        type="module"
        src="https://sdk.spotdraft.com/clickwrap/v1/sdk.js"
      ></script>
    </head>
    <form id="form">
      <!-- Form goes here -->
      <input id="email" type="text" />
      <div id="my-clickthrough-host"></div>
      <button id="submit-button"></button>
    </form>
    <script type="module">
      window.addEventListener("sdClickthroughLoaded", function () {
        const sdClickthrough = new SdClickthrough({
          clickwrapId: "<CLICKWRAP_ID_FROM_CONSOLE>",
          hostLocationDomId: "my-clickthrough-host",
          baseUrl: "<BASEURL_FROM_CONSOLE>",
        });
        sdClickthrough.init();
        sdClickthrough.on("acceptanceToggled", function (data) {
          console.log("accepted Event triggered:", data);
        });
      });

      const button = document.getElementById("submit-button");
      const form = document.getElementById("form");
      const email = document.getElementById("email");
      button.addEventListener("click", function (event) {
        event.preventDefault();
        if (!email.value) {
          alert("Please fill all the details");
        }
        if (sdClickthrough.isAccepted()) {
          sdClickthrough.submit({ user_identifier: email.value }).then((_) => {
            form.submit();
          });
        } else {
          alert("Please accept the policies to continue");
        }
      });
    </script>
  </body>
</html>

Migrating from Hosted SDK to NPM Package

If you are currently using the hosted CDN script and wish to migrate to the npm package:

1. Install the package: npm install @spotdraft/clickwrap-client
2. Remove the script tag: Delete <script src="https://sdk.spotdraft.com/clickwrap/v1/sdk.js"></script>
3. Remove the event listener: The sdClickthroughLoaded event is no longer needed
4. Import directly: import { SdClickthrough } from "@spotdraft/clickwrap-client"
5. Instantiate and init: Create your SDK instance and call await sdk.init() directly

The API methods (init, isAccepted, submit, on, openConsentDialog, closeConsentDialog) remain identical across both distribution methods.

API Reference

Constructor

new SdClickthrough(context: SdClickthroughContext)

| Parameter | Type | Required | Description | | ----------------------------- | ----------------------- | -------- | -------------------------------------------- | | context.clickwrapId | string | Yes | Clickwrap ID from SpotDraft console | | context.baseUrl | string | Yes | Base URL from SpotDraft console | | context.hostLocationDomId | string | No* | DOM element ID to render into | | context.displayConfig | ClickwrapDisplayConfig| No | Display and theming options |

*Required for embedded modes, optional for modal mode.

Methods

| Method | Returns | Description | | ----------------------- | ------------------ | ---------------------------------------------- | | init() | Promise<void> | Initialize the SDK and render the UI | | isAccepted() | boolean | Check if all agreements are accepted | | submit(payload) | Promise<unknown> | Submit the clickthrough contract | | on(event, callback) | void | Listen for SDK events | | openConsentDialog() | Promise<void> | Open the modal dialog (modal mode only) | | closeConsentDialog() | void | Close the modal dialog | | isReacceptanceRequired(userId) | Promise<unknown> | Check if re-acceptance is needed |

Development

Building for NPM

# Build the npm package (ESM + CJS + browser + types)
npm run nx run clickwrap-client-sdk:build-npm

# Build only specific formats
npm run nx run clickwrap-client-sdk:build-npm-lib      # ESM + CJS
npm run nx run clickwrap-client-sdk:build-npm-browser   # Browser IIFE
npm run nx run clickwrap-client-sdk:build-npm-types     # TypeScript declarations

Publishing to NPM

Publishing goes to your npm account at registry.npmjs.org. npm requires two-factor authentication (or a granular token with bypass 2FA) to publish.

# Publish as @spotdraft/clickwrap-client (requires 2FA on the account that owns @spotdraft)
nx run clickwrap-client-sdk:npm-publish --args="--ver=1.0.0 --tag=latest"

# Publish under your own npm username for now (e.g. @your-username/clickwrap-client)
nx run clickwrap-client-sdk:npm-publish --args="--ver=1.0.0 --tag=latest --scope=your-npm-username"

# Pre-release
nx run clickwrap-client-sdk:npm-publish --args="--ver=1.0.0-beta.1 --tag=next"

When you’re ready to publish under the @spotdraft org, run without --scope and ensure 2FA is enabled for that account.

Building the Hosted SDK (unchanged)

# Staging build
npm run nx run clickwrap-client-sdk:build

# Production (v1) build
npm run nx run clickwrap-client-sdk:build:v1

Running Tests

npm run nx test clickwrap-client-sdk