Angular SDK

npm (Recommended)

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

npm install @keverdjs/fraud-sdk-angular

yarn

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

yarn add @keverdjs/fraud-sdk-angular

Peer Dependencies

The Angular SDK requires Angular 15.0 or higher and RxJS 7.0 or higher. These should already be installed in your Angular project, but if not, install them:

npm install @angular/core@^15.0.0 rxjs@^7.0.0
# or
yarn add @angular/core@^15.0.0 rxjs@^7.0.0

Note: The SDK uses Angular's dependency injection system and RxJS Observables for reactive data access. The SDK is provided as a singleton service using Angular's providedIn: 'root' pattern, making it available throughout your application.

1. Import Module

Import the KeverdModule in your root module (app.module.ts) and configure it using the forRoot() method. This method follows Angular's module configuration pattern and provides the SDK configuration to the dependency injection system.

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.

For Angular Standalone Components: If you're using Angular standalone components (Angular 14+), you can import the KeverdService directly and call init() manually, or use Angular's APP_INITIALIZER to initialize the SDK at application startup.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { KeverdModule } from '@keverdjs/fraud-sdk-angular';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    KeverdModule.forRoot({
      apiKey: environment.keverdApiKey, // Use environment variables
      endpoint: 'https://api.keverd.com', // Optional: defaults to https://api.keverd.com
      debug: !environment.production, // Enable debug in dev only
    }),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

2. Use Service in Components

Inject the KeverdService into your components using Angular's dependency injection. The service provides an RxJS Observable-based API for accessing visitor data and risk assessment. All methods return Observables, allowing you to use RxJS operators for reactive data handling.

Performance: Data collection typically completes in under 50ms. The total time (including network request) is typically under 200ms (p99 latency). The service uses RxJS Observables for efficient reactive data handling.

import { Component, OnInit } from '@angular/core';
import { KeverdService } from '@keverdjs/fraud-sdk-angular';
import type { KeverdVisitorData } from '@keverdjs/fraud-sdk-angular';

@Component({
  selector: 'app-root',
  template: \`
    <div *ngIf="loading">Loading risk assessment...</div>
    <div *ngIf="error">
      <p>Error: {{ error.message }}</p>
      <button (click)="checkRisk()">Retry</button>
    </div>
    <div *ngIf="data && !loading">
      <p>Risk Score: {{ data.riskScore }}/100</p>
      <p>Action: {{ data.action }}</p>
      <p>Reasons: {{ data.reasons.join(', ') }}</p>
      <button (click)="checkRisk()">Reload data</button>
    </div>
  \`
})
export class AppComponent implements OnInit {
  data: KeverdVisitorData | null = null;
  loading = false;
  error: any = null;

  constructor(private keverd: KeverdService) {}

  ngOnInit() {
    this.checkRisk();
  }

  checkRisk() {
    this.loading = true;
    this.error = null;
    
    this.keverd.getVisitorData({
      extendedResult: true
    }).subscribe({
      next: (data) => {
        this.data = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = err;
        this.loading = false;
      }
    });
  }
}

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.

import { catchError, retry, throwError } from 'rxjs';
import { of } from 'rxjs';

this.keverd.getVisitorData()
  .pipe(
    retry({
      count: 3,
      delay: (error, retryCount) => {
        if (error.message.includes('timeout') || error.message.includes('Timeout')) {
          // Retry with exponential backoff
          return timer(retryCount * 1000);
        }
        return throwError(() => error);
      }
    }),
    catchError((error) => {
      if (error.message.includes('network') || error.message.includes('Network')) {
        console.error('Network error:', error.message);
        showNetworkError();
      }
      return throwError(() => error);
    })
  )
  .subscribe({
    next: (data) => this.data = data,
    error: (err) => this.error = err
  });

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.

import { catchError } from 'rxjs/operators';
import { throwError } from 'rxjs';

this.keverd.getVisitorData()
  .pipe(
    catchError((error) => {
      if (error.code === 'HTTP_401' || error.message.includes('Unauthorized')) {
        // Invalid API key
        console.error('Invalid API key. Please check your configuration.');
        showConfigurationError();
      } else if (error.code === 'HTTP_429' || error.message.includes('rate limit')) {
        // Rate limit exceeded
        console.warn('Rate limit exceeded. Please retry after some time.');
        showRateLimitError();
      } else if (error.code?.startsWith('HTTP_5')) {
        // Server errors - retry with backoff
        console.error('Server error:', error.message);
        return this.keverd.getVisitorData().pipe(
          retry({ count: 3, delay: 1000 })
        );
      }
      return throwError(() => error);
    })
  )
  .subscribe({
    next: (data) => this.data = data,
    error: (err) => this.error = err
  });

SDK Not Initialized Errors

These errors occur when you try to use the SDK before it's initialized or when the module hasn't been configured.

this.keverd.getVisitorData()
  .pipe(
    catchError((error) => {
      if (error.code === 'SDK_NOT_INITIALIZED') {
        // SDK not initialized - initialize and retry
        console.warn('SDK not initialized, initializing...');
        this.keverd.init({
          apiKey: environment.keverdApiKey,
          endpoint: 'https://api.keverd.com'
        });
        // Retry after initialization
        return this.keverd.getVisitorData();
      }
      return throwError(() => error);
    })
  )
  .subscribe({
    next: (data) => this.data = data,
    error: (err) => this.error = err
  });

Best Practices for Error Handling

• Use RxJS operators: Use RxJS operators like catchError, retry, and retryWhen to handle errors reactively.
• Implement retry logic: For transient errors (network timeouts, server errors), implement retry logic with exponential backoff using retry or retryWhen operators.
• 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.
• Unsubscribe properly: Always unsubscribe from Observables to prevent memory leaks. Use Angular's takeUntil pattern or the async pipe in templates.

Module Setup

• Use forRoot in root module: Call KeverdModule.forRoot() in your root module (app.module.ts) to configure the SDK once for your entire application.
• 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.

Service Usage

• Inject service in components: Inject the KeverdService into your components using Angular's dependency injection. The service is provided as a singleton, so all components share the same instance.
• Use RxJS operators: Take advantage of RxJS operators to transform, filter, retry, and handle errors in your data streams. Use map, catchError, retry, and other operators as needed.
• Avoid excessive calls: Don't call getVisitorData() on every component lifecycle hook or user interaction. Use it strategically for high-value or high-risk operations.
• Unsubscribe properly: Always unsubscribe from Observables to prevent memory leaks. Use Angular's async pipe in templates, or use the takeUntil pattern with OnDestroy in components.

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.
• RxJS efficiency: Use RxJS operators efficiently. Avoid creating unnecessary subscriptions and use operators like shareReplay to share Observable streams across multiple subscribers.

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.