Migration Guide
Learn how to migrate from the single-packet API to the multi-packet API and take advantage of new features in ToughClicks.
Overview
ToughClicks has evolved to support multiple document packets, allowing you to manage different document sets with individual configuration. This guide will help you:
- Understand the differences between single and multi-packet APIs
- Migrate existing single-packet implementations
- Adopt new features while maintaining backward compatibility
- Avoid common migration pitfalls
The multi-packet API is backward compatible. Existing single-packet implementations will continue to work without changes. This guide is for those who want to adopt the new multi-packet features.
What's New in Multi-Packet API
Key Changes
- Array-based packet IDs - Pass an array instead of a single string
- Per-packet display options - Configure each packet independently
- Optional packets - Mark packets as optional for opt-in consent
- Enhanced validation - Separate validation for each packet
- New API methods -
setPacketDisplayOptions(),setAllPacketDisplayOptions(), etc.
Benefits
- Better separation of concerns - Keep required legal docs separate from optional marketing consent
- Flexible UX - Use different display methods for different packets
- Targeted rendering - Render packets in different parts of your page
- Improved validation - Fine-grained control over validation logic
Migration Path
Step 1: Assess Your Current Implementation
First, identify how you're currently using ToughClicks:
// Current single-packet implementation
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true
});
tc.render();
Step 2: Choose Your Migration Strategy
You have three options:
Option A: No Changes (Recommended for Simple Cases)
If you only need one packet, keep your existing code:
// This still works!
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({ /* options */ });
tc.render();
When to use: Single packet use case, no immediate need for new features
Option B: Minimal Migration (Quick Upgrade)
Convert to array syntax but keep same behavior:
// Before
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({ /* options */ });
// After
const tc = new ToughClicks(clientToken, [packetId]);
tc.setPacketDisplayOptions(packetId, { /* options */ });
When to use: Want to prepare for future multi-packet support
Option C: Full Migration (Maximum Features)
Adopt full multi-packet API with constructor options:
// Before
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true
});
// After
const tc = new ToughClicks(
clientToken,
[packetId],
false, // debug
TCEnvironment.production, // environment
[
{
packetId: packetId,
displayOptions: {
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
optional: false
}
}
]
);
When to use: Adding multiple packets or using optional packets
Step 3: Update Your Code
Basic Migration
Before:
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
const tc = new ToughClicks(
'your-client-token',
'your-packet-id'
);
tc.setDisplayOptions({
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
manualAcceptance: false
});
tc.render();
After (Minimal Changes):
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
const tc = new ToughClicks(
'your-client-token',
['your-packet-id'] // Now an array
);
tc.setPacketDisplayOptions('your-packet-id', {
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
manualAcceptance: false
});
tc.render();
After (Constructor Options):
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
const tc = new ToughClicks(
'your-client-token',
['your-packet-id'],
false, // debug mode
undefined, // environment (defaults to production)
[
{
packetId: 'your-packet-id',
displayOptions: {
containerId: 'tc-agreements',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
manualAcceptance: false,
optional: false
}
}
]
);
tc.render();
Adding Additional Packets
Once migrated to array syntax, adding packets is straightforward:
Adding Required Packets
const tc = new ToughClicks(
clientToken,
['terms-packet', 'privacy-packet'], // Multiple packets
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.scroll,
shouldOpenModal: true,
optional: false // Required
}
},
{
packetId: 'privacy-packet',
displayOptions: {
containerId: 'privacy-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
optional: false // Required
}
}
]
);
Adding Optional Packets
Perfect for marketing consent, newsletters, etc.:
const tc = new ToughClicks(
clientToken,
['terms-packet', 'marketing-packet'],
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
optional: false // Required
}
},
{
packetId: 'marketing-packet',
displayOptions: {
containerId: 'marketing-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
optional: true // Optional - user can skip
}
}
]
);
Event Handling Changes
Single Packet Events
Before:
tc.on('tc-valid', (event) => {
console.log('Is valid:', event.detail.isValid);
submitButton.disabled = !event.detail.isValid;
});
tc.on('tc-accepted', (event) => {
console.log('All accepted:', event.detail.allAccepted);
if (event.detail.allAccepted) {
submitForm();
}
});
Multi-Packet Events
After:
tc.on('tc-valid', (event) => {
// New property for multi-packet
console.log('All packets valid:', event.detail.allPacketsValid);
// Individual packet validation
event.detail.validatedPackets.forEach((packet) => {
console.log(`Packet ${packet.id}: ${packet.isValid ? 'Valid' : 'Invalid'}`);
});
// Enable submit when all required packets are valid
submitButton.disabled = !event.detail.allPacketsValid;
});
tc.on('tc-accepted', (event) => {
console.log('All accepted:', event.detail.allAccepted);
console.log('Acceptances:', event.detail.acceptances);
if (event.detail.allAccepted) {
submitForm();
}
});
Checking Individual Packet Validity
// New method for checking specific packet
const isTermsValid = tc.isPacketValid('terms-packet');
const isPrivacyValid = tc.isPacketValid('privacy-packet');
console.log('Terms valid:', isTermsValid);
console.log('Privacy valid:', isPrivacyValid);
Verification Changes
Single Packet Verification
Before:
const verification = await tc.verify({ userId: '[email protected]' });
console.log('User compliant:', verification.userCompliant);
Multi-Packet Verification
After:
// Verify all packets
const verifications = await tc.verify({ userId: '[email protected]' });
// verifications is an array with one entry per packet
verifications.forEach((verification) => {
console.log(`Packet ${verification.id}:`, verification.userCompliant);
});
// Check if all packets are compliant
const allCompliant = verifications.every((v) => v.userCompliant);
Verify Specific Packet:
const verification = await tc.verify({
userId: '[email protected]',
packetId: 'terms-packet'
});
console.log('Terms packet compliant:', verification.userCompliant);
Framework-Specific Migrations
React Migration
Before (Single Packet):
import { useEffect, useState } from 'react';
import { ToughClicks } from '@toughclicks/js-client-sdk';
function TermsAcceptance({ email }) {
const [isValid, setIsValid] = useState(false);
useEffect(() => {
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({
containerId: 'tc-agreements',
signerId: email,
displayMethod: TCDisplayMethod.individual
});
tc.on('tc-valid', (e) => {
setIsValid(e.detail.isValid);
});
tc.render();
}, [email]);
return (
<div>
<div id="tc-agreements"></div>
<button disabled={!isValid}>Submit</button>
</div>
);
}
After (Multi-Packet):
import { useEffect, useState } from 'react';
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
function TermsAcceptance({ email }) {
const [isValid, setIsValid] = useState(false);
useEffect(() => {
const tc = new ToughClicks(
clientToken,
['terms-packet', 'privacy-packet'],
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerId: email,
displayMethod: TCDisplayMethod.individual,
optional: false
}
},
{
packetId: 'privacy-packet',
displayOptions: {
containerId: 'privacy-container',
signerId: email,
displayMethod: TCDisplayMethod.individual,
optional: false
}
}
]
);
tc.on('tc-valid', (e) => {
setIsValid(e.detail.allPacketsValid); // Updated property
});
tc.render();
}, [email]);
return (
<div>
<div id="terms-container"></div>
<div id="privacy-container"></div>
<button disabled={!isValid}>Submit</button>
</div>
);
}
Vue Migration
Before:
<template>
<div>
<div id="tc-agreements"></div>
<button :disabled="!isValid">Submit</button>
</div>
</template>
<script>
import { ToughClicks } from '@toughclicks/js-client-sdk';
export default {
data() {
return {
isValid: false,
tc: null
};
},
mounted() {
this.tc = new ToughClicks(this.clientToken, this.packetId);
this.tc.setDisplayOptions({
containerId: 'tc-agreements',
signerId: this.email
});
this.tc.on('tc-valid', (e) => {
this.isValid = e.detail.isValid;
});
this.tc.render();
}
};
</script>
After:
<template>
<div>
<div id="terms-container"></div>
<div id="privacy-container"></div>
<button :disabled="!isValid">Submit</button>
</div>
</template>
<script>
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
export default {
data() {
return {
isValid: false,
tc: null
};
},
mounted() {
this.tc = new ToughClicks(
this.clientToken,
['terms-packet', 'privacy-packet'],
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerId: this.email,
displayMethod: TCDisplayMethod.individual
}
},
{
packetId: 'privacy-packet',
displayOptions: {
containerId: 'privacy-container',
signerId: this.email,
displayMethod: TCDisplayMethod.individual
}
}
]
);
this.tc.on('tc-valid', (e) => {
this.isValid = e.detail.allPacketsValid;
});
this.tc.render();
}
};
</script>
Angular Migration
Before:
import { Component, OnInit } from '@angular/core';
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
@Component({
selector: 'app-terms',
template: `
<div id="tc-agreements"></div>
<button [disabled]="!isValid">Submit</button>
`
})
export class TermsComponent implements OnInit {
private tc: ToughClicks;
public isValid = false;
ngOnInit() {
this.tc = new ToughClicks(
environment.tcClientToken,
environment.tcPacketId
);
this.tc.setDisplayOptions({
containerId: 'tc-agreements',
signerId: this.userEmail,
displayMethod: TCDisplayMethod.individual
});
this.tc.on('tc-valid', (e) => {
this.isValid = e.detail.isValid;
});
this.tc.render();
}
}
After:
import { Component, OnInit } from '@angular/core';
import { ToughClicks, TCDisplayMethod } from '@toughclicks/js-client-sdk';
@Component({
selector: 'app-terms',
template: `
<div id="terms-container"></div>
<div id="privacy-container"></div>
<button [disabled]="!isValid">Submit</button>
`
})
export class TermsComponent implements OnInit {
private tc: ToughClicks;
public isValid = false;
ngOnInit() {
this.tc = new ToughClicks(
environment.tcClientToken,
['terms-packet', 'privacy-packet'],
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerId: this.userEmail,
displayMethod: TCDisplayMethod.individual,
optional: false
}
},
{
packetId: 'privacy-packet',
displayOptions: {
containerId: 'privacy-container',
signerId: this.userEmail,
displayMethod: TCDisplayMethod.individual,
optional: false
}
}
]
);
this.tc.on('tc-valid', (e) => {
this.isValid = e.detail.allPacketsValid;
});
this.tc.render();
}
}
Common Migration Scenarios
Scenario 1: Separating Terms and Marketing Consent
Goal: Keep required legal terms separate from optional marketing consent.
const tc = new ToughClicks(
clientToken,
['legal-packet', 'marketing-packet'],
false,
undefined,
[
{
packetId: 'legal-packet',
displayOptions: {
containerId: 'legal-terms',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.scroll,
shouldOpenModal: true,
optional: false // Required
}
},
{
packetId: 'marketing-packet',
displayOptions: {
containerId: 'marketing-consent',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: false,
optional: true // Optional - user can skip
}
}
]
);
Scenario 2: Different Display Methods
Goal: Use scroll for terms, individual checkboxes for privacy.
const tc = new ToughClicks(
clientToken,
['terms-packet', 'privacy-packet'],
false,
undefined,
[
{
packetId: 'terms-packet',
displayOptions: {
containerId: 'terms-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.scroll, // Scroll through
shouldOpenModal: true
}
},
{
packetId: 'privacy-packet',
displayOptions: {
containerId: 'privacy-container',
signerIdSelector: 'userEmail',
displayMethod: TCDisplayMethod.individual, // Individual checkboxes
shouldOpenModal: false
}
}
]
);
Scenario 3: Progressive Enhancement
Goal: Start with single packet, add more over time.
Phase 1 - Initial:
const tc = new ToughClicks(clientToken, ['terms-packet']);
tc.setPacketDisplayOptions('terms-packet', { /* options */ });
Phase 2 - Add Privacy:
const tc = new ToughClicks(clientToken, ['terms-packet', 'privacy-packet']);
tc.setPacketDisplayOptions('terms-packet', { /* options */ });
tc.setPacketDisplayOptions('privacy-packet', { /* options */ });
Phase 3 - Add Optional Marketing:
const tc = new ToughClicks(
clientToken,
['terms-packet', 'privacy-packet', 'marketing-packet'],
false,
undefined,
[
{ packetId: 'terms-packet', displayOptions: { /* options */ } },
{ packetId: 'privacy-packet', displayOptions: { /* options */ } },
{ packetId: 'marketing-packet', displayOptions: { optional: true, /* options */ } }
]
);
API Method Comparison
Constructor
| Old API | New API |
|---|---|
new ToughClicks(token, packetId) | new ToughClicks(token, [packetId]) |
| N/A | new ToughClicks(token, packetIds, debug, env, context, packetDisplayOptions) |
Display Options
| Old API | New API |
|---|---|
tc.setDisplayOptions(options) | tc.setPacketDisplayOptions(packetId, options) |
| N/A | tc.setAllPacketDisplayOptions(optionsArray) |
| N/A | tc.getPacketDisplayOptions(packetId) |
Validation
| Old API | New API |
|---|---|
tc.isValid() | tc.isValid() (still works for overall validity) |
| N/A | tc.isPacketValid(packetId) (check specific packet) |
Events
| Old API Property | New API Property |
|---|---|
event.detail.isValid | event.detail.allPacketsValid |
| N/A | event.detail.validatedPackets (array of packet states) |
Testing Your Migration
Step-by-Step Testing
-
Verify Rendering
tc.render().then(() => {
console.log('Rendered successfully');
tc.printState(); // Inspect state
}); -
Test Validation
tc.on('tc-valid', (event) => {
console.log('All packets valid:', event.detail.allPacketsValid);
event.detail.validatedPackets.forEach((packet) => {
console.log(`${packet.id}: ${packet.isValid}`);
});
}); -
Test Acceptance
tc.on('tc-accepted', (event) => {
console.log('Acceptance event:', event.detail);
console.log('All accepted:', event.detail.allAccepted);
}); -
Test Verification
const verifications = await tc.verify({ userId: '[email protected]' });
console.log('Verification results:', verifications);
Checklist
- Library initializes without errors
- All packets render correctly
- Validation events fire for each packet
- Overall validation works correctly
- Optional packets don't block submission
- Acceptance creates for all checked packets
- Verification returns correct compliance status
- No console errors
- Backward compatibility maintained (if keeping single-packet code)
Common Pitfalls
1. Forgetting to Update Event Properties
Wrong:
tc.on('tc-valid', (event) => {
submitButton.disabled = !event.detail.isValid; // Old property
});
Correct:
tc.on('tc-valid', (event) => {
submitButton.disabled = !event.detail.allPacketsValid; // New property
});
2. Using Wrong Method for Display Options
Wrong:
const tc = new ToughClicks(token, [packetId]);
tc.setDisplayOptions(options); // Old method, won't work correctly
Correct:
const tc = new ToughClicks(token, [packetId]);
tc.setPacketDisplayOptions(packetId, options); // New method
3. Missing Container Elements
Each packet needs its own container:
Wrong:
// Two packets, one container
<div id="tc-agreements"></div>
tc.setPacketDisplayOptions('packet-1', { containerId: 'tc-agreements' });
tc.setPacketDisplayOptions('packet-2', { containerId: 'tc-agreements' }); // Conflict!
Correct:
// Two packets, two containers
<div id="terms-container"></div>
<div id="privacy-container"></div>
tc.setPacketDisplayOptions('packet-1', { containerId: 'terms-container' });
tc.setPacketDisplayOptions('packet-2', { containerId: 'privacy-container' });
4. Not Handling Optional Packets
Wrong:
// Expecting validation to wait for optional packet
tc.on('tc-valid', (event) => {
// This fires when required packets are valid,
// even if optional packet is unchecked
submitButton.disabled = !event.detail.allPacketsValid;
});
Correct:
tc.on('tc-valid', (event) => {
// allPacketsValid only considers required packets
// Optional packets don't affect this
submitButton.disabled = !event.detail.allPacketsValid;
// If you need to check optional packet specifically:
const marketingOptIn = tc.isPacketValid('marketing-packet');
console.log('User opted into marketing:', marketingOptIn);
});
Rollback Plan
If you encounter issues, you can easily roll back:
// Multi-packet implementation having issues
const tc = new ToughClicks(token, ['packet-1', 'packet-2']);
tc.setPacketDisplayOptions('packet-1', options1);
tc.setPacketDisplayOptions('packet-2', options2);
// Roll back to single packet
const tc = new ToughClicks(token, 'packet-1');
tc.setDisplayOptions(options1);
The single-packet API is still fully supported.
Getting Help
If you encounter issues during migration:
-
Enable Debug Mode
const tc = new ToughClicks(token, packetIds, true); // Debug enabled
tc.printState(); -
Check Console - Look for errors or warnings
-
Review Documentation
-
Contact Support - Email developers@toughclicks.com with:
- Your current code
- Migration strategy you're using
- Any error messages
- Debug logs (
tc.printState()output)
Next Steps
After migrating:
- Explore optional packets for consent management
- Use different display methods for different UX needs
- Implement force reacceptance workflows
- Set up testing and debugging for your multi-packet implementation