Vanilla JavaScript SDK

npm (Recommended)

Install the SDK using npm, the Node.js package manager. This is the recommended installation method for most projects.

npm install @keverdjs/fraud-sdk

yarn

Alternatively, install using Yarn if you prefer it over npm.

yarn add @keverdjs/fraud-sdk

CDN (Alternative)

For projects that don't use a package manager, you can include the SDK via a CDN. Add this script tag to your HTML:

<script src="https://cdn.keverd.com/sdk/v1/keverd-sdk.min.js"></script>

Note: When using the CDN, the SDK is available globally as window.Keverd. The CDN version is automatically minified and optimized for production use.

1. Import and Initialize

Import the SDK and initialize it with your API key. The SDK follows a singleton pattern, so you only need to initialize it once in your application. Initialization is synchronous and non-blocking, but you should call it early in your application lifecycle (e.g., in your main entry point or app initialization code).

Important: The endpoint must use HTTPS. The SDK will throw an error if you provide an HTTP URL. The default API endpoint is https://api.keverd.com.

import { Keverd } from '@keverdjs/fraud-sdk';

// Simple initialization with API key only
Keverd.init('your-api-key-here');

// Or with full configuration object
Keverd.init({
  apiKey: 'your-api-key-here',
  endpoint: 'https://api.keverd.com', // Optional: defaults to https://api.keverd.com
  userId: 'user-123', // Optional: user identifier
  debug: true, // Optional: enable debug logging (default: false)
});

2. Get Visitor Data

Call getVisitorData() to collect device information, behavioral data, and receive a risk assessment from the Keverd API. This method is asynchronous and returns a Promise that resolves to a FingerprintResponse object.

Performance: Data collection typically completes in under 50ms. The total time (including network request) is typically under 200ms (p99 latency). The method uses the browser's native fetch API with a default timeout of 30 seconds.

// Get visitor data and risk assessment
try {
  const result = await Keverd.getVisitorData();
  
  console.log('Risk Score:', result.risk_score); // 0-100
  console.log('Normalized Score:', result.score); // 0.0-1.0
  console.log('Action:', result.action); // 'allow' | 'soft_challenge' | 'hard_challenge' | 'block'
  console.log('Session ID:', result.session_id); // UUID
  console.log('Request ID:', result.requestId); // UUID (same as session_id)
  console.log('Reasons:', result.reason); // Array of risk reasons
  
  // Handle risk score
  if (result.risk_score >= 70) {
    // High risk - block or require additional verification
    handleHighRisk(result);
  } else if (result.risk_score >= 30) {
    // Medium risk - require MFA
    requireMFA(result);
  } else {
    // Low risk - proceed normally
    proceedNormally(result);
  }
} catch (error) {
  // Handle errors (see Error Handling section)
  console.error('Error getting visitor data:', error);
}

Network Errors

Network errors occur when the device cannot connect to the API or when the request times out. The SDK uses 30-second timeouts for connection, read, and write operations.

try {
  const result = await Keverd.getVisitorData();
} catch (error) {
  if (error.message.includes('timeout') || error.message.includes('Timeout')) {
    // Handle timeout - retry with exponential backoff
    console.warn('Request timed out, retrying...');
    setTimeout(() => checkRisk(), 1000); // Retry after 1 second
  } else if (error.message.includes('network') || error.message.includes('Network')) {
    // Handle network connectivity issues
    console.error('Network error:', error.message);
    showNetworkError();
  } else {
    // Handle other network errors
    console.error('Network error:', error);
  }
}

API Errors

API errors occur when the server returns an error status code (4xx or 5xx). Common causes include invalid API keys, rate limiting, or server errors.

try {
  const result = await Keverd.getVisitorData();
} catch (error) {
  if (error.message.includes('401') || error.message.includes('Unauthorized')) {
    // Invalid API key
    console.error('Invalid API key. Please check your configuration.');
    showConfigurationError();
  } else if (error.message.includes('429') || error.message.includes('rate limit')) {
    // Rate limit exceeded
    console.warn('Rate limit exceeded. Please retry after some time.');
    showRateLimitError();
  } else if (error.message.includes('500') || error.message.includes('502') || error.message.includes('503')) {
    // Server errors - retry with backoff
    console.error('Server error:', error.message);
    retryWithBackoff();
  } else {
    // Other API errors
    console.error('API error:', error.message);
    handleApiError(error);
  }
}

Initialization Errors

Initialization errors occur when you try to use the SDK before calling init() or when the SDK is not properly initialized.

