Skip to main content
Version: Isle Royale (2.5.0)

Manual Acceptance

By default, the ToughClicks library automatically creates acceptance records once all checkboxes are checked and a valid user identifier is set. However, you may want more control over when acceptances are created. Manual acceptance mode gives you this control.

Overview​

Manual acceptance mode allows you to:

  • Control the exact moment when acceptance records are created
  • Coordinate acceptance with other form submissions
  • Add custom validation before acceptance
  • Implement multi-step workflows
  • Show loading states during acceptance

When to Use Manual Acceptance​

Consider using manual acceptance when:

  • You have a form submission that should include ToughClicks acceptance
  • You need to validate other fields before creating acceptances
  • You want to show a loading state while acceptances are being created
  • You need to coordinate multiple asynchronous operations
  • You want explicit control over the acceptance timing

Enabling Manual Acceptance​

Set the manualAcceptance option to true in your display options configuration:

const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

const options = {
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email-input',
manualAcceptance: true // Enable manual acceptance
};

tc.setDisplayOptions(options);

When manual acceptance is enabled, the library will not automatically create acceptance records. You must explicitly call the accept() method.

See Display Options for more information about configuration.

The accept() Method​

The ToughClicks library exposes an accept() method that you call when you want acceptance records to be created.

Syntax:

const success = await tc.accept();

Returns: Promise<boolean>

  • true - Acceptance records were created successfully
  • false - Acceptance creation failed

Side effects:

When called, the accept() method will:

  1. Validate that all requirements are met (checkboxes checked, valid identifier)
  2. Send acceptance data to ToughClicks servers
  3. Fire the tc-accepted event upon completion
  4. Return a boolean indicating success

Basic Usage Example​

// Initialize with manual acceptance
const tc = new ToughClicks(clientToken, packetId);

tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email-input',
manualAcceptance: true
});

// Call accept when ready
document.getElementById('submit-btn').addEventListener('click', async () => {
const success = await tc.accept();

if (success) {
console.log('Acceptance created successfully');
// Proceed with your application flow
} else {
console.error('Failed to create acceptance');
// Handle failure
}
});

Working with Validation Events​

Use the tc-valid event to determine when it's safe to call accept():

const tc = new ToughClicks(clientToken, packetId);

tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email-input',
manualAcceptance: true
});

let canAccept = false;

// Track validation state
tc.on('tc-valid', (e) => {
canAccept = e.detail.isValid;

// Enable/disable submit button
const submitBtn = document.getElementById('submit-btn');
submitBtn.disabled = !canAccept;
});

// Only accept if validation passed
document.getElementById('submit-btn').addEventListener('click', async () => {
if (!canAccept) {
alert('Please accept all terms before proceeding');
return;
}

const success = await tc.accept();

if (success) {
// Navigate to next page
window.location.href = '/dashboard';
}
});

See Events for detailed information about event listeners.

Complete Form Integration Example​

Here's a complete example integrating ToughClicks with a registration form:

const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);

// Configure manual acceptance
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email',
manualAcceptance: true
});

let termsValid = false;

// Track ToughClicks validation
tc.on('tc-valid', (e) => {
termsValid = e.detail.isValid;
updateSubmitButton();
});

// Track terms acceptance completion
tc.on('tc-accepted', (e) => {
if (e.detail.allAccepted) {
console.log('Terms accepted, submitting form');
submitRegistrationForm();
}
});

// Form submission
document.getElementById('registration-form').addEventListener('submit', async (e) => {
e.preventDefault();

// Validate form
if (!validateForm()) {
alert('Please fill out all required fields');
return;
}

// Validate terms
if (!termsValid) {
alert('Please accept all terms before proceeding');
return;
}

// Disable submit button
const submitBtn = document.getElementById('submit-btn');
submitBtn.disabled = true;
submitBtn.textContent = 'Processing...';

try {
// Create acceptance records
const success = await tc.accept();

if (!success) {
throw new Error('Failed to create acceptance records');
}

// tc-accepted event will handle form submission
} catch (error) {
console.error('Error during acceptance:', error);
alert('An error occurred. Please try again.');

// Re-enable submit button
submitBtn.disabled = false;
submitBtn.textContent = 'Submit';
}
});

function validateForm() {
// Your form validation logic
const email = document.getElementById('email').value;
const name = document.getElementById('name').value;
return email && name;
}

function updateSubmitButton() {
const submitBtn = document.getElementById('submit-btn');
const formValid = validateForm();
submitBtn.disabled = !(formValid && termsValid);
}

async function submitRegistrationForm() {
// Submit your form data
const formData = {
email: document.getElementById('email').value,
name: document.getElementById('name').value
};

try {
const response = await fetch('/api/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(formData)
});

if (response.ok) {
window.location.href = '/welcome';
} else {
alert('Registration failed. Please try again.');
}
} catch (error) {
console.error('Registration error:', error);
alert('An error occurred. Please try again.');
}
}

Loading States​

Show a loading state while acceptance is being processed:

document.getElementById('submit-btn').addEventListener('click', async () => {
const button = document.getElementById('submit-btn');
const spinner = document.getElementById('loading-spinner');

// Show loading state
button.disabled = true;
button.textContent = 'Processing...';
spinner.style.display = 'inline-block';

try {
const success = await tc.accept();

if (success) {
button.textContent = 'Success!';
// Proceed with your flow
} else {
button.textContent = 'Failed - Try Again';
button.disabled = false;
}
} catch (error) {
button.textContent = 'Error - Try Again';
button.disabled = false;
} finally {
spinner.style.display = 'none';
}
});

Error Handling​

Always handle potential errors when calling accept():

try {
const success = await tc.accept();

if (success) {
// Handle success
console.log('Acceptance created');
} else {
// Handle failure
console.error('Acceptance failed');
showErrorMessage('Unable to process acceptance. Please try again.');
}
} catch (error) {
// Handle exception
console.error('Exception during acceptance:', error);
showErrorMessage('An unexpected error occurred.');
}

You can also listen for the tc-internal-error event:

tc.on('tc-internal-error', (e) => {
console.error('ToughClicks error:', e.detail.error);
showErrorMessage('Unable to process terms acceptance.');
});

See Error Handling for more information.

Best Practices​

1. Always Check Validation State​

Before calling accept(), ensure the validation state is valid:

let isValid = false;

tc.on('tc-valid', (e) => {
isValid = e.detail.isValid;
});

// Later...
if (isValid) {
await tc.accept();
}

2. Disable UI During Processing​

Prevent duplicate submissions by disabling controls during acceptance:

button.disabled = true;
await tc.accept();
// Re-enable only if needed (e.g., on error)

3. Use the tc-accepted Event​

Don't rely solely on the return value. Use the tc-accepted event for final confirmation:

tc.on('tc-accepted', (e) => {
if (e.detail.allAccepted) {
// Definitely all accepted, safe to proceed
completeWorkflow();
}
});

const success = await tc.accept();
// Event will fire regardless of return value

4. Coordinate with Other Async Operations​

Use Promise.all() if you need to coordinate multiple async operations:

const [acceptSuccess, apiSuccess] = await Promise.all([
tc.accept(),
submitToAPI(formData)
]);

if (acceptSuccess && apiSuccess) {
// Both succeeded
}

Automatic vs Manual Acceptance​

FeatureAutomaticManual
When acceptance occursWhen checkboxes checked + valid IDWhen you call accept()
ControlLess controlFull control
ComplexitySimplerMore complex
Best forSimple flowsComplex forms, multi-step workflows
Loading statesHarder to implementEasy to implement
ValidationBuilt-in onlyCustom validation possible