Basic Usage (Single Packet)
Learn how to integrate ToughClicks with a single document packet. This is the simplest way to get started.
Three-Step Integration
Adding ToughClicks to your web application requires three primary steps:
- Initialize the library
- Set display options
- Render the checkboxes
Step 1: Initialize ToughClicks
First, create a new instance of the ToughClicks library:
import { ToughClicks } from '@toughclicks/js-client-sdk';
const tc = new ToughClicks(clientToken, packetId);
With CDN
<script src="https://cdn.toughclicks.com/lib/{version}/toughclicks.umd.js"></script>
<script>
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
</script>
Step 2: Configure Display and Global Settings
Configure how ToughClicks should behave in your application:
import { TCDisplayMethod } from '@toughclicks/js-client-sdk';
// Configure display options for the packet
tc.setPacketDisplayOptions({
packetId: 'your-packet-id',
displayOptions: {
containerId: 'tc-agreements', // Required: div to inject UI into
displayMethod: TCDisplayMethod.individual, // Optional: how to display checkboxes
shouldOpenModal: false, // Optional: open terms in modal
optional: false // Optional: whether packet is required
}
});
// Configure global settings
tc.setGlobalSettings({
signerIdSelector: 'userEmailInput', // Optional: input field for user identifier
signerId: null, // Optional: user identifier if you have it
manualAcceptance: false // Optional: manual vs automatic acceptance
});
Display Options
- packetId (required) - The packet ID these options apply to
- containerId (required) - The HTML element ID where ToughClicks will render the UI
- displayMethod (optional) - How to display agreement checkboxes (see Display Methods)
- shouldOpenModal (optional) - Whether document terms open in a modal (
true) or new tab (false) - optional (optional) - Whether this packet is required for acceptance
Global Settings
Choose one of the following for signer identification:
- signerIdSelector - ID of an input field (e.g., email input) that ToughClicks will monitor for the user's identifier
- signerId - Directly provide the user's identifier if you already have it
Additional global settings:
- manualAcceptance - Set to
trueto manually control when acceptances are created (see Manual Acceptance)
Step 3: Render the Checkboxes
Now render the ToughClicks UI:
tc.render();
This returns a Promise<boolean> indicating whether rendering was successful.
Complete Example
Here's a full working example:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://cdn.toughclicks.com/lib/latest/toughclicks.css" />
</head>
<body>
<form id="signup-form">
<label>Email:</label>
<input type="email" id="userEmail" required />
<!-- ToughClicks will inject checkboxes here -->
<div id="tc-agreements"></div>
<button type="submit" id="submit-btn" disabled>Sign Up</button>
</form>
<script src="https://cdn.toughclicks.com/lib/latest/toughclicks.umd.js"></script>
<script>
const { ToughClicks, TCDisplayMethod } = window.ToughClicks;
const packetId = '3646a13b-cbd1-482c-9947-460cb74a71f2';
// Initialize
const tc = new ToughClicks(
'477951a5-069b-401f-ab7f-32db486d5741',
packetId
);
// Configure display options
tc.setPacketDisplayOptions({
packetId: packetId,
displayOptions: {
containerId: 'tc-agreements',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true
}
});
// Configure global settings
tc.setGlobalSettings({
signerIdSelector: 'userEmail',
signerId: null,
manualAcceptance: false
});
// Render
tc.render();
// Listen for validation
tc.on('tc-valid', (event) => {
document.getElementById('submit-btn').disabled = !event.detail.isValid;
});
// Listen for acceptance
tc.on('tc-accepted', (event) => {
if (event.detail.allAccepted) {
alert('Thank you for accepting our terms!');
// Proceed with form submission
}
});
</script>
</body>
</html>
With a Frontend Framework
React Example
import { useEffect, useRef, useState } from 'react';
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
import '@toughclicks/js-client-sdk/toughclicks.css';
function TermsAcceptance() {
const tcRef = useRef(null);
const [isValid, setIsValid] = useState(false);
const [email, setEmail] = useState('');
useEffect(() => {
const packetId = 'your-packet-id';
// Initialize ToughClicks
const tc = new ToughClicks(
'your-client-token',
packetId
);
// Configure display options
tc.setPacketDisplayOptions({
packetId: packetId,
displayOptions: {
containerId: 'tc-agreements',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true
}
});
// Configure global settings
tc.setGlobalSettings({
signerId: email,
signerIdSelector: null,
manualAcceptance: false
});
// Listen for validation
tc.on('tc-valid', (e) => {
setIsValid(e.detail.isValid);
});
tc.render();
tcRef.current = tc;
return () => {
// Cleanup if needed
};
}, [email]);
return (
<div>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Your email"
/>
<div id="tc-agreements"></div>
<button disabled={!isValid}>
Accept and Continue
</button>
</div>
);
}
Vue Example
<template>
<div>
<input
v-model="email"
type="email"
placeholder="Your email"
/>
<div id="tc-agreements"></div>
<button :disabled="!isValid">
Accept and Continue
</button>
</div>
</template>
<script>
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
import '@toughclicks/js-client-sdk/toughclicks.css';
export default {
data() {
return {
email: '',
isValid: false,
tc: null
};
},
mounted() {
const packetId = 'your-packet-id';
this.tc = new ToughClicks(
'your-client-token',
packetId
);
// Configure display options
this.tc.setPacketDisplayOptions({
packetId: packetId,
displayOptions: {
containerId: 'tc-agreements',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true
}
});
// Configure global settings
this.tc.setGlobalSettings({
signerId: this.email,
signerIdSelector: null,
manualAcceptance: false
});
this.tc.on('tc-valid', (e) => {
this.isValid = e.detail.isValid;
});
this.tc.render();
},
watch: {
email(newEmail) {
// Update signer ID when email changes
if (this.tc) {
this.tc.setGlobalSettings({
signerId: newEmail,
signerIdSelector: null,
manualAcceptance: false
});
}
}
}
};
</script>
Next Steps
- Multiple Packets - Learn about handling multiple document packets
- Display Options - Explore all display configuration options
- Events - Set up event listeners for validation and acceptance
- Customization - Learn about CSS customization