npm package: @spotdraft/clickwrap-client
Description: SpotDraft Clickwrap/Clickthrough SDK — embed consent workflows in any web application
Author: SpotDraft
Latest version: 0.0.1

# 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:

```bash
npm install @spotdraft/clickwrap-client
```

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

```typescript
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

```javascript
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)

```html
<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:

```html
<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

```typescript
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

```javascript
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 |

```typescript
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:

```typescript
const payload = {
  user_identifier: "johndoe@example.com", // required field
  first_name: "John",
  last_name: "Doe",
  user_email: "johndoe@example.com"
};

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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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
<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

```typescript
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        |

---