Passage React Native SDK

A React Native SDK for integrating Passage into your iOS and Android applications.

Installation

npm install @getpassage/react-native react-native-webview @react-native-cookies/cookies
# or
yarn add @getpassage/react-native react-native-webview @react-native-cookies/cookies

iOS Setup

cd ios && pod install

Usage

1. Wrap your app with the Provider

import { PassageProvider } from "@getpassage/react-native";

function App() {
  return (
    <PassageProvider
      config={{
        debug: false,
      }}
    >
      <YourAppContent />
    </PassageProvider>
  );
}

2. Use the hook in your components

import React from "react";
import { Button, View } from "react-native";
import { usePassage } from "@getpassage/react-native";

function ConnectButton() {
  const passage = usePassage();

  const handleConnect = async () => {
    try {
      // Step 1: Initialize with your publishable key
      await passage.initialize({
        publishableKey: "your-publishable-key",
        prompts: [
          {
            identifier: "welcome",
            prompt: "Welcome to our app!",
            integrationid: "your-integration-id",
            forceRefresh: false,
          },
        ],
        onConnectionComplete: (connection) => {
          console.log("Connection established:", connection);
        },
        onConnectionError: (error) => {
          console.error("Connection error:", error);
        },
        onDataComplete: (data) => {
          console.log("Data received:", data);
        },
        onPromptComplete: (prompt) => {
          console.log("Prompt completed:", prompt);
        },
        onExit: (reason) => {
          console.log("User exited:", reason);
        },
      });

      // Step 2: Open the modal
      await passage.open({
        presentationStyle: "modal", // or "fullScreen");
      });
    } catch (error) {
      console.error("Failed to connect:", error);
    }
  };

  return (
    <View>
      <Button title="Connect with Passage" onPress={handleConnect} />
    </View>
  );
}

3. Headless Connection (Optional)

You can also connect without opening a modal:

const handleHeadlessConnect = async () => {
  try {
    await passage.connect({
      intentToken: "your-intent-token",
      onMessage: (message) => {
        console.log("Received message:", message);
      },
      onError: (error) => {
        console.error("Connection error:", error);
      },
      onClose: () => {
        console.log("Connection closed");
      },
    });
  } catch (error) {
    console.error("Failed to connect:", error);
  }
};

const handleDisconnect = () => {
  passage.disconnect();
};

API Reference

PassageProvider

The provider component that manages the Passage state.

interface PassageConfig {
  baseUrl?: string; // Default: varies by environment
  socketUrl?: string; // Default: varies by environment
  socketNamespace?: string; // Default: "/ws"
  debug?: boolean; // Default: false
}

<PassageProvider config={config}>{children}</PassageProvider>;

usePassage

Hook that provides access to Passage functionality.

Returns an object with these methods:

initialize(options: PassageInitializeOptions)

Initialize Passage with your publishable key and configuration. Must be called before open().

interface PassageInitializeOptions {
  publishableKey: string;
  prompts?: PassagePrompt[];
  onConnectionComplete?: (data: PassageSuccessData) => void;
  onError?: (error: PassageErrorData) => void;
  onDataComplete?: (data: PassageDataResult) => void;
  onPromptComplete?: (prompt: PassagePromptResponse) => void;
  onExit?: (reason?: string) => void;
}

open(options?: PassageOpenOptions)

Open the Passage modal. Must call initialize() first.

interface PassageOpenOptions {
  intentToken?: string; // Optional - uses internal token if not provided
  onConnectionComplete?: (data: PassageSuccessData) => void;
  onConnectionError?: (error: PassageErrorData) => void;
  onDataComplete?: (data: PassageDataResult) => void;
  onPromptComplete?: (prompt: PassagePromptResponse) => void;
  onExit?: (reason?: string) => void;
  presentationStyle?: "modal" | "fullScreen"; // Default: "modal"
}

close()

Close the Passage modal.

getData()

Get stored session data and prompts.

connect(options: PassageConnectOptions)

Connect to Passage in headless mode (no UI).

interface PassageConnectOptions {
  intentToken: string;
  onMessage?: (message: any) => void;
  onError?: (error: PassageErrorData) => void;
  onClose?: () => void;
}

disconnect()

Disconnect from Passage.

Type Definitions

interface PassagePrompt {
  identifier: string;
  prompt: string;
  integrationid: string;
  forceRefresh: boolean;
}

interface PassageConnection {
  id: string;
  integrationId?: string;
  data?: any;
  sessionInfo?: {
    cookies: any[];
    localStorage: any[];
    sessionStorage: any[];
  };
}

interface PassageErrorData {
  error: string;
  data?: any;
}

interface PassageDataResult {
  data?: any;
  prompts?: Array<{
    prompt: string;
    results: any;
  }>;
}

Features

• TypeScript Support: Full TypeScript support with type definitions
• Cookie Management: Automatic cookie handling via @react-native-cookies/cookies
• Remote Control: Built-in support for automation and remote control
• Modal & Full Screen: Support for both modal and full-screen presentation
• Cross-Platform: Works on both iOS and Android

Requirements

• React Native >= 0.60.0
• React >= 16.8.0 (Hooks support)
• react-native-webview >= 11.0.0
• @react-native-cookies/cookies >= 6.0.0

Support

For issues and questions, please visit our GitHub repository.

License

MIT © Passage