airvoy 1.0.0

Flutter SDK for Airvoy - Zero-rated eSIM connectivity for mobile apps. Give your users connectivity, keep your competitors offline.

Airvoy Flutter SDK

Give your users connectivity. Keep your competitors offline.

The Airvoy SDK enables zero-rated eSIM connectivity for mobile apps. Users get free access to your app and whitelisted domains, with optional paid upgrades for full internet access.

Features

• Zero-rated connectivity — Your app works abroad without using user's mobile data
• One-tap eSIM installation — Native iOS/Android setup via universal links
• Data management — Set limits, check usage, upgrade plans
• Pre-built widgets — Drop-in UI components for eSIM status, QR codes, upsells
• Push notifications — Alert users when they've used 80%, 95%, or 100% of data

Installation

Add to your pubspec.yaml:

dependencies:
  airvoy: ^1.0.0

Then run:

flutter pub get

Quick Start

import 'package:airvoy/airvoy.dart';

// Initialize the client
final airvoy = Airvoy(
  apiKey: 'sk_live_your_api_key',
  groupId: 'your-group-id',
);

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

// Install on their device (opens native eSIM setup)
await airvoy.installOnDevice(esim.activationCode);

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

// Upgrade to full internet when user pays
await airvoy.enableFullInternet(esim.id, dataLimitMb: 1024);

API Reference

Initialization

final airvoy = Airvoy(
  apiKey: 'sk_live_xxx',      // Required: Your API key
  groupId: 'g546cfz...',              // Required: Your default group ID
);

eSIM Management

Method	Description
createEsim({groupId})	Create a new eSIM
getEsim(esimId)	Get eSIM details including status and usage
getUsage(esimId)	Get data usage statistics
enableEsim(esimId)	Enable eSIM connectivity
disableEsim(esimId)	Disable eSIM connectivity

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

// Get details
final esim = await airvoy.getEsim('esim-id');
print('Status: ${esim.status}');
print('Connected: ${esim.isConnected}');
print('Full Internet: ${esim.fullInternet}');

// Get usage
final usage = await airvoy.getUsage('esim-id');
print('Used: ${usage.usedMb} MB');
print('Limit: ${usage.limitMb} MB');
print('Remaining: ${usage.remainingMb} MB');
print('Percent used: ${usage.percentUsed}%');

// Enable/disable
await airvoy.enableEsim('esim-id');
await airvoy.disableEsim('esim-id');

Data Management

Method	Description
setDataLimit(esimId, limitMb)	Set or update data limit
enableFullInternet(esimId, dataLimitMb)	Upgrade to unrestricted internet
disableFullInternet(esimId)	Return to restricted (free) mode

// User buys 2GB data package
await airvoy.setDataLimit('esim-id', limitMb: 2048);

// User upgrades to full internet with 1GB
await airvoy.enableFullInternet('esim-id', dataLimitMb: 1024);

// User's data runs out, back to free restricted mode
await airvoy.disableFullInternet('esim-id');

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 eSIM support

// One-tap install (recommended)
await airvoy.installOnDevice(esim.activationCode);

// Or get platform-specific links
final iosLink = airvoy.getIosInstallLink(esim.activationCode);
final androidLink = airvoy.getAndroidInstallLink(esim.activationCode);

// Check support
if (airvoy.isEsimSupported) {
  // Show install button
}

Push Notifications

Register for notifications when data usage reaches thresholds:

// Register with FCM token (Android)
await airvoy.registerForNotifications(
  'esim-id',
  fcmToken: 'your-fcm-token',
  thresholds: [80, 95, 100], // Notify at 80%, 95%, 100%
);

// Register with APNs token (iOS)
await airvoy.registerForNotifications(
  'esim-id',
  apnsToken: 'your-apns-token',
  thresholds: [80, 95, 100],
);

// Update thresholds
await airvoy.updateNotificationThresholds(
  'esim-id',
  thresholds: [50, 75, 90, 100],
);

// Unregister
await airvoy.unregisterNotifications('esim-id');

Pre-built Widgets

EsimCard

A complete eSIM status card with usage, QR code, and action buttons.

EsimCard(
  airvoy: airvoy,
  esimId: 'xxx',
  showQrCode: true,
  onInstall: () => print('Installing...'),
  onUpgrade: () => showUpgradeDialog(),
  onDisable: () => confirmDisable(),
)