try {
  const result = await Keverd.getVisitorData();
} catch (error) {
  if (error.message.includes('not initialized') || error.message.includes('init')) {
    // SDK not initialized
    console.error('SDK not initialized. Call Keverd.init() first.');
    Keverd.init({
      apiKey: 'your-api-key-here',
      endpoint: 'https://api.keverd.com'
    });
    // Retry after initialization
    setTimeout(() => checkRisk(), 100);
  } else {
    // Other errors
    console.error('Error:', error);
  }
}

Best Practices for Error Handling

• Always use try-catch: Wrap all calls to getVisitorData() in try-catch blocks to handle errors gracefully.
• Implement retry logic: For transient errors (network timeouts, server errors), implement retry logic with exponential backoff.
• Fail gracefully: Decide on a fail-open or fail-closed strategy. Fail-open allows access when the SDK fails, while fail-closed blocks access. Choose based on your security requirements.
• Log errors: Log errors to your error tracking service (e.g., Sentry, LogRocket) for debugging and monitoring.
• User feedback: Provide clear feedback to users when errors occur, especially for authentication or security-related failures.

Initialization

• Initialize early: Call init() as early as possible in your application lifecycle, ideally in your main entry point or app initialization code.
• Initialize once: The SDK uses a singleton pattern, so you only need to initialize it once. Subsequent calls to init() will be ignored.
• Use environment variables: Store your API key in environment variables and never commit it to version control. Use different API keys for development, staging, and production environments.
• Enable debug in development only: Set debug: true only in development environments. Disable it in production to avoid exposing sensitive information in the console.

API Calls

• Call at appropriate times: Call getVisitorData() at key points in your user flow, such as login, registration, checkout, or sensitive operations.
• Avoid excessive calls: Don't call getVisitorData() on every page load or user interaction. Use it strategically for high-value or high-risk operations.
• Handle asynchronously: Always use await or .then() when calling getVisitorData(), as it returns a Promise.
• Implement retry logic: For transient errors, implement retry logic with exponential backoff to improve reliability.

Use-Case-Specific Methods

• Use appropriate methods: Use verifyLogin() for login flows, verifyCheckout() for payment flows, etc. This provides better context for risk scoring.
• Login verification: Call verifyLogin() before authenticating the user. Block or challenge high-risk attempts (risk_score ≥ 70).
• Checkout verification: Call verifyCheckout() before processing payment. Require additional verification for medium-risk checkouts (risk_score 30-69).
• Registration verification: Use verifyRegistration() to detect bot signups. Block high-risk registrations automatically.
• Password reset: Always use verifyPasswordReset() for password reset flows. This is a high-risk operation that requires extra scrutiny.

Risk Score Interpretation

• 0-29 (Low Risk): Allow the operation. User behavior matches their profile and shows no suspicious patterns.
• 30-69 (Medium Risk): Require additional verification (MFA, CAPTCHA, email confirmation). User behavior is unusual but not clearly fraudulent.
• 70-100 (High Risk): Block the operation or require manual review. Strong indicators of fraud or account takeover.
• Context matters: A risk score of 50 for login is more concerning than 50 for registration. Adjust thresholds based on use case.
• Combine with other signals: Use risk scores alongside other security measures (rate limiting, IP reputation, etc.) for defense in depth.
• Monitor trends: Track risk score trends over time. Sudden increases may indicate a new attack vector.

Security

• Protect your API key: Never expose your API key in client-side code that can be viewed in the browser. Use environment variables or a secure configuration management system.
• Use HTTPS: Always use HTTPS endpoints. The SDK will not work with HTTP endpoints for security reasons.
• Validate risk scores: Don't blindly trust risk scores. Use them as one factor in your security decision-making process, along with other signals.
• Monitor for anomalies: Set up monitoring and alerting for unusual patterns in risk scores or error rates.

Performance

• Non-blocking: The SDK is designed to be non-blocking. Data collection and API calls happen asynchronously and won't block your UI.
• Minimal impact: Behavioral data collection is passive and has minimal impact on page performance. The SDK uses efficient event listeners that are automatically cleaned up.
• Bundle size: The SDK is lightweight and has a small bundle size. It won't significantly impact your application's load time.

Privacy and Compliance

• GDPR compliance: The SDK is designed to be GDPR-compliant. All sensitive data is hashed client-side, and no PII is collected or transmitted.
• User consent: Consider obtaining user consent before initializing the SDK, especially in regions with strict privacy regulations.
• Privacy policy: Update your privacy policy to inform users about data collection and how it's used for fraud detection.
• Data retention: The SDK stores minimal data in localStorage. Consider clearing this data when users log out or request data deletion.