Cashfree Device Intelligence SDK Documentation

The Device Intelligence SDK is a user-friendly solution that allows businesses to gather important data directly from users' browsers. This SDK seamlessly captures essential information about users' browsing behavior, device characteristics, and security properties, providing businesses with valuable insights. By leveraging this comprehensive data collection, businesses can optimize their services, personalize user experiences, enhance fraud detection, and make informed decisions based on accurate and reliable information.

Key Features

• Modern Agent-based API: Efficient agent-based architecture similar to FingerprintJS with intelligent caching
• Unified Data Collection: Single API that collects both device data (browser info, system info, etc.) and risk data (bot detection, tampering detection, etc.)
• Configurable: Fine-grained control over which data points to collect
• Comprehensive: Collects 80+ data points covering device, browser, and security characteristics
• Performance Optimized: Built-in caching, timeout controls, and performance metrics
• Error Resilient: Comprehensive error handling with fallback mechanisms
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• Backward Compatible: Legacy API support for existing implementations

Architecture

The SDK has been designed with a modern agent-based architecture where all device intelligence data is collected through a single, comprehensive data type called BrowserInfo. This approach provides:

Agent-based Design

• Efficient Caching: Intelligent caching system that reduces redundant data collection
• Performance Optimization: Built-in performance metrics and timeout controls
• Error Resilience: Comprehensive error handling with multiple fallback strategies
• Resource Management: Optimized resource usage with proper cleanup mechanisms

Unified Data Structure

The unified approach combines:

• Device & Browser Data: OS, browser version, screen resolution, hardware info, etc.
• Security & Risk Data: Bot detection, tampering detection, VM detection, privacy settings, etc.
• User Experience Data: Timezone, language, installed fonts, plugins, etc.
• Network Data: IP address, WebRTC IPs, connection type, etc.
• Performance Metrics: Data collection timing, cache hit rates, visitor ID generation strategies
• Error Tracking: Comprehensive error logging and diagnostics

All methods now return this unified data structure, eliminating the need for separate device and risk data APIs.

Installation

1. Using NPM package

   npm install @cashfreepayments/deviceintel-js-sdk

2. Using CDN URL

   <script src="https://vssdk-prod.cashfree.com/device-intel-js-sdk/1.1.5/index.mjs"></script>

3. ES Module Import

   import DeviceIntelligence from 'https://vssdk-prod.cashfree.com/device-intel-js-sdk/1.1.5/index.mjs'

Note: Make sure only one of the above is present in your application

Installation & Usage

The SDK provides two main usage patterns:

1. Modern Agent-based API (Recommended)

The modern API uses an agent-based approach similar to FingerprintJS, which is more efficient and provides better caching:

Import via URL (ES Module)

import DeviceIntelligence from 'https://vssdk-prod.cashfree.com/device-intel-js-sdk/1.1.5/index.mjs'

// Initialize the agent
const agent = await DeviceIntelligence.load()

// Get unified device and risk data
const data = await agent.get({
  taskTimeout: 500,
  overallTimeout: 1000,
  options: { user_ip: false }
})

console.log(data) // Contains all 80+ unified data fields

Import via Script Tag

<script src="https://vssdk-prod.cashfree.com/device-intel-js-sdk/1.1.5/index.mjs"></script>
<script>
  (async () => {
    // Initialize the agent
    const agent = await window.DeviceIntelligence.load()

    // Collect comprehensive unified device intelligence data
    const data = await agent.get({
      taskTimeout: 500,
      overallTimeout: 1000,
      options: { user_ip: false }
    })

    console.log(data) // 80+ unified fields including device, browser, and risk data
  })()
</script>

Using NPM Package

import { load } from '@cashfreepayments/deviceintel-js-sdk'

// Initialize the agent
const agent = await load()

// Collect comprehensive unified device intelligence data
const data = await agent.get({
  taskTimeout: 500,
  overallTimeout: 1000,
  options: { user_ip: false }
})

console.log(data) // Complete unified data structure

2. Legacy Direct API (For Backward Compatibility)

For existing implementations, the legacy API is still supported:

import { getBrowserData } from '@cashfreepayments/deviceintel-js-sdk'

// Direct method call (legacy approach)
const data = await getBrowserData(500, 1000, { user_ip: false })
console.log(data) // Complete unified data structure

Agent-based API Configuration

The modern Agent-based API provides better performance and more configuration options:

Load Options

const agent = await DeviceIntelligence.load({
  delayFallback: 50,  // Fallback delay in milliseconds (default: 50)
  debug: false        // Enable debug mode (default: false)
})

Get Options

const data = await agent.get({
  taskTimeout: 500,      // Individual task timeout (default: 500ms)
  overallTimeout: 1000,   // Overall timeout (default: 1000ms)
  options: {             // Data collection options
    user_ip: false,
    location: false,
    // ... other options
  },
  debug: false           // Enable debug mode for this call
})

Agent Methods

Timeout Configuration

Both the agent-based and legacy APIs support timeout configuration for optimal performance:

Parameters:

1. taskTimeout: Specifies the maximum allowed time (in milliseconds) for individual tasks within the method to complete. Default: 500ms

