Events

The VECU IDV Web SDK emits rich lifecycle events for real-time observability. Subscribe to events to track verification progress, handle errors, and integrate with your analytics.

Subscribing to Events

import { createVecuIDVSDK, SdkEvent } from 'vec-idp-web-sdk';

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  bearerToken: 'your-bearer-token',
});

// Subscribe to events
sdk.on(SdkEvent.VERIFICATION_COMPLETED, event => {
  console.log('Verification completed:', event.data);
});

// Subscribe once (auto-unsubscribes after first trigger)
sdk.once(SdkEvent.VERIFICATION_STARTED, event => {
  console.log('Verification started');
});

// Unsubscribe
const handler = event => console.log(event);
sdk.on(SdkEvent.VERIFICATION_PROGRESS, handler);
sdk.off(SdkEvent.VERIFICATION_PROGRESS, handler);

SDK Events

Events related to SDK initialization and lifecycle.

SdkEvent.SDK_INIT

Emitted when SDK initialization starts.

sdk.on(SdkEvent.SDK_INIT, () => {
  console.log('SDK initialization started');
});

SdkEvent.SDK_READY

Emitted when SDK initialization completes successfully.

sdk.on(SdkEvent.SDK_READY, () => {
  console.log('SDK is ready');
});

SdkEvent.SDK_ERROR

Emitted when SDK initialization or runtime error occurs.

sdk.on(SdkEvent.SDK_ERROR, event => {
  console.error('SDK error:', {
    code: event.data.code, // 'SDK_INIT_FAILED'
    message: event.data.message,
    details: event.data.details, // Inner error object
  });
});

Verification Events

Events related to the verification process.

SdkEvent.VERIFICATION_STARTED

Emitted when a verification session starts.

sdk.on(SdkEvent.VERIFICATION_STARTED, event => {
  console.log('Verification started:', {
    token: event.data.token,
    ui: event.data.ui,
  });
});

SdkEvent.VERIFICATION_PROGRESS

Emitted during verification with progress updates. The number and granularity of progress events may vary — do not rely on specific step names or a fixed number of progress events.

sdk.on(SdkEvent.VERIFICATION_PROGRESS, event => {
  console.log('Progress:', {
    sessionId: event.data.sessionId,
    step: event.data.step,
    percentage: event.data.percentage, // 0-100
    message: event.data.message,
  });
});

SdkEvent.VERIFICATION_COMPLETED

Emitted when verification completes successfully.

sdk.on(SdkEvent.VERIFICATION_COMPLETED, event => {
  console.log('Verification completed:', {
    sessionId: event.data.sessionId,
    result: event.data.result,
    addressConfirmed: event.data.addressConfirmed,
  });
});

SdkEvent.VERIFICATION_FAILED

Emitted when a verification session fails. Failures may include timeout errors if the verification session exceeds its maximum duration.

sdk.on(SdkEvent.VERIFICATION_FAILED, event => {
  console.error('Verification failed:', event.data.error);
});

Reverification Events

Events specific to the reverification flow.

SdkEvent.REVERIFICATION_STARTED

Emitted when a reverification flow starts.

sdk.on(SdkEvent.REVERIFICATION_STARTED, event => {
  console.log('Reverification started:', {
    provider: event.data.provider,
    token: event.data.token,
  });
});

SdkEvent.REVERIFICATION_PROGRESS

Emitted with high-level progress updates during reverification.

sdk.on(SdkEvent.REVERIFICATION_PROGRESS, event => {
  console.log('Reverification progress:', event.data);
});

SdkEvent.REVERIFICATION_COMPLETED

Emitted when reverification completes successfully.

sdk.on(SdkEvent.REVERIFICATION_COMPLETED, event => {
  console.log('Reverification completed:', event.data.result);
});

SdkEvent.REVERIFICATION_FAILED

Emitted when reverification fails.

sdk.on(SdkEvent.REVERIFICATION_FAILED, event => {
  console.error('Reverification failed:', event.data.error);
});

SdkEvent.REVERIFICATION_ERROR

