JavaScript SDK Configuration

The Dfence JavaScript SDK is configurable to fit your specific needs. This guide covers all available configuration options, methods, and advanced usage patterns.

Quick Start

The Dfence SDK is initialized using the dfence.load() function:

Copy
dfence.load('YOUR_TOKEN', {
  userId: 'USER_ID'
});

Parameters:

• token (string, required): Your Dfence project token
• config (object, required): Configuration object with at least userId defined

Configuration Options

The config object supports the following configuration options:

Configuration Example

Copy
dfence.load('YOUR_TOKEN', {
  userId: 'user_123',         // Required: Unique identifier for the current user
  enable: true,               // Optional: Enable/disable monitoring (default: true)
  mode: 'device-limit',       // Optional: 'concurrence' or 'device-limit' (default: 'concurrence')
  limit: 3,                   // Optional: Allow up to 3 active devices/sessions (default: 1)
  timeout: 4000,              // Optional: Custom API timeout in ms (default: 3000)
  url: 'https://detect.yourcompany.com', // Optional: Custom domain endpoint
  cookieName: 'my_dfence_cookie' // Optional: Custom cookie name (default: 'dfence')
});

Note: Only specify the fields relevant to your use case. The userId field and your project token are required; all other fields are optional with sensible defaults.

SDK Methods

Once the SDK is loaded, you can use the following methods on the dfence object:

• dfence.pause(): Pauses session monitoring. Useful when you want to temporarily stop detection (e.g., during maintenance, user logout, or specific user actions).
• dfence.resume(): Resumes session monitoring after it has been paused.
• dfence.event(eventName): Logs a custom event to the Dfence event bus. Useful for tracking specific user actions or business events. eventName (string, required): Name of the event to log
• dfence.onBlock(blockFunction): Sets a custom handler function that is called when a user should be blocked. This allows you to implement your own blocking UI instead of using Dfence's default pop-in. See Customizing the Blocking Experience for detailed examples and best practices.
• dfence.onUnblock(unblockFunction): Sets a custom handler function that is called when a user should be unblocked (when the blocking condition clears). Important: Always implement the onUnblock handler to clean up your custom UI when the blocking condition clears.

Each methods return the dfence object (for method chaining)

Events

The SDK dispatches a custom event when it finishes loading:

dfence:loaded

Dispatched on the window object when the SDK has finished initializing. Useful for knowing when the SDK is ready to use.

Copy
window.addEventListener('dfence:loaded', function() {
  console.log('Dfence SDK is ready!');
  // Your code here
});

Complete Example

Here's a complete example showing a typical integration:

Copy
<script type="text/javascript">
  // Dfence snippet here...
  
  // Initialize SDK
  dfence.load('YOUR_TOKEN', {
    userId: 'user_12345',
    mode: 'device-limit',
    limit: 3
  });
  
  // Set up custom blocking handlers
  dfence.onBlock(function() {
    showCustomBlockingModal();
  });
  
  dfence.onUnblock(function() {
    hideCustomBlockingModal();
  });
  
  // Listen for SDK ready event
  window.addEventListener('dfence:loaded', function() {
    console.log('Dfence SDK loaded successfully');
  });
</script>

Debug Mode

Enable debug mode by adding ?_dfencedebug=true to your URL. This will log detailed information about SDK operations to the browser console.

Copy
// URL: https://yourapp.com?_dfencedebug=true
// Console will show: "Dfence SDK initialized with debug mode"

Troubleshooting

SDK not starting

• Check userId: Ensure userId is set and not empty
• Check token: Verify your token is correct
• Check enable: Make sure enable is not set to false
• Check browser console: Enable debug mode to see detailed error messages

Blocking not working

• Verify mode and limit: Check that mode and limit are set correctly
• Check network requests: Use browser DevTools to verify API requests are being made
• Test with debug mode: Enable debug mode to see what's happening

Custom handlers not firing

• Check handler registration: Ensure onBlock and onUnblock are called before blocking occurs
• Verify function syntax: Make sure handlers are valid functions
• Check SDK initialization: Ensure the SDK has finished loading before expecting handlers to fire