Caching
The ToughClicks library implements intelligent caching to provide faster load times and reduce the number of API requests. Understanding how caching works allows you to optimize performance for your use case.
Overview
By default, ToughClicks caches certain API requests locally in the browser. This caching:
- Reduces page load times for returning users
- Minimizes API requests to ToughClicks servers
- Improves perceived performance
- Reduces bandwidth usage
Important: ToughClicks does not cache any sensitive information such as acceptance records or personal data. Only non-sensitive configuration data is cached.
What is Cached
The library caches:
- Packet configuration - Display settings, document list
- Document metadata - Titles, versions, display order
- Public terms content - The text of terms and conditions
The library does not cache:
- User acceptance status
- Personal identifying information
- Acceptance records
- Authentication tokens
- Custom data
Default Cache Behavior
Default TTL (Time To Live): 24 hours
The library will cache API responses for 24 hours by default. After this period, the cache expires and fresh data is fetched from the server.
Example:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Default caching is automatic - no configuration needed
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email'
});
// First load: Fetches from server
// Subsequent loads within 24 hours: Uses cache
Customizing Cache TTL
You can customize the cache duration by calling setTTL() with a new TTL value in milliseconds.
Syntax:
tc.setTTL(milliseconds);
Parameters:
milliseconds- Cache duration in milliseconds (0 to disable caching)
Setting Custom TTL
Example - 12 hours:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Set cache TTL to 12 hours
const twelveHours = 1000 * 60 * 60 * 12;
tc.setTTL(twelveHours);
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email'
});
Example - 1 hour:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Set cache TTL to 1 hour
const oneHour = 1000 * 60 * 60;
tc.setTTL(oneHour);
Example - 7 days:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Set cache TTL to 7 days
const sevenDays = 1000 * 60 * 60 * 24 * 7;
tc.setTTL(sevenDays);
Disabling Cache
For testing, debugging, or situations where you always need fresh data, you can disable caching entirely by setting the TTL to 0.
Example:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Disable caching
tc.setTTL(0);
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email'
});
// Every load will fetch fresh data from the server
Important: If you disable caching and generate an excessive number of API calls, ToughClicks may reach out to discuss either optimizing your implementation or adjusting service fees to account for the increased server load.
When to Modify Cache Settings
Use Longer Cache (7+ days)
Consider a longer cache duration when:
- Your terms rarely change
- You want maximum performance
- You have high traffic volume
- Bandwidth costs are a concern
Example use case: Established application with stable terms
// Cache for 30 days
const thirtyDays = 1000 * 60 * 60 * 24 * 30;
tc.setTTL(thirtyDays);
Use Shorter Cache (1-6 hours)
Consider a shorter cache duration when:
- You update terms frequently
- You need users to see changes quickly
- You're actively developing/testing
- You have dynamic packet configurations
Example use case: Active development or frequently updated terms
// Cache for 1 hour
const oneHour = 1000 * 60 * 60;
tc.setTTL(oneHour);
Disable Cache (0ms)
Disable caching when:
- Testing new document versions
- Debugging integration issues
- Developing locally
- You need real-time updates
Example use case: Development environment
// Development environment - no cache
if (process.env.NODE_ENV === 'development') {
tc.setTTL(0);
}
// Production - use default cache
Cache Storage
The cache is stored in the browser's local storage. It persists:
- Across page reloads
- Across browser sessions
- Until the TTL expires
- Until the user clears browser data
Cache keys are unique per:
- Client token
- Packet ID
- API endpoint
This means different packets won't interfere with each other's cache.
Cache Invalidation
The cache automatically invalidates when:
- TTL expires - After the configured duration
- User clears browser data - Clears local storage
- Different packet loaded - Each packet has separate cache
- Library version changes - Major version updates may clear cache
Manual Cache Clearing
Users can clear the cache by:
- Clearing browser data/local storage
- Using browser developer tools
- Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
Programmatic Cache Clearing
The library provides a clearCache() method to programmatically clear all cached data:
// Clear all cached data
const success = tc.clearCache();
if (success) {
console.log('Cache cleared successfully');
}
Alternatively, you can force a refresh by setting TTL to 0 temporarily:
// Force a fresh fetch
tc.setTTL(0);
await tc.setDisplayOptions({ /* options */ });
// Restore normal caching
const twentyFourHours = 1000 * 60 * 60 * 24;
tc.setTTL(twentyFourHours);
Environment-Based Configuration
Configure different cache settings for different environments:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Environment-based TTL
const cacheTTL = {
development: 0, // No cache
staging: 1000 * 60 * 60, // 1 hour
production: 1000 * 60 * 60 * 24 // 24 hours
};
tc.setTTL(cacheTTL[process.env.NODE_ENV] || cacheTTL.production);
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email'
});
Performance Considerations
Cache Hit Performance
When data is cached:
- Load time: ~10-50ms (local storage read)
- No network requests
- Instant UI rendering
Cache Miss Performance
When cache expires or is disabled:
- Load time: ~100-750ms (network request - may depend on user's internet performance)
- API calls to ToughClicks servers
- Slight delay before UI rendering
Recommendations
For optimal performance:
- Use default caching for most production applications
- Longer TTL for stable, high-traffic applications
- Shorter TTL during active development of terms
- Disable caching only for debugging/testing
Monitoring Cache Behavior
Check browser developer tools to monitor caching:
// Enable debug logging (if supported)
console.log('ToughClicks cache TTL:', tc.getTTL ? tc.getTTL() : '24 hours (default)');
Check Network tab in browser DevTools:
- Cache hit: No API requests to ToughClicks
- Cache miss: API requests visible
Complete Configuration Example
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Determine cache strategy based on environment and needs
function getCacheTTL() {
// Development: no cache
if (window.location.hostname === 'localhost') {
return 0;
}
// Staging: short cache
if (window.location.hostname.includes('staging')) {
return 1000 * 60 * 60; // 1 hour
}
// Production: standard cache
return 1000 * 60 * 60 * 24; // 24 hours
}
// Set cache TTL
tc.setTTL(getCacheTTL());
// Configure display options
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerIdSelector: 'email'
});
console.log('Cache TTL:', getCacheTTL() === 0 ? 'Disabled' : `${getCacheTTL() / 1000 / 60 / 60} hours`);
Best Practices
- Use default caching in production for optimal performance
- Disable caching only when necessary (development, debugging)
- Match TTL to update frequency of your terms
- Consider bandwidth costs when setting long TTLs
- Test cache behavior across different scenarios
- Document cache settings in your codebase
- Monitor performance with and without caching
Troubleshooting
Not seeing document updates
Problem: Updated document versions aren't appearing Solution: Cache may not have expired yet
// Temporarily disable cache to force refresh
tc.setTTL(0);
Slow load times
Problem: Page loads slowly despite caching Solution: Verify cache is enabled
// Ensure caching is enabled (non-zero TTL)
tc.setTTL(1000 * 60 * 60 * 24); // 24 hours
Inconsistent behavior between users
Problem: Different users see different content Solution: Cache is per-browser, per-user
- This is expected behavior
- Each user's cache expires independently
- Clearing cache affects only that user/browser
Related Documentation
- Installation - Initial setup
- Basic Usage - Getting started
- Error Handling - Handle cache-related errors