Skip to main content
Version: Isle Royale (2.5.0)

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
Backward Compatibility

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​

  1. Array-based packet IDs - Pass an array instead of a single string
  2. Per-packet display options - Configure each packet independently
  3. Optional packets - Mark packets as optional for opt-in consent
  4. Enhanced validation - Separate validation for each packet
  5. 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:

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​

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 APINew API
new ToughClicks(token, packetId)new ToughClicks(token, [packetId])
N/Anew ToughClicks(token, packetIds, debug, env, context, packetDisplayOptions)

Display Options​

Old APINew API
tc.setDisplayOptions(options)tc.setPacketDisplayOptions(packetId, options)
N/Atc.setAllPacketDisplayOptions(optionsArray)
N/Atc.getPacketDisplayOptions(packetId)

Validation​

Old APINew API
tc.isValid()tc.isValid() (still works for overall validity)
N/Atc.isPacketValid(packetId) (check specific packet)

Events​

Old API PropertyNew API Property
event.detail.isValidevent.detail.allPacketsValid
N/Aevent.detail.validatedPackets (array of packet states)

Testing Your Migration​

Step-by-Step Testing​

  1. Verify Rendering

    tc.render().then(() => {
    console.log('Rendered successfully');
    tc.printState(); // Inspect state
    });
  2. 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}`);
    });
    });
  3. Test Acceptance

    tc.on('tc-accepted', (event) => {
    console.log('Acceptance event:', event.detail);
    console.log('All accepted:', event.detail.allAccepted);
    });
  4. 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:

  1. Enable Debug Mode

    const tc = new ToughClicks(token, packetIds, true); // Debug enabled
    tc.printState();
  2. Check Console - Look for errors or warnings

  3. Review Documentation

  4. 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: