Skip to main content
Version: Isle Royale (2.5.0)

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:

  1. TTL expires - After the configured duration
  2. User clears browser data - Clears local storage
  3. Different packet loaded - Each packet has separate cache
  4. 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:

  1. Use default caching for most production applications
  2. Longer TTL for stable, high-traffic applications
  3. Shorter TTL during active development of terms
  4. 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​

  1. Use default caching in production for optimal performance
  2. Disable caching only when necessary (development, debugging)
  3. Match TTL to update frequency of your terms
  4. Consider bandwidth costs when setting long TTLs
  5. Test cache behavior across different scenarios
  6. Document cache settings in your codebase
  7. 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