airvoy 1.0.4

Flutter SDK for Airvoy eSIM connectivity API.

Airvoy Flutter SDK

Flutter SDK for the Airvoy eSIM connectivity API.

Installation

dependencies:
  airvoy: ^1.0.4

Quick Start

import 'package:airvoy/airvoy.dart';

final airvoy = Airvoy(
  apiKey: 'sk_live_your_api_key',
  groupId: 'your_group_id',
);

// Create an eSIM
final esim = await airvoy.createEsim();

// Install on device
await airvoy.installOnDevice(esim.activationCode);

// Check usage
final usage = await airvoy.getUsage(esim.id);
print('${usage.usedFormatted} / ${usage.limitFormatted}');

// Enable full internet access
await airvoy.enableFullInternet(esim.id, dataLimitMb: 1024);

API Reference

Initialization

final airvoy = Airvoy(
  apiKey: 'sk_live_abc',   // Required
  groupId: 'abc123...',         // Required
);

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: int)	Set data limit in MB
enableFullInternet(esimId, dataLimitMb: int)	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, thresholds: [50, 75, 100]);

Widgets

EsimCard

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

EsimCard(
  airvoy: airvoy,
  esimId: 'abc',
  onInstall: () {},
  onUpgrade: () {},
)

UsageMeter

Data usage progress bar.

UsageMeter(airvoy: airvoy, esimId: 'abc')

// Or with existing Usage object
UsageMeterBar(usage: usage)

QrCodeView

QR code for manual installation.

QrCodeView(activationCode: esim.activationCode, size: 200)

InstallButton

One tap installation button.

InstallButton(
  activationCode: esim.activationCode,
  onInstalled: () {},
  onError: (e) {},
)

UpsellBanner

Prompt to upgrade to full internet.

UpsellBanner(
  airvoy: airvoy,
  esimId: 'abc',
  onUpgrade: (dataMb) {},
)

Error Handling

try {
  await airvoy.createEsim();
} on AuthenticationException catch (e) {
  // Invalid API key (401)
} on InsufficientBalanceException catch (e) {
  // Low balance (402)
  print('Balance: ${e.balance}, Required: ${e.minimumRequired}');
} on ValidationException catch (e) {
  // Invalid parameters (400)
} on NotFoundException catch (e) {
  // Resource not found (404)
} on NetworkException catch (e) {
  // Connection error
} on AirvoyException catch (e) {
  // Other API errors
}

Models

Esim

esim.id
esim.groupId
esim.iccid
esim.status              // EsimStatus.enabled or .disabled
esim.activationCode
esim.dataLimitMb
esim.fullInternet
esim.connectionStatus    // ConnectionStatus.connected or .disconnected
esim.ipAddress
esim.usage
esim.isEnabled
esim.isConnected
esim.isRestricted
esim.iosInstallLink
esim.androidInstallLink

Usage

usage.usedMb
usage.limitMb
usage.remainingMb
usage.percentUsed
usage.isExhausted
usage.usedFormatted      // "512.5 MB" or "1.2 GB"
usage.limitFormatted
usage.remainingFormatted
usage.isAboveThreshold(80)

Requirements

• Flutter 3.10.0+
• Dart 3.0.0+
• iOS 12.1+ (eSIM support)
• Android 9+ (eSIM support)

License

MIT