2. overallTimeout: Specifies the maximum allowed time (in milliseconds) for the entire execution of the method, including all tasks, to complete. Default: 1000ms

Example Usage

// Agent-based API
const agent = await DeviceIntelligence.load()
const data = await agent.get({
  taskTimeout: 500,
  overallTimeout: 1000,
  options: { user_ip: false }
})

// Legacy API
const data = await getBrowserData(500, 1000, { user_ip: false })

Example with Custom Timeout Values

// Agent-based API with custom timeouts
const agent = await DeviceIntelligence.load()
const data = await agent.get({
  taskTimeout: 500,
  overallTimeout: 1000,
  options: { user_ip: false }
})

// Legacy API with custom timeouts
const data = await getBrowserData(500, 1000, { user_ip: false })

Optional Parameters

Both the agent-based and legacy APIs accept an optional configuration object that allows you to control which data points are collected. Each property in this configuration object can be set to false to skip collecting that specific information.

const options = {
  user_ip: false,               // Skip collecting IP address
  location: false,              // Skip collecting geolocation data
  browser_info: false,          // Skip collecting browser information
  screen_info: false,           // Skip collecting screen resolution and color depth
  plugins: false,               // Skip collecting browser plugin information
  timezone: false,              // Skip collecting timezone information
  canvas_device_fingerprint: false, // Skip canvas fingerprinting
  audio_fingerprint: false,     // Skip audio fingerprinting
  webgl_fingerprint: false,     // Skip WebGL fingerprinting
  // ... any other BrowserInfo field can be disabled
}

// Agent-based API
const agent = await DeviceIntelligence.load()
const data = await agent.get({ options })

// Legacy API
const data = await getBrowserData(500, 1000, options)

By default, all data points are collected (equivalent to setting all options to true). Setting any option to false will:

1. Skip the associated data collection tasks
2. Potentially reduce overall execution time
3. Return 'NA' for those specific properties in the result object

Methods Exposed

Note: Visitor ID generation is handled automatically by the SDK during data collection and is available in the visitor_id field of the returned BrowserInfo object. There is no separate generateVisitorID() method in the current API.

Unified Data Structure

All methods now return a unified BrowserInfo type containing comprehensive device intelligence data. This includes all the fields previously split between device and risk data:

Complete Data Fields with Types (80+ fields)

The SDK collects comprehensive data across multiple categories with strict TypeScript typing:

Core Identification

Device & Hardware Information

Operating System

Browser Information

Display & Screen

Location & Language

Network & Connectivity

Browser Features & Capabilities

Privacy & Security

Fingerprinting Components

Advanced Entropy

Device Classification

Performance Metrics

Error Tracking & Diagnostics

TypeScript Support

The SDK provides full TypeScript support with these verified types:

import { 
  BrowserInfo, 
  BrowserDataOptions, 
  LoadOptions, 
  GetOptions, 
  Agent 
} from '@cashfreepayments/deviceintel-js-sdk'

// Example of accessing the actual data structure
const data: BrowserInfo = await agent.get()

// Verified field access patterns
const visitorId: string | 'NA' = data.visitor_id  // "bb890aa2a2963e45b5a2f16fe9b93756"
const browserName: string | 'NA' = data.browser_name  // "GoogleChrome"
const deviceType: string | 'NA' = data.device_type  // "Desktop"
const hardwareConcurrency: number | 'NA' = data.hardware_concurrency  // 10
const webglFingerprint: object | 'NA' = data.webgl_fingerprint  // Complex object
const performanceMetrics = data.performance_metrics  // Always present object
const errorTracking = data.error_tracking  // Always present object

// Privacy settings (returned as JSON string)
const privacySettings: string | 'NA' = data.privacy_settings
if (privacySettings !== 'NA') {
  const parsedSettings = JSON.parse(privacySettings)
  console.log(parsedSettings.doNotTrack)  // true
}

// WebGL fingerprint access
if (data.webgl_fingerprint !== 'NA') {
  const webgl = data.webgl_fingerprint as any
  console.log(webgl.version)  // "WebGL 1.0 (OpenGL ES 2.0 Chromium)"
  console.log(webgl.vendor)   // "WebKit"
}

Error Handling and Diagnostics

const agent = await DeviceIntelligence.load()
const data = await agent.get()

// Check if any errors occurred during data collection
if (data.error_tracking?.has_errors) {
  console.log('Failed collectors:', data.error_tracking.failed_collectors)
  console.log('Error categories:', data.error_tracking.error_categories)
}

// Check visitor ID generation strategy
console.log('Visitor ID strategy:', data.performance_metrics?.visitor_id_strategy)

Selective Data Collection

const agent = await DeviceIntelligence.load()

// Collect only essential data for faster performance
const minimalData = await agent.get({
  taskTimeout: 200,
  overallTimeout: 300,
  options: {
    // Disable resource-intensive collectors
    canvas_device_fingerprint: false,
    audio_fingerprint: false,
    webgl_fingerprint: false,
    installed_fonts: false,
    // Keep essential fields enabled (default: true)
    visitor_id: true,
    device_type: true,
    browser_name: true,
    user_agent: true
  }
})