UsageMeter

A progress bar showing data usage.

// With auto-loading
UsageMeter(
  airvoy: airvoy,
  esimId: 'xxx',
  height: 8,
  showLabels: true,
)

// With existing Usage object
UsageMeterBar(
  usage: usage,
  height: 8,
)

QrCodeView

Display QR code for manual eSIM installation.

QrCodeView(
  activationCode: esim.activationCode,
  size: 200,
  showCopyButton: true,
  showActivationCode: false,
)

InstallButton

One-tap button to open native eSIM setup.

InstallButton(
  activationCode: esim.activationCode,
  text: 'Install eSIM',
  icon: Icons.install_mobile,
  onInstalled: () => print('Setup opened!'),
  onError: (e) => showError(e),
)

// Compact icon-only version
InstallIconButton(
  activationCode: esim.activationCode,
  size: 48,
  onInstalled: () => refresh(),
)

UpsellBanner

Prompt users to upgrade to full internet access.

UpsellBanner(
  airvoy: airvoy,
  esimId: 'xxx',
  title: 'Need full internet?',
  subtitle: 'Access Instagram, TikTok, and more',
  packages: DataPackage.standardPackages,
  onSelectPackage: (package) {
    // Handle payment, then:
    await airvoy.enableFullInternet(
      esimId,
      dataLimitMb: package.dataMb,
    );
  },
)

// Compact button version
UpsellButton(
  text: 'Get full internet',
  onTap: () => showPackages(),
)

Data Packages

Pre-defined packages for upselling:

// Use standard packages
DataPackage.standardPackages
// [
//   DataPackage(id: 'pkg_500mb', name: 'Light', dataMb: 500, price: 4.99),
//   DataPackage(id: 'pkg_1gb', name: 'Standard', dataMb: 1024, price: 7.99),
//   DataPackage(id: 'pkg_3gb', name: 'Plus', dataMb: 3072, price: 14.99),
//   DataPackage(id: 'pkg_5gb', name: 'Premium', dataMb: 5120, price: 19.99),
// ]

// Or create custom packages
final customPackages = [
  DataPackage(
    id: 'daily_pass',
    name: 'Day Pass',
    dataMb: 250,
    price: 2.99,
  ),
];

Error Handling

The SDK throws typed exceptions for different error conditions:

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

Models

Esim

esim.id                 // Unique identifier
esim.groupId            // Group this eSIM belongs to
esim.iccid              // SIM card identifier
esim.status             // EsimStatus.enabled or .disabled
esim.activationCode     // LPA activation code
esim.dataLimitMb        // Current data limit
esim.fullInternet       // true if unrestricted access
esim.connectionStatus   // ConnectionStatus.connected or .disconnected
esim.ipAddress          // Current IP when connected
esim.usage              // Usage object (if available)
esim.isEnabled          // Convenience: status == enabled
esim.isConnected        // Convenience: connectionStatus == connected
esim.isRestricted       // Convenience: !fullInternet
esim.iosInstallLink     // iOS universal link
esim.androidInstallLink // Android universal link

Usage

usage.usedMb            // Data used in MB
usage.limitMb           // Data limit in MB
usage.remainingMb       // Data remaining in MB
usage.percentUsed       // Percentage used (0-100)
usage.percentRemaining  // Percentage remaining (0-100)
usage.isExhausted       // true if limit reached
usage.usedFormatted     // "512.5 MB" or "1.2 GB"
usage.limitFormatted    // Formatted limit
usage.remainingFormatted // Formatted remaining
usage.isAboveThreshold(80) // Check if above threshold

Platform Support

Platform	eSIM Installation	Push Notifications
iOS	✅ Universal link	✅ APNs
Android	✅ Universal link	✅ FCM

Requirements

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

Example App

See the /example folder for a complete demo app showing:

• eSIM creation and installation
• Usage monitoring
• Full internet upgrades
• All pre-built widgets

cd example
flutter run

Getting Your API Key

1. Visit airvoy.app/dashboard
2. Create an account
3. Add minimum balance ($250)
4. Create a group with your whitelisted domains
5. Generate your API key (starts with sk_live_)

Support

• Documentation: airvoy.app/docs
• Email: [e-mail]
• Issues: GitHub Issues

License

MIT License - see LICENSE file for details.

---

Built with ❤️ by Airvoy