Airvoy React Native SDK

React Native SDK for the Airvoy eSIM connectivity API.

Installation

npm install airvoy-react-native

Required Peer Dependencies

npm install react-native-svg react-native-qrcode-svg @react-native-clipboard/clipboard

For iOS:

cd ios && pod install

Quick Start

import { Airvoy, AirvoyProvider, EsimCard } from 'airvoy-react-native'

// Option 1: Direct usage
const airvoy = new Airvoy({
  apiKey: 'sk_live_your_api_key',
  groupId: 'your_group_id',
})

const esim = await airvoy.createEsim()
await airvoy.installOnDevice(esim.activationCode)

const usage = await airvoy.getUsage(esim.id)
console.log(`${usage.usedMb} / ${usage.limitMb} MB`)

await airvoy.enableFullInternet(esim.id, 1024)

// Option 2: With React Context
function App() {
  return (
    <AirvoyProvider apiKey="sk_live_xxx" groupId="your_group_id">
      <MyScreen />
    </AirvoyProvider>
  )
}

function MyScreen() {
  return (
    <EsimCard
      esimId="abc123"
      onInstall={() => console.log('Installing...')}
      onUpgrade={() => console.log('Upgrading...')}
    />
  )
}

API Reference

Initialization

const airvoy = new Airvoy({
  apiKey: 'sk_live_abc',
  groupId: 'abc123',
})

eSIM Management

| Method | Description | |--------|-------------| | createEsim(groupId?) | Create a new eSIM | | getEsim(esimId) | Get eSIM details | | getUsage(esimId) | Get data usage | | enableEsim(esimId) | Enable connectivity | | disableEsim(esimId) | Disable connectivity |

Data Management

| Method | Description | |--------|-------------| | setDataLimit(esimId, limitMb) | Set data limit in MB | | enableFullInternet(esimId, dataLimitMb) | Enable unrestricted access | | disableFullInternet(esimId) | Return to filtered mode |

Installation

| Method | Description | |--------|-------------| | installOnDevice(activationCode) | Open native eSIM setup | | installEsim(esim) | Install using Esim object | | getIosInstallLink(code) | Get iOS universal link | | getAndroidInstallLink(code) | Get Android universal link | | isEsimSupported() | Check device support |

Push Notifications

await airvoy.registerForNotifications(esimId, {
  fcmToken: 'token',        // Android
  apnsToken: 'token',       // iOS
  thresholds: [80, 95, 100],
})

await airvoy.unregisterNotifications(esimId)

await airvoy.updateNotificationThresholds(esimId, [50, 75, 100])

Hooks

import { useEsim, useUsage, useAirvoy } from 'airvoy-react-native'

function MyComponent() {
  const airvoy = useAirvoy()
  const { esim, loading, error, refresh } = useEsim('esim_id')
  const { usage } = useUsage('esim_id')

  if (loading) return <Text>Loading...</Text>
  if (error) return <Text>Error: {error.message}</Text>

  return <Text>{esim?.iccid}</Text>
}

Components

EsimCard

Complete eSIM status card with usage, QR code, and actions.

<EsimCard
  esimId="abc"
  onInstall={() => {}}
  onUpgrade={() => {}}
  onDisable={() => {}}
  showQrCode={true}
/>

UsageMeter

Data usage progress bar.

<UsageMeter esimId="abc" height={8} showLabels={true} />

// Or with existing Usage object
<UsageMeterBar usage={usage} />

QrCodeView

QR code for manual installation.

<QrCodeView
  activationCode={esim.activationCode}
  size={200}
  showCopyButton={true}
  onCopied={() => console.log('Copied!')}
/>

InstallButton

One tap installation button.

<InstallButton
  activationCode={esim.activationCode}
  onInstalled={() => {}}
  onError={(e) => console.error(e)}
  text="Install eSIM"
/>

<InstallIconButton
  activationCode={esim.activationCode}
  size={48}
/>

UpsellBanner

Prompt to upgrade to full internet.

<UpsellBanner
  esimId="abc"
  onUpgrade={(dataMb) => airvoy.enableFullInternet('abc', dataMb)}
  title="Need full internet?"
  subtitle="Upgrade to access any website or service"
/>

<UpsellButton onPress={() => {}} text="Get full internet" />

Error Handling

import {
  AirvoyException,
  AuthenticationException,
  InsufficientBalanceException,
  ValidationException,
  NotFoundException,
  NetworkException,
} from 'airvoy-react-native'

try {
  await airvoy.createEsim()
} catch (e) {
  if (e instanceof AuthenticationException) {
    // Invalid API key (401)
  } else if (e instanceof InsufficientBalanceException) {
    // Low balance (402)
    console.log(`Balance: ${e.balance}, Required: ${e.minimumRequired}`)
  } else if (e instanceof ValidationException) {
    // Invalid parameters (400)
  } else if (e instanceof NotFoundException) {
    // Resource not found (404)
  } else if (e instanceof NetworkException) {
    // Connection error
  } else if (e instanceof AirvoyException) {
    // Other API errors
    console.log(e.code, e.message)
  }
}

Models

Esim

interface Esim {
  id: string
  groupId: string
  iccid: string
  status: 'enabled' | 'disabled'
  imsi?: string
  msisdn?: string
  activationCode: string
  dataLimitMb: number
  fullInternet: boolean
  originalGroupId?: string
  connectionStatus: 'connected' | 'disconnected'
  ipAddress?: string
  usage?: Usage
  createdAt: string
  updatedAt: string
}

// Helper functions
isEnabled(esim)           // status === 'enabled'
isConnected(esim)         // connectionStatus === 'connected'
isRestricted(esim)        // !fullInternet
getIosInstallLink(code)   // iOS universal link
getAndroidInstallLink(code) // Android universal link

Usage

interface Usage {
  usedMb: number
  limitMb: number
}

// Helper functions
getRemainingMb(usage)
getPercentUsed(usage)        // 0-100
getPercentRemaining(usage)
isExhausted(usage)
isAboveThreshold(usage, 80)
formatMb(1024)               // "1.0 GB"
getUsedFormatted(usage)      // "512.5 MB"
getLimitFormatted(usage)
getRemainingFormatted(usage)

Requirements

• React Native 0.68+
• React 18+
• iOS 12.1+ (eSIM support)
• Android 9+ (eSIM support)

License

MIT