Skip to main content

@zyphe-sdk/browser

Install the package:

pnpm add @zyphe-sdk/browser

Embedding the Zyphe Verification Iframe​

Use the startVerificationSession function to embed a Zyphe verification flow in your web app:

import { startVerificationSession } from '@zyphe-sdk/browser'

const container = document.getElementById('your-container-id')

const flowParams = {
  email: 'user@example.com',
  flowId: 'your-flow-id',
  flowStepId: 'your-flow-step-id',
  isSandbox: true, // or false for production
  customData: {
    /* optional custom data */
  }, // Optional: pass any extra data needed for your flow
}

const opts = {
  apiKey: 'your-api-key',
  // ...other SDK options
}

const result = await startVerificationSession({
  containerElement: container,
  flowParams,
  opts,
  eventHandlers: {
    onSuccess: () => {
      // Handle success
      console.log('Verification completed successfully')
    },
    onFailure: () => {
      // Handle failure
      console.log('Verification failed')
    },
  },
})

if (result.error) {
  // Handle error (e.g., show a message to the user)
  console.error('Failed to start verification session:', result.error)
} else {
  // Session created successfully, iframe embedded
  console.log('Verification session started successfully')
}

Key Features​

  • Non-throwing API: The function returns a Result object: { error, data }. If session creation fails, error will be set and no iframe will be embedded.
  • Automatic iframe management: Creates and appends an iframe to the specified container with proper styling and permissions.
  • Event handling: Listen for success and failure events from the verification flow.
  • Camera permissions: The iframe is automatically configured with camera permissions for document and identity verification.

API Reference​

startVerificationSession({ containerElement, flowParams, opts, eventHandlers })​

Creates a verification session and embeds the Zyphe iframe in the specified container.

Parameters​

  • containerElement: HTMLElement - The DOM element to append the iframe to
  • flowParams: InitializeZypheFlowParams - The parameters for the verification flow
    • email: string - User's email address
    • flowId: string - The ID of the verification flow
    • flowStepId: string - The ID of the specific flow step
    • isSandbox: boolean - Whether to use sandbox or production environment
    • customData?: any - Optional custom data to pass to the flow
  • opts: SDKOptions - SDK configuration options (e.g., { apiKey })
  • eventHandlers?: { onSuccess?, onFailure? } - Optional event handlers
    • onSuccess?: () => void - Called when verification completes successfully
    • onFailure?: () => void - Called when verification fails

Returns​

Promise<{ error?: any, data?: any }> - A Result object

  • If error is present, session creation failed and no iframe is embedded
  • If data is present, session was created and iframe is embedded

Example​

const result = await startVerificationSession({
  containerElement: document.getElementById('verification-container'),
  flowParams: {
    email: 'user@example.com',
    flowId: 'flow_123',
    flowStepId: 'step_456',
    isSandbox: true,
    customData: { userId: 'user_789' },
  },
  opts: { apiKey: 'your-api-key' },
  eventHandlers: {
    onSuccess: () => console.log('Verification successful'),
    onFailure: () => console.log('Verification failed'),
  },
})

Browser Compatibility​

This SDK requires a modern browser with support for:

  • ES6+ features
  • Web Crypto API (for future webhook signature verification)
  • Iframe elements