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 successfullyfalse- Acceptance creation failed
Side effects:
When called, the accept() method will:
- Validate that all requirements are met (checkboxes checked, valid identifier)
- Send acceptance data to ToughClicks servers
- Fire the
tc-acceptedevent upon completion - 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
| Feature | Automatic | Manual |
|---|---|---|
| When acceptance occurs | When checkboxes checked + valid ID | When you call accept() |
| Control | Less control | Full control |
| Complexity | Simpler | More complex |
| Best for | Simple flows | Complex forms, multi-step workflows |
| Loading states | Harder to implement | Easy to implement |
| Validation | Built-in only | Custom validation possible |
Related Documentation
- Display Options - Configure manual acceptance mode
- Events - Listen for validation and acceptance events
- Error Handling - Handle acceptance errors
- Basic Usage - See automatic acceptance examples