expo-esim-manager

Expo module for managing eSIM functionality on Android devices. This module provides a comprehensive interface for installing, managing, and monitoring eSIM profiles on Android devices that support eSIM technology.

Features

• ✅ Install eSIM profiles using activation codes
• ✅ Scan QR codes for eSIM installation
• ✅ List installed eSIM profiles
• ✅ Check eSIM support on device
• ✅ Diagnostic information
• ✅ Real-time installation status tracking
• ✅ Comprehensive error handling
• ✅ React Hook for easy integration

Platform Support

• Android: ✅ Full support
• iOS: ❌ Not implemented (iOS eSIM management requires different APIs)

Installation

npx expo install expo-esim-manager

Permissions

This module requires the following Android permissions:

• READ_PHONE_STATE
• READ_PHONE_NUMBERS

The module will automatically request these permissions when needed.

Usage

Basic Usage

import { ExpoEsimManager, useEsimManager } from "expo-esim-manager";

// Check if device supports eSIM
const isSupported = ExpoEsimManager.isEsimSupported();

// Get installed eSIM profiles
const installedEsims = ExpoEsimManager.getInstalledEsims();

// Install eSIM using activation code
const installEsim = async (activationCode) => {
  try {
    const result = await ExpoEsimManager.install({ activationCode });
    console.log("eSIM installed successfully:", result);
  } catch (error) {
    console.error("Installation failed:", error);
  }
};

// Scan QR code for eSIM installation
const scanQrCode = async () => {
  try {
    const result = await ExpoEsimManager.scanQrCode();
    console.log("eSIM installed from QR code:", result);
  } catch (error) {
    console.error("QR scan failed:", error);
  }
};

Using the React Hook

import React from "react";
import { View, Text, Button } from "react-native";
import { useEsimManager, InstallationStatus } from "expo-esim-manager";

export default function EsimManager() {
  const {
    permissionsGranted,
    installedEsims,
    installationStatus,
    installError,
    installESim,
    scanQrCode,
    runDiagnostic,
  } = useEsimManager();

  const handleInstall = async () => {
    await installESim("your-activation-code-here");
  };

  const handleScanQr = async () => {
    await scanQrCode();
  };

  return (
    <View>
      <Text>Permissions: {permissionsGranted ? "Granted" : "Not Granted"}</Text>
      <Text>Installed eSIMs: {installedEsims.length}</Text>
      <Text>Status: {installationStatus}</Text>

      {installError && <Text>Error: {installError.message}</Text>}

      <Button title="Install eSIM" onPress={handleInstall} />
      <Button title="Scan QR Code" onPress={handleScanQr} />
      <Button title="Run Diagnostic" onPress={runDiagnostic} />
    </View>
  );
}

API Reference

Core Functions

isEsimSupported(): boolean

Checks if the device supports eSIM functionality.

getInstalledEsims(): EsimInfo[]

Returns an array of installed eSIM profiles.

install(params: { activationCode: string }): Promise<EsimInstallResult>

Installs an eSIM profile using an activation code.

scanQrCode(): Promise<EsimInstallResult>

Opens QR code scanner for eSIM installation.

diagnosticInfo(): Record<string, any>

Returns diagnostic information about the eSIM system.

React Hook: useEsimManager()

Returns an object with the following properties:

State Properties

• permissionsGranted: boolean - Whether required permissions are granted
• installedEsims: EsimInfo[] - Array of installed eSIM profiles
• diagnosticData: any - Diagnostic information
• installationStatus: InstallationStatus - Current installation status
• installError: InstallError - Error information if installation failed

Actions

• installESim(activationCode: string): Promise<void> - Install eSIM with activation code
• scanQrCode(): Promise<void> - Scan QR code for eSIM installation
• runDiagnostic(): void - Run diagnostic check
• checkInstalledEsims(): void - Refresh installed eSIM list

Types

EsimInfo

type EsimInfo = {
  displayName: string;
  carrierName: string;
  isActive: boolean;
  subscriptionId: number;
  countryIso: string;
};

EsimInstallResult

type EsimInstallResult = {
  status: "success";
  message: string;
};

InstallationStatus

enum InstallationStatus {
  NotStarted = "NotStarted",
  Started = "Started",
  Confirming = "Confirming",
  Completed = "Completed",
  Failed = "Failed",
  Cancelled = "Cancelled",
}

EsimInstallError

type EsimInstallError = {
  code: string; // Various error codes
  message: string;
};

Error Codes

The module provides comprehensive error handling with specific error codes:

• INVALID_ACTIVATION_CODE - Invalid or expired activation code
• PROFILE_ALREADY_EXISTS - eSIM profile already installed
• NETWORK_ERROR - Network connectivity issues
• SERVER_ERROR - Server-side errors
• USER_CANCELED - User cancelled the operation
• UNSUPPORTED_ERROR - Device doesn't support eSIM
• AMBIGUOUS_RESULT - Installation result unclear (requires verification)

And many more specific error codes for different scenarios.

Example Project

Check out the example/ directory for a complete working example of how to use this module.

Development

# Install dependencies
npm install

# Build the module
npm run build

# Run tests
npm test

# Open example app
npm run open:android

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Report a bug
• 💡 Request a feature