Emitted for non-fatal errors during reverification.

sdk.on(SdkEvent.REVERIFICATION_ERROR, event => {
  console.warn('Reverification error:', event.data);
});

Provider Events

Events from the underlying identity verification provider.

SdkEvent.PROVIDER_LOADED

Emitted when provider SDK loads successfully.

sdk.on(SdkEvent.PROVIDER_LOADED, event => {
  console.log('Provider loaded:', {
    provider: event.data.provider,
    digitalIntelligenceEnabled: event.data.digitalIntelligenceEnabled,
  });
});

SdkEvent.PROVIDER_ERROR

Emitted when a provider error occurs.

sdk.on(SdkEvent.PROVIDER_ERROR, event => {
  console.error('Provider error:', event.data);
});

SdkEvent.PROVIDER_EVENT

Generic event forwarding from the provider.

sdk.on(SdkEvent.PROVIDER_EVENT, event => {
  console.log('Provider event:', event.data);
});

Address Events

Events related to address confirmation.

SdkEvent.ADDRESS_VERIFICATION_NEEDED

Emitted when address confirmation is required.

sdk.on(SdkEvent.ADDRESS_VERIFICATION_NEEDED, event => {
  console.log('Address verification needed:', {
    sessionId: event.data.sessionId,
    verificationId: event.data.verificationId,
    addressData: event.data.addressData,
    provider: event.data.provider,
    patchOptions: event.data.patchOptions,
    verificationResponse: event.data.verificationResponse,
    onConfirm: event.data.onConfirm, // Confirmation callback
    onDispute: event.data.onDispute, // Dispute callback
  });
});

SdkEvent.ADDRESS_FIELD_TAMPERING_DETECTED

sdk.on(SdkEvent.ADDRESS_FIELD_TAMPERING_DETECTED, event => {
  console.warn('Tampering detected:', {
    field: event.data.field,
    expectedValue: event.data.expectedValue,
    receivedValue: event.data.receivedValue,
  });
});

SdkEvent.ADDRESS_FIELD_TAMPERING_BLOCKED

sdk.on(SdkEvent.ADDRESS_FIELD_TAMPERING_BLOCKED, event => {
  console.error('Submission blocked due to tampering:', event.data);
});

UI Events

Events related to the verification UI.

SdkEvent.UI_CREATED

Emitted when the UI container is created.

sdk.on(SdkEvent.UI_CREATED, event => {
  console.log('UI created:', event.data.sessionId);
});

SdkEvent.UI_READY

Emitted when the UI is ready for interaction.

sdk.on(SdkEvent.UI_READY, event => {
  console.log('UI ready:', event.data.sessionId);
});

SdkEvent.UI_CLOSED

Emitted when the UI is closed by the user.

sdk.on(SdkEvent.UI_CLOSED, event => {
  console.log('UI closed:', event.data.sessionId);
});

Authentication Events

Events related to authentication and token handling.

SdkEvent.AUTHENTICATION_TOKEN_FAILURE

sdk.on(SdkEvent.AUTHENTICATION_TOKEN_FAILURE, event => {
  console.error('Token exchange failed:', event.data);
  // Handle token refresh or redirect to login
});

Digital Intelligence Events

Events from the Digital Intelligence (device risk) SDK.

SdkEvent.DEVICE_RISK_INITIALIZED

Emitted when Digital Intelligence SDK initializes.

sdk.on(SdkEvent.DEVICE_RISK_INITIALIZED, event => {
  console.log('Device risk initialized:', {
    provider: event.data.provider,
    enabled: event.data.enabled,
  });
});

SdkEvent.DEVICE_ERROR

Emitted when Digital Intelligence SDK fails to load.

sdk.on(SdkEvent.DEVICE_ERROR, event => {
  console.error('Device risk error:', {
    provider: event.data.provider,
    error: event.data.error,
  });
});

Event Reference Table

Next Steps

• API Reference - Complete method reference
• Configuration - SDK configuration options
• Webhooks - Server-side event handling