@cartai2025/device-sdk

v1.0.3

Published

a month ago

Advanced browser identification library with the highest accuracy and stability

0High
0Medium
0Low

fraud fraud detection fraud prevention browser identification device identification browser analysis device analysis privacy

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

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

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.