Expo-ii-integration NPM

expo-ii-integration

This library enables smartphone native applications to authenticate with Internet Identity through a web application bridge. It provides a seamless integration between Expo applications and Internet Identity authentication, with different authentication flows for web and native platforms.

Features

Seamless Internet Identity authentication in Expo apps
Platform-specific authentication flows:
- Web: Modal-based authentication using iframe messaging
- Native: Browser-based authentication using Expo WebBrowser
Secure key and delegation chain management
Platform-agnostic secure storage handling
Type-safe React hooks and context
Automatic path restoration after authentication
Error handling and state management

Installation

npm install expo-ii-integration

Dependencies

This package has the following peer dependencies that you need to install:

{
  "@dfinity/agent": "^0.20.2",
  "@dfinity/identity": "^0.20.2",
  "expo-linking": "~7.0.5",
  "expo-router": "~4.0.17",
  "expo-web-browser": "~14.0.2",
  "react-native": "0.76.7"
}

Usage

Basic Setup

Wrap your app with the IIIntegrationProvider:

import { IIIntegrationProvider, useIIIntegration } from 'expo-ii-integration';

function App() {
  const iiIntegration = useIIIntegration({
    localIPAddress: '192.168.0.210',
    dfxNetwork: 'local',
    iiIntegrationCanisterId: 'YOUR_II_INTEGRATION_CANISTER_ID',
    iiCanisterId: 'YOUR_II_CANISTER_ID'
  });

  return (
    <IIIntegrationProvider value={iiIntegration}>
      {/* Your app components */}
    </IIIntegrationProvider>
  );
}

Using the Authentication Context

import { useIIIntegrationContext } from 'expo-ii-integration';

function AuthButton() {
  const {
    login,
    logout,
    isAuthenticated,
    isReady,
    identity,
    pathWhenLogin, // Path to restore after login
    authError
  } = useIIIntegrationContext();

  if (!isReady) return null;

  return (
    <Button
      onPress={isAuthenticated ? logout : login}
      title={isAuthenticated ? 'Logout' : 'Login with Internet Identity'}
    />
  );
}

API Reference

useIIIntegration Hook

The main hook for Internet Identity integration.

Parameters

type UseIIAuthParams = {
  localIPAddress: string;     // Local IP address for development
  dfxNetwork: string;         // dfx network (e.g., 'local', 'ic')
  iiIntegrationCanisterId: string;  // II Integration canister ID
  iiCanisterId: string;       // Internet Identity canister ID
};

Returns

interface IIIntegrationContextType {
  identity: DelegationIdentity | undefined;  // Current user identity
  isReady: boolean;                         // Authentication state is initialized
  isAuthenticated: boolean;                 // User is authenticated
  login: () => Promise<void>;               // Trigger login flow
  logout: () => Promise<void>;              // Clear authentication
  pathWhenLogin: string | undefined;        // Path to restore after login
  authError: unknown | undefined;           // Authentication errors
}