CartAI Device SDK

Advanced browser identification library with the highest accuracy and stability for fraud detection and device analysis.

Installation

npm install @cartai2025/device-sdk

Or using yarn:

yarn add @cartai2025/device-sdk

Quick Start

Basic Usage

import CartAI from '@cartai2025/device-sdk'

// Initialize the agent
const cartaiAgent = await CartAI.load()

// Get visitor identifier
const result = await cartaiAgent.get()

console.log('Visitor ID:', result.visitorId)
console.log('Confidence:', result.confidence)

ES Modules

import { load } from '@cartai2025/device-sdk'

async function getDeviceFingerprint() {
  const agent = await load()
  const result = await agent.get()

  return {
    visitorId: result.visitorId,
    confidence: result.confidence.score,
    components: result.components
  }
}

getDeviceFingerprint().then(data => {
  console.log('Device fingerprint:', data)
})

CDN Usage (Browser)

<!DOCTYPE html>
<html>
<head>
    <script src="https://d24lz8mxe7yhfu.cloudfront.net/cartai-device-sdk/cartai-device-sdk.min.js"></script>
</head>
<body>
    <script>
        CartAI.load().then(agent => {
            return agent.get()
        }).then(result => {
            console.log('Visitor ID:', result.visitorId)
            console.log('Confidence:', result.confidence.score)
        })
    </script>
</body>
</html>

API Reference

`load(options?)`

Loads and initializes the CartAI agent.

Parameters:

options (optional): Configuration options
- delayFallback (number, default: 50): Fallback delay for older browsers in milliseconds
- debug (boolean, default: false): Enable debug logging

Returns: Promise<Agent>

const agent = await CartAI.load({
  delayFallback: 100,
  debug: true
})

`agent.get(options?)`

Gets the visitor identifier and device fingerprint.

Parameters:

options (optional): Get options
- debug (boolean): Enable debug logging (deprecated - use load options instead)

Returns: Promise<GetResult>

const result = await agent.get()

GetResult Object

The result object contains:

visitorId (string): Unique visitor identifier
confidence (Confidence): Confidence score and details
components (object): Raw fingerprinting components used for identification
version (string): SDK version used for identification

{
  visitorId: "abc123def456...",
  confidence: {
    score: 0.99,
    comment: "High confidence"
  },
  components: {
    // Various device and browser characteristics
  },
  version: "1.0.0"
}

Advanced Usage

Custom Configuration

import { load } from '@cartai2025/device-sdk'

const agent = await load({
  delayFallback: 200,  // Custom delay for older browsers
  debug: true          // Enable detailed logging
})

const result = await agent.get()

Working with Components

import { load, hashComponents, componentsToDebugString } from '@cartai2025/device-sdk'

const agent = await load()
const result = await agent.get()

// Get debug information about components
const debugInfo = componentsToDebugString(result.components)
console.log('Components debug info:', debugInfo)

// Generate custom hash from components
const customHash = hashComponents(result.components)
console.log('Custom hash:', customHash)

Error Handling

import CartAI from '@cartai2025/device-sdk'

try {
  const agent = await CartAI.load({
    debug: true
  })

  const result = await agent.get()

  if (result.confidence.score > 0.8) {
    console.log('High confidence ID:', result.visitorId)
  } else {
    console.log('Lower confidence ID:', result.visitorId)
    console.log('Confidence details:', result.confidence.comment)
  }
} catch (error) {
  console.error('CartAI initialization failed:', error)
}

Browser Compatibility

CartAI Device SDK supports all modern browsers:

Chrome 49+
Firefox 52+
Safari 10+
Edge 79+
Opera 36+

Privacy & Security

No personal information is collected
All processing happens locally in the browser
Compliant with privacy regulations (GDPR, CCPA)
Respects Do Not Track headers

Performance

Lightweight (~50KB minified)
Lazy loading of detection modules
Optimized for minimal impact on page load
Uses requestIdleCallback when available

Use Cases

Fraud Prevention: Identify suspicious devices and behavior
Analytics: Track unique visitors without cookies
Security: Detect bot traffic and automated attacks
Personalization: Provide consistent experience across sessions
A/B Testing: Ensure users stay in the same test group

TypeScript Support

Full TypeScript definitions are included:

import { Agent, GetResult, LoadOptions } from '@cartai2025/device-sdk'

const options: LoadOptions = {
  delayFallback: 100,
  debug: false
}

const agent: Agent = await CartAI.load(options)
const result: GetResult = await agent.get()

License

This project is licensed under the Business Source License 1.1 (BUSL-1.1).

Support

For support and questions:

GitHub Issues: https://github.com/shimiljas/cartai/issues
Documentation: https://github.com/shimiljas/cartai/tree/main/cartai-device-sdk

Changelog

See CHANGELOG.md for version history and updates.

Package detail

@cartai2025/device-sdk

readme