Event System - frankieone

Overview

The OneSDK uses an event-driven architecture that allows you to listen for and respond to various events throughout the verification lifecycle. Every module and the SDK itself emit events that you can subscribe to.

Event Methods

All modules and the SDK context provide these event methods:

`on(eventName, callback)`

Registers an event listener for the specified event. Signature:

on<EventName>(
  eventName: EventName | EventName[],
  callback: (...args: EventArguments) => void
): void

Parameters:

eventName: String or array of strings representing event name(s)
callback: Function to call when the event is emitted

Example:

// Single event
oneSDKInstance.on('error', (error) => {
  console.error('SDK error:', error);
});

// Multiple events
oneSDKInstance.on(['loading', 'info'], (data) => {
  console.log('Event received:', data);
});

`off(eventName, callback)`

Removes a previously registered event listener. Signature:

off<EventName>(
  eventName: EventName | EventName[],
  callback: (...args: EventArguments) => void
): void

Parameters:

eventName: String or array of strings representing event name(s)
callback: The exact function reference that was registered with on()

Example:

const errorHandler = (error) => {
  console.error('Error:', error);
};

// Register
oneSDKInstance.on('error', errorHandler);

// Later, remove
oneSDKInstance.off('error', errorHandler);

Do not call off() without parameters on global event handlers. This removes ALL listeners and may break internal SDK functionality.

`emit(eventName, ...args)`

Emits an event with optional arguments. Available only on the SDK context (not on module instances). Signature:

emit<EventName>(
  eventName: EventName,
  ...args: EventArguments
): void

Example:

// Emit custom telemetry event
oneSDKInstance.emit('telemetry', {
  eventName: 'CUSTOM_EVENT',
  data: { action: 'button_clicked' }
});

Global Events

These events are emitted by the SDK context and are available on all SDK instances.

Common Events

Available on all modules and the SDK context:

Event	Arguments	Description
`error`	`(error: OneSDKError)`	Emitted when an error occurs
`warning`	`(warning: { message: string, payload?: unknown })`	Emitted for non-critical warnings
`info`	`(info: { message?: string, payload?: unknown, name?: unknown })`	Emitted for informational messages
`loading`	`(isLoading: boolean, context: { message: string })`	Emitted when loading state changes
`*`	`(event: { eventName: string, arguments: unknown[] })`	Wildcard - captures all events

SDK-Specific Events

Event	Arguments	Description
`resolved_root_config`	`(config: GlobalState)`	Emitted when root configuration is resolved
`resolved_module_config`	`(state: InjectedState, config: unknown)`	Emitted when a module configuration is resolved
`telemetry`	`(event: TelemetryEvent)`	Emitted for internal diagnostic data (used by FrankieOne for troubleshooting)
`network_offline`	`()`	Emitted when network connection is lost
`network_online`	`()`	Emitted when network connection is restored

Event Examples

Handling Errors

oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    code: error.code,
    details: error.details
  });

  // Show user-friendly message
  showErrorToUser('Verification error. Please try again.');
});

Monitoring Loading States

oneSDKInstance.on('loading', (isLoading, context) => {
  if (isLoading) {
    showSpinner(context.message);
  } else {
    hideSpinner();
  }
});

Telemetry Events

Telemetry events are used internally by FrankieOne for troubleshooting and diagnostic purposes. You generally don’t need to listen to these events in your application.

// For debugging purposes only
oneSDKInstance.on('telemetry', (event) => {
  if (typeof event === 'string') {
    console.log('Telemetry event:', event);
  } else {
    console.log('Telemetry event:', event.eventName, event.data);
  }
});

Network Status Monitoring

let isOnline = true;

oneSDKInstance.on('network_offline', () => {
  isOnline = false;
  showBanner('You are offline. Verification will resume when connection is restored.');
});

oneSDKInstance.on('network_online', () => {
  if (!isOnline) {
    isOnline = true;
    showBanner('Connection restored. Resuming verification...');
  }
});

Configuration Events

oneSDKInstance.on('resolved_root_config', (config) => {
  console.log('SDK configured with:', {
    mode: config.mode,
    recipe: config.recipe,
    session: config.session
  });
});

Wildcard Event Listener

Capture all events for debugging:

oneSDKInstance.on('*', (event) => {
  console.log('Event emitted:', event.eventName, event.arguments);
});

Module Events

Each module has its own set of events. Subscribe to module events through the module instance:

Individual Module Events

const individual = oneSDKInstance.individual();

individual.on('data_loaded', () => {
  console.log('Individual data loaded');
});

individual.on('results', (results) => {
  console.log('Verification results:', results);
});

individual.on('detection_complete', (data) => {
  console.log('Detection complete:', data);
});

Component Events

Dynamic components also emit events:

const documentComponent = oneSDKInstance.component('document', {
  countries: ['AUS', 'NZL']
});

documentComponent.on('results', (results) => {
  console.log('Document capture results:', results);
});

documentComponent.on('ready', () => {
  console.log('Document component ready');
  documentComponent.mount('#document-container');
});

Event Patterns

Async Event Handling

individual.on('results', async (results) => {
  try {
    // Send results to backend
    await sendToBackend(results);

    // Continue to next step
    startNextVerificationStep();
  } catch (error) {
    console.error('Failed to process results:', error);
  }
});

Event Cleanup

Always clean up event listeners when components unmount:

// React example
useEffect(() => {
  const handleError = (error) => {
    console.error(error);
  };

  oneSDKInstance.on('error', handleError);

  // Cleanup on unmount
  return () => {
    oneSDKInstance.off('error', handleError);
  };
}, []);

Event Chaining

Chain events to create verification flows:

const individual = oneSDKInstance.individual();

// Step 1: Wait for data to load
individual.on('data_loaded', () => {
  console.log('Step 1: Data loaded');

  // Step 2: Submit data
  individual.submit();
});

// Step 3: Handle results
individual.on('results', (results) => {
  console.log('Step 2: Results received');

  if (results.status.type === 'passed') {
    navigateToSuccess();
  } else {
    showErrorScreen(results);
  }
});

Error Event Details

The error event provides a structured error object:

class OneSDKError<Payload = unknown> extends Error {
  readonly message: string;
  readonly name: string;
  readonly payload: Payload;
}

Properties:

message - Human-readable error description
name - Error type identifier (optional)
payload - Additional error context (type varies by error)

Error Handling Example

oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    name: error.name,
    payload: error.payload
  });

  // Handle errors based on name and message patterns
  if (error.name === 'NetworkError') {
    showRetryButton();
  } else if (error.message.includes('token')) {
    redirectToLogin();
  } else {
    showGenericError(error.message);
  }
});

Telemetry Event Structure

Telemetry events can be either a simple string or an object:

type TelemetryEvent =
  | string
  | {
      eventName: string;
      data?: Record<string, unknown>;
      error?: Error;
    };

Telemetry Event Details

Telemetry events are used internally by FrankieOne for diagnostic and troubleshooting purposes. These events are not intended for use in your application logic or analytics.

// For debugging purposes only - not recommended for production use
oneSDKInstance.on('telemetry', (event) => {
  console.log('Internal diagnostic event:', event);
});

Best Practices

Always handle errors: Subscribe to the error event on all modules and the SDK context.
Clean up listeners: Remove event listeners when components unmount to prevent memory leaks.
Use specific events: Subscribe to specific events rather than relying on the wildcard (*) event.
Avoid inline functions with off: Store function references if you need to remove them later.
Don’t block event handlers: Keep event handler logic lightweight. Use async handlers for heavy operations.
Monitor network events: Handle offline scenarios gracefully by listening to network events.
Log telemetry in production: Use telemetry events to monitor SDK behavior in production.

Debugging Events

Log All Events

if (process.env.NODE_ENV === 'development') {
  oneSDKInstance.on('*', (event) => {
    console.debug('[OneSDK Event]', event.eventName, event.arguments);
  });
}

Event Timeline

const eventLog = [];

oneSDKInstance.on('*', (event) => {
  eventLog.push({
    timestamp: Date.now(),
    name: event.eventName,
    args: event.arguments
  });
});

// Later, inspect the timeline
console.table(eventLog);

​Overview

​Event Methods

​on(eventName, callback)

​off(eventName, callback)

​emit(eventName, ...args)

​Global Events

​Common Events

​SDK-Specific Events

​Event Examples

​Handling Errors

​Monitoring Loading States

​Telemetry Events

​Network Status Monitoring

​Configuration Events

​Wildcard Event Listener

​Module Events

​Individual Module Events

​Component Events

​Event Patterns

​Async Event Handling

​Event Cleanup

​Event Chaining

​Error Event Details

​Error Handling Example

​Telemetry Event Structure

​Telemetry Event Details

​Best Practices

​Debugging Events

​Log All Events

​Event Timeline

​Related

Overview

Event Methods

`on(eventName, callback)`

`off(eventName, callback)`

`emit(eventName, ...args)`

Global Events

Common Events

SDK-Specific Events

Event Examples

Handling Errors

Monitoring Loading States

Telemetry Events

Network Status Monitoring

Configuration Events

Wildcard Event Listener

Module Events

Individual Module Events

Component Events

Event Patterns

Async Event Handling

Event Cleanup

Event Chaining

Error Event Details

Error Handling Example

Telemetry Event Structure

Telemetry Event Details

Best Practices

Debugging Events

Log All Events

Event Timeline

Related