Vue.js SDK

npm (Recommended)

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

npm install @keverdjs/fraud-sdk-vue

yarn

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

yarn add @keverdjs/fraud-sdk-vue

Peer Dependencies

The Vue SDK requires Vue 3.0 or higher (for Composition API support). Vue should already be installed in your project, but if not, install it:

npm install vue@^3.0.0
# or
yarn add vue@^3.0.0

Note: The SDK uses Vue 3's Composition API (composables, refs, provide/inject) internally, so Vue 3.0+ is required. The SDK is compatible with both Options API and Composition API components, but composables can only be used in Composition API components.

1. Setup Provider or Install Plugin

You can use the SDK in two ways: install it as a Vue plugin (recommended for global access) or use the useKeverdProvider composable in your root component.

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.

Option A - Plugin Installation (Recommended): Install the SDK as a Vue plugin for global access across all components.

import { createApp } from 'vue';
import App from './App.vue';
import KeverdPlugin from '@keverdjs/fraud-sdk-vue';

const app = createApp(App);

app.use(KeverdPlugin, {
  apiKey: process.env.VUE_APP_KEVERD_API_KEY, // Use environment variables
  endpoint: 'https://api.keverd.com', // Optional: defaults to https://api.keverd.com
  debug: process.env.NODE_ENV === 'development', // Enable debug in dev only
});

app.mount('#app');

Option B - Composable Setup: Use the useKeverdProvider composable in your root component.

<script setup>
import { useKeverdProvider } from '@keverdjs/fraud-sdk-vue';

// Setup provider (call once in root component, e.g., App.vue)
useKeverdProvider({
  apiKey: import.meta.env.VITE_KEVERD_API_KEY,
  endpoint: 'https://api.keverd.com',
  debug: import.meta.env.DEV
});
</script>

2. Use Composable in Components

The useKeverdVisitorData composable provides a Vue-friendly interface for accessing visitor data and risk assessment. The composable manages loading states, error handling, and data fetching automatically using Vue's reactivity system.

Performance: Data collection typically completes in under 50ms. The total time (including network request) is typically under 200ms (p99 latency). The composable uses Vue's reactivity system to prevent unnecessary re-renders.

<script setup>
import { useKeverdVisitorData } from '@keverdjs/fraud-sdk-vue';

// Use composable in any component
const { data, loading, error, getData } = useKeverdVisitorData({
  extendedResult: true, // Include extended result data
  immediate: true, // Automatically fetch data on mount
});

// Handle risk score reactively
const riskLevel = computed(() => {
  if (!data.value) return 'unknown';
  if (data.value.riskScore >= 70) return 'high';
  if (data.value.riskScore >= 30) return 'medium';
  return 'low';
});
</script>

<template>
  <div>
    <!-- Loading state -->
    <div v-if="loading">Loading risk assessment...</div>
    
    <!-- Error state -->
    <div v-else-if="error">
      <p>Error: {{ error.message }}</p>
      <button @click="getData">Retry</button>
    </div>
    
    <!-- Success state -->
    <div v-else-if="data">
      <p>Risk Score: {{ data.riskScore }}/100</p>
      <p>Action: {{ data.action }}</p>
      <p>Reasons: {{ data.reasons.join(', ') }}</p>
      <p>Risk Level: {{ riskLevel }}</p>
      <button @click="getData">Reload data</button>
    </div>
    
    <!-- No data state -->
    <div v-else>
      <button @click="getData">Check Risk</button>
    </div>
  </div>
</template>

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.

<script setup>
import { watch } from 'vue';
import { useKeverdVisitorData } from '@keverdjs/fraud-sdk-vue';

const { data, loading, error, getData } = useKeverdVisitorData({
  immediate: true,
});

watch(error, (err) => {
  if (err) {
    if (err.message.includes('timeout') || err.message.includes('Timeout')) {
      // Handle timeout - retry with exponential backoff
      console.warn('Request timed out, retrying...');
      setTimeout(() => getData(), 1000);
    } else if (err.message.includes('network') || err.message.includes('Network')) {
      // Handle network connectivity issues
      console.error('Network error:', err.message);
      showNetworkError();
    }
  }
});
</script>

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.

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

SDK Not Ready Errors

These errors occur when you try to use the SDK before it's initialized or when the provider hasn't mounted yet.

watch(error, (err) => {
  if (err && err.code === 'SDK_NOT_READY') {
    // SDK not initialized - wait a bit and retry
    console.warn('SDK not ready, retrying...');
    setTimeout(() => getData(), 100);
  }
});

Best Practices for Error Handling

• Use watch to monitor errors: Set up a watch to monitor the error ref and handle errors appropriately.
• 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.

Provider Setup

• Call provider once: Call useKeverdProvider once in your root component (e.g., App.vue) or install the plugin globally in your app setup.
• 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.

Composable Usage

• Use immediate option wisely: Set immediate: true only when you need data immediately on component mount. For on-demand fetching, use immediate: false and call getData() manually.
• Avoid excessive calls: Don't call getData() on every render or user interaction. Use it strategically for high-value or high-risk operations.
• Handle loading and error states: Always handle the loading and error refs in your components to provide good user experience.
• Use computed properties: Use Vue's computed to derive values from the data ref for better performance and reactivity.

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.