@capgo/capacitor-persona

Capacitor plugin for launching Persona Inquiry flows in iOS and Android apps.

Install

bun add @capgo/capacitor-persona
bunx cap sync

Usage

import { Persona } from '@capgo/capacitor-persona';

await Persona.addListener('inquiryComplete', (result) => {
  console.log('Persona complete', result.inquiryId, result.status, result.fields);
});

await Persona.addListener('inquiryCanceled', (result) => {
  console.log('Persona canceled', result.inquiryId, result.sessionToken);
});

await Persona.addListener('inquiryError', (result) => {
  console.error('Persona error', result.error, result.errorCode);
});

await Persona.startInquiry({
  templateId: 'itmpl_EXAMPLE',
  environment: 'sandbox',
  referenceId: 'user_123',
  fields: {
    name_first: 'Alex',
    age: 29,
    is_verified_user: true,
  },
});

Integration Notes

• iOS requires Persona usage descriptions in Info.plist, including NSCameraUsageDescription, NSLocationWhenInUseUsageDescription, and NSBluetoothAlwaysUsageDescription.
• Android uses Persona's Maven repository (https://sdk.withpersona.com/android/releases) and bundles com.withpersona.sdk2:inquiry.
• For critical business logic, rely on Persona webhooks instead of SDK callbacks.

API

• startInquiry(...)
• addListener('inquiryComplete', ...)
• addListener('inquiryCanceled', ...)
• addListener('inquiryError', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

startInquiry(...)

startInquiry(options: StartInquiryOptions) => Promise<void>

Launch a Persona Inquiry flow.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | StartInquiryOptions |

addListener('inquiryComplete', ...)

addListener(eventName: 'inquiryComplete', listenerFunc: (info: InquiryCompleteInfo) => void) => Promise<PluginListenerHandle>

Listen for successful completion.

| Param | Type | | ------------------ | -------------------------------------------------------------------------------------- | | eventName | 'inquiryComplete' | | listenerFunc | (info: InquiryCompleteInfo) => void |

Returns: Promise<PluginListenerHandle>

addListener('inquiryCanceled', ...)

addListener(eventName: 'inquiryCanceled', listenerFunc: (info: InquiryCanceledInfo) => void) => Promise<PluginListenerHandle>

Listen for cancellation.

| Param | Type | | ------------------ | -------------------------------------------------------------------------------------- | | eventName | 'inquiryCanceled' | | listenerFunc | (info: InquiryCanceledInfo) => void |

Returns: Promise<PluginListenerHandle>

addListener('inquiryError', ...)

addListener(eventName: 'inquiryError', listenerFunc: (info: InquiryErrorInfo) => void) => Promise<PluginListenerHandle>

Listen for unrecoverable errors.

| Param | Type | | ------------------ | -------------------------------------------------------------------------------- | | eventName | 'inquiryError' | | listenerFunc | (info: InquiryErrorInfo) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin instance.

Interfaces

StartInquiryOptions

Input payload used to launch an Inquiry.

Provide at least one of:

• templateId
• templateVersion
• inquiryId

| Prop | Type | Description | Default | | --------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------- | | inquiryId | string | Existing Inquiry ID created on your backend. | | | sessionToken | string | Session token required when resuming an existing Inquiry. | | | templateId | string | Inquiry template ID from Persona Dashboard (recommended). | | | templateVersion | string | Inquiry template version ID from Persona Dashboard. | | | referenceId | string | Your internal user reference. | | | accountId | string | Persona account ID. | | | environment | PersonaEnvironment | Persona environment. | 'production' | | locale | string | Locale override, for example en, fr, es. | | | fields | Record<string, PersonaFieldValue> | Optional fields pre-written into the Inquiry. | |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

InquiryCompleteInfo

Payload emitted when an Inquiry is completed.

| Prop | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | | inquiryId | string | | status | string | | fields | Record<string, PersonaResultFieldValue> |

InquiryCanceledInfo

Payload emitted when an Inquiry is canceled.

| Prop | Type | | ------------------ | ------------------- | | inquiryId | string | | sessionToken | string |

InquiryErrorInfo

Payload emitted when an Inquiry errors.

| Prop | Type | | --------------- | ------------------- | | error | string | | errorCode | string | | cause | string |

Type Aliases

PersonaEnvironment

Environment where Persona should run.

'production' | 'sandbox'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

PersonaFieldValue

Supported field value types for pre-writing Inquiry fields.

string | number | boolean | string[]

PersonaResultFieldValue

Serialized field value returned in Inquiry result callbacks.

string | number | boolean | string[] | null