Dashboard Events

The SDK provides a fire-and-forget event tracking system for sending telemetry to the Incode dashboard. This allows you to track module lifecycle, screen transitions, and custom events throughout your verification flow.

Overview

Events are sent automatically by the SDK's built-in modules, but you can also track custom events from your own code. All events are:

• Fire-and-forget: Never blocks execution, never throws errors
• Headless-compatible: Available in @incodetech/core with zero UI dependencies
• Auto-queued: Events sent before SDK is configured are queued and sent automatically when setup() is called

Quick Start

import { 
  addEvent, 
  moduleOpened, 
  moduleClosed,
  eventModuleNames 
} from '@incodetech/core/events';

// Track module lifecycle
useEffect(() => {
  moduleOpened(eventModuleNames.phone);
  return () => moduleClosed(eventModuleNames.phone);
}, []);

// Track custom events
addEvent({
  code: 'customButtonClicked',
  module: eventModuleNames.phone,
  payload: { buttonId: 'submit' },
});

Event Logging

Subscribe to all events for custom logging or analytics:

import { subscribeEvent } from '@incodetech/core/events';

// Custom logger - separate from API event sending
const unsubscribeLogger = subscribeEvent((event) => {
  console.log('[Event]', {
    code: event.code,
    module: event.module,
    screen: event.screen,
    payload: event.payload,
    timestamp: new Date(event.clientTimestamp ?? Date.now()).toISOString(),
  });
});

// Events are logged AND sent to API independently
addEvent({ code: 'test', module: 'PHONE' });
// → Logged to console via listener
// → Sent to API (automatic)

// Remove logger when done
unsubscribeLogger();

API Reference

Core Functions

addEvent(event)

Sends a single event to the dashboard. Fire-and-forget - never blocks or throws.

addEvent({
  code: 'captureAttemptFinished',
  module: eventModuleNames.id,
  screen: eventScreenNames.frontCameraCapture,
  payload: { logs: [], attemptNumber: 1 },
  clientTimestamp: Date.now(), // Optional, defaults to now
});

Parameters:

subscribeEvent(listener)

Subscribes to all SDK events for logging, debugging, or custom analytics. Returns an unsubscribe function.

const unsubscribe = subscribeEvent((event) => {
  console.log('[Event]', event.code, event.module);
  // Your custom logic here
});

// Later
unsubscribe();

Parameters:

Returns: Unsubscribe function to remove the listener

Note: Subscribers receive events before they're queued or sent to the API. Listener errors are silently caught and don't affect event sending.

Helper Functions

// Module lifecycle
moduleOpened(module, screen?, payload?);
moduleClosed(module, screen?, payload?);

// Screen lifecycle
screenOpened(module, screen, payload?);
screenClosed(module, screen, payload?);

// Generic screen event
screenEvent({ module, screen, code, payload });

Available Constants

Module Names

import { eventModuleNames } from '@incodetech/core/events';

Screen Names

import { eventScreenNames } from '@incodetech/core/events';

Grouped by module for readability.

Selfie / Face Capture

Auth Face

Consent

CURP

QR

OTP / Signature

ID — Front

ID — Back

Passport

Document Capture

Digital ID

Conference

Video Selfie

eKYC / eKYB / Forms

Watchlists

Phone / Email / Instant Verify

Custom Module

Video Selfie Events

import { videoSelfieEvents } from '@incodetech/core/events';

Event Queue

Events sent before the SDK is configured (before setup() is called with a token) are automatically queued. When setup() is called with a token, all queued events are automatically flushed and sent.

// This event will be queued
addEvent({ code: 'sdkLoading', payload: { timestamp: Date.now() } });

// Later, after setup with token
await setup({ apiURL: '...', token: 'session-token' });
// ^ Queued events are automatically sent here

Common Event Codes

The SDK automatically sends these events from built-in modules:

Examples

Track Custom Button Click

import { addEvent, eventModuleNames } from '@incodetech/core/events';

function handleSubmit() {
  addEvent({
    code: 'customSubmitClicked',
    module: eventModuleNames.phone,
    payload: { timestamp: Date.now() },
  });
  
  // Your submit logic...
}

Track Screen Transition

import { screenEvent, eventModuleNames, eventScreenNames } from '@incodetech/core/events';

function navigateToTutorial() {
  screenEvent({
    module: eventModuleNames.id,
    screen: eventScreenNames.frontTutorial,
    code: 'screenOpened',
  });
  
  // Navigate...
}

Track Module Lifecycle in Headless Mode

import { moduleOpened, moduleClosed, eventModuleNames } from '@incodetech/core/events';

function MyCustomPhoneFlow() {
  useEffect(() => {
    moduleOpened(eventModuleNames.phone);
    
    return () => {
      moduleClosed(eventModuleNames.phone);
    };
  }, []);
  
  // Your custom implementation...
}

Best Practices

1. Use constants - Always use eventModuleNames and eventScreenNames instead of hardcoded strings
2. Fire-and-forget - Don't await addEvent() - it's designed to never block
3. Use hooks for lifecycle - Use useModuleEvents/useScreenEvents for automatic tracking
4. Include context - Add relevant data in payload for debugging
5. Don't track sensitive data - Never include PII or sensitive information in event payloads
6. Use subscribers for custom logging - Use subscribeEvent() for custom analytics or logging needs
7. Keep listeners lightweight - Event listeners are called synchronously; avoid heavy operations

See Also

• Headless Mode: Using events in headless mode
• Event Callbacks: SDK callbacks vs dashboard events
• API Reference: Full API documentation