Customizing the Blocking Experience

Dfence provides a default blocking pop-in that automatically displays when concurrent access or device limits are detected. However, you can fully customize this experience to match your application's design and branding.

Default Behavior

When no custom handlers are provided, Dfence automatically displays a built-in pop-in that takes over the page content with an overlay, shows a clear message to explain why access is blocked, and provides action buttons allowing users to continue on the current device. The pop-in also includes an FAQ section with expandable information for additional help, and it automatically unblocks the user as soon as the blocking condition is cleared.

Language Support

The default pop-in supports automatic translation based on the user's browser language:

• English (en) - Default language
• French (fr) - Automatically displayed for French-speaking users

The SDK detects the browser language and displays messages in the appropriate language. If the browser language is not supported, it defaults to English.

Customizing the Blocking UI

You can replace the default pop-in with your own custom UI using the onBlock and onUnblock methods. These methods allow you to implement any UI pattern that fits your application's design.

Using onBlock and onUnblock

The onBlock method is called when a user should be blocked, and onUnblock is called when they should be unblocked. You can set these handlers using the queue pattern:

Copy
// Set custom block handler
dfence.onBlock(function() {
  // Your custom blocking UI logic here
});

// Set custom unblock handler
dfence.onUnblock(function() {
  // Your custom unblocking UI logic here
});

Important: These methods can be called before or after the SDK loads. If called before loading, the handlers are queued and executed when the SDK initializes.

Implementation Examples

Here are several common patterns for customizing the blocking experience:

Example 1: Custom Modal

Create a branded modal that matches your application's design:

Copy
dfence.onBlock(function() {
  // Create modal overlay
  const overlay = document.createElement('div');
  overlay.id = 'dfence-block-overlay';
  overlay.style.cssText = 'position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0,0,0,0.7); z-index: 9999; display: flex; align-items: center; justify-content: center;';
  
  // Create modal content
  const modal = document.createElement('div');
  modal.style.cssText = 'background: white; padding: 2rem; border-radius: 8px; max-width: 500px;';
  modal.innerHTML = `
    <h2>Account Already in Use</h2>
    <p>Your account is currently being used on another device. Please close other sessions to continue.</p>
    <button onclick="document.getElementById('dfence-block-overlay').remove()">Close</button>
  `;
  
  overlay.appendChild(modal);
  document.body.appendChild(overlay);
});

dfence.onUnblock(function() {
  // Remove modal when unblocked
  const overlay = document.getElementById('dfence-block-overlay');
  if (overlay) {
    overlay.remove();
  }
});

Example 2: Top Banner

Display a non-intrusive banner at the top of the page:

Copy
dfence.onBlock(function() {
  const banner = document.createElement('div');
  banner.id = 'dfence-banner';
  banner.style.cssText = 'position: fixed; top: 0; left: 0; width: 100%; background: #ff6b6b; color: white; padding: 1rem; text-align: center; z-index: 9999;';
  banner.textContent = '⚠️ Concurrent access detected. Please close other sessions.';
  document.body.insertBefore(banner, document.body.firstChild);
  
  // Prevent scrolling
  document.body.style.overflow = 'hidden';
});

dfence.onUnblock(function() {
  const banner = document.getElementById('dfence-banner');
  if (banner) {
    banner.remove();
  }
  document.body.style.overflow = '';
});

Example 3: Dimmed Page with Alert

Dim the page and show a browser alert:

Copy
dfence.onBlock(function() {
  // Dim the page
  document.body.style.opacity = '0.5';
  document.body.style.pointerEvents = 'none';
  
  // Show alert
  alert('Your account is being used on another device. Please close other sessions.');
});

dfence.onUnblock(function() {
  // Restore page
  document.body.style.opacity = '1';
  document.body.style.pointerEvents = 'auto';
});

Example 4: Redirect to Upgrade Page

Redirect users to an upgrade page when limits are reached:

Copy
dfence.onBlock(function() {
  // Redirect to upgrade page
  window.location.href = '/upgrade?reason=device-limit';
});