Choosing an integration method

Persona offers three main ways to integrate an identity verification flow into your frontend: Hosted Flow, Embedded Flow, and Mobile SDK. These methods all provide UIs that your end users use to complete Persona inquiries. You’ll see these methods referred to as “Inquiry-based” integrations (also known as “Client-side” integrations).

This guide helps you choose the Inquiry-based integration method that best fits your technical resources, timeline, and product needs.

At a glance

At a glance, here’s how the main Inquiry-based integration methods compare:

These key questions may help you make a quick decision:

┌─ Do you have engineering resources available?
├─ NO → Hosted Flow (fastest, no code required)
└─ YES → Do you have a native mobile app?
    ├─ YES → Mobile SDK (iOS/Android/React Native)
    └─ NO → Do you want to keep users on your domain?
        ├─ YES → Embedded Flow (seamless web integration)
        └─ NO → Hosted Flow with API (fast implementation, scalable)

Below, learn more about how each integration method works and how they compare.

Integration method overviews

You can skip to a section below:

• Hosted Flow
• Embedded Flow
• Mobile SDK

Hosted Flow

When you use a Hosted Flow, users are redirected to a Persona-hosted page to complete verification. This page can be customized with your branding, but it lives on Persona’s domain.

How Hosted Flow works

Here is how you verify a user using Hosted Flow:

• You send the user a URL (via email, SMS, or linked from your app).
• The user clicks the link and is taken to <your custom subdomain>.withpersona.com/verify.
• After the user completes verification, they can be redirected back to your site.

Technical implementation

There are three ways to use Hosted Flow:

1. Create a generic link (No code)
   • Use one link that autogenerates a new inquiry for each user
   • Best for: Sharing with small groups, simple use cases
   • Warning: Users who click the link multiple times will create duplicate inquiries
2. Create unique links manually (No code)
   • Create unique inquiry links one-by-one in the Persona Dashboard
   • Best for: Testing, very low volume (less than ~10 inquiries/month)
3. Create unique links via API (Some code required)
   • Programmatically create a unique inquiry link for each user
   • Best for: High volume and/or personalized experiences
   • Recommended for production use

Note that you can get started with a no-code approach, and migrate to the more scalable code-based approach later.

When to choose Hosted Flow

Hosted Flow may be a good choice if you have these constraints:

• It’s acceptable for users to leave your site temporarily. (Required)
• You need to start verifying users today.
• You have limited engineering resources.
• You’re running a pilot or proof of concept.
• You’re distributing links via email or SMS.

Learn more about integrating with Hosted Flow.

Embedded Flow (Web SDK)

An Embedded Flow embeds Persona’s verification UI directly into your website as an iframe. Users never leave your domain, creating a seamless experience within your content.

How Embedded Flow works

Here’s how you verify a user using Embedded Flow:

• Install Persona’s JavaScript SDK (~10 lines of code).
• When a user visits your website, the SDK opens a modal or inline frame on your page.
• The user completes verification without leaving your page.
• Your code can receive callbacks when the user finishes verification.

Technical implementation

There are two ways to use Embedded Flow. Both require some code:

1. Generate inquiries from an inquiry template (Minimal code required)
   • Embed the web SDK and configure it with your inquiry template ID.
   • A new inquiry is created each time a user starts the flow.
   • Best for: small numbers of users, simple use cases
   • Warning: Users who load your page multiple times will create duplicate inquiries.
2. Pre-create inquiries via API (More code required)
   • Embed the web SDK.
   • For each new user, create a new inquiry ID via API, then pass the inquiry ID to the SDK.
   • Best for: High volume and/or personalized experiences
   • Recommended for production use

Note that you can get started with the simpler implementation, and build up to the more scalable approach later.

Here’s an example of the web SDK code that you would embed into your frontend:

1
import Persona from 'persona';
2
3
const client = new Persona.Client({
4
  templateId: '<a Persona inquiry template ID starting with itmpl_>',
5
  referenceId: "<a unique ID for the current user>",
6
  environmentId: '<a Persona environment ID starting with env_>',
7
  onReady: () => client.open(),
8
  onComplete: ({ inquiryId, status, fields }) => {
9
    console.log('Verification complete!', inquiryId);
10
    // Proceed with your application flow
11
  },
12
  onCancel: ({ inquiryId, sessionToken }) => console.log('User cancelled'),
13
  onError: (error) => console.log('Error:', error)
14
});

When to choose Embedded Flow

Embedded Flow may be a good choice if you have these constraints:

• You have a web application. (Required)
• You have at least frontend development resources. (Required)
• You want to create a seamless experience between your content and the Persona verification flow.
• Keeping users on your domain is important.

Learn more about integrating with Embedded Flow.

Mobile SDK

Persona offers native SDKs for iOS, Android, and React Native that integrate our verification flow directly into your mobile app.

If you already have a mobile app, using Persona’s mobile SDKs can be a great option.

How Mobile SDK works

Here’s how you verify a user using a mobile SDK:

• Install the appropriate SDK for your platform.
• Present the Persona flow as a native screen in your app.
• The SDK handles camera access, photo capture, and uploads.
• Your app receives callbacks with verification results.

Technical implementation

There are two ways to use a mobile SDK:

1. Generate inquiries from an inquiry template
   • Embed the mobile SDK and configure it with your inquiry template ID.
   • A new inquiry is created each time a user starts the flow.
   • Best for: small numbers of users, simple use cases
   • Warning: Users who load your page multiple times will create duplicate inquiries
2. Pre-create inquiries via API
   • Embed the mobile SDK.
   • For each new user, create a new inquiry ID via API, then pass the inquiry ID to the SDK.
   • Recommended for production use.

Both approaches work with all three platforms: iOS, Android, and React Native.

Note that these approaches are analogous to the two ways to implement Embedded Flow.

When to choose Mobile SDK

A mobile SDK may be a good choice if you have these constraints:

• You have a native iOS or Android app. (Required)
• You have mobile development resources. (Required)
• Photo quality and mobile optimization are important.
• You want full control over the mobile experience.

Learn more about integrating with Mobile SDK.