Komissio SDK for Flutter

Official Flutter SDK for Komissio — track affiliate conversions, attribute referrals, and auto-calculate commissions in your mobile app.

Features

• Deep link attribution — automatically capture ref, cmp, coupon from deep links
• Conversion tracking — one-time purchases, subscriptions, custom events
• Auto-commission — commissions calculated server-side using your commission rules
• Offline queue — conversions are queued and retried when connectivity returns
• Idempotency — orderId prevents duplicate conversions
• Rich metadata — platform, device, app version, sub-IDs, custom fields
• 30-day attribution window — persisted locally, auto-expires

Installation

dependencies:
  komissio_sdk: ^1.0.0

Quick Start

1. Initialize

Call configure() once at app startup (before runApp or in your first widget's initState):

import 'package:komissio_sdk/komissio_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Komissio.configure(
    apiKey: 'km_live_your_api_key',
    merchantId: 'your-merchant-uuid',
    appVersion: '1.2.3',          // shown in your dashboard
    logLevel: LogLevel.info,      // enable during development
  );

  runApp(MyApp());
}

2. Handle Deep Links

When your app opens via a deep link containing affiliate attribution:

// Using app_links, uni_links, or go_router deep link handlers:
void onDeepLink(Uri uri) {
  // URI: https://yourapp.com/promo?ref=sarah123&cmp=spring_sale
  Komissio.handleDeepLink(uri);
  // Attribution is now stored locally and will be included in all conversions
}

3. Track Conversions

// One-time purchase
final result = await Komissio.trackConversion(
  eventType: EventType.oneTimePurchase,
  customerIdentifier: 'user@example.com',
  value: 49.99,
  orderId: 'order_12345',  // idempotency key
);

if (result.attributed) {
  print('Attributed to ${result.affiliate?.name}');
  print('Commission: ${result.commission?.amount} ${result.commission?.currency}');
}

// Subscription
await Komissio.trackConversion(
  eventType: EventType.subscriptionCreated,
  customerIdentifier: 'user@example.com',
  value: 9.99,
  orderId: 'sub_67890',
  metadata: {'plan': 'premium', 'billing': 'monthly'},
);

4. Identify Users (Optional)

Link a customer ID for recurring commission tracking across sessions:

await Komissio.identify(customerId: 'stripe_cust_abc123');

5. Manual Attribution (Optional)

Set attribution directly (e.g., from a QR code scan or promo screen):

await Komissio.setAttribution(
  ref: 'partner_code',
  coupon: 'SAVE20',
);

Configuration Options

Parameter	Default	Description
apiKey	required	Your API key (km_live_...)
merchantId	required	Your merchant UUID
baseUrl	https://api.komissio.io	API base URL
platform	SdkPlatform.flutter	Platform identifier
appVersion	null	Your app version
enableOfflineQueue	true	Queue conversions when offline
maxQueueSize	100	Max offline queue entries
logLevel	LogLevel.none	none, error, info, verbose

Event Types

Event Type	When to Use
EventType.oneTimePurchase	Single purchase completed
EventType.subscriptionCreated	New subscription started
EventType.subscriptionUpgraded	Plan upgraded
EventType.subscriptionDowngraded	Plan downgraded
EventType.subscriptionCancelled	Subscription cancelled
EventType.trackingVisit	Page view / screen visit

Conversion Result

Every trackConversion() call returns a ConversionResult:

ConversionResult(
  attributed: true,                    // was an affiliate matched?
  conversionId: 'uuid',               // server-assigned ID
  trackingMethod: 'referral_link',    // how attribution was resolved
  affiliate: AffiliateInfo(
    programId: 'uuid',
    referralCode: 'sarah123',
    name: 'Sarah Johnson',
  ),
  commission: CommissionInfo(
    id: 'uuid',
    amount: '4.99',                   // auto-calculated
    currency: 'USD',
  ),
  eventType: 'one_time_purchase',
  platform: 'flutter',
  createdAt: DateTime(...),
  deduplicated: false,                // true if orderId was already processed
)

Offline Support

When the device is offline, conversions are queued locally and automatically flushed when connectivity returns. You can also manually control the queue:

// Check queue size
final pending = await Komissio.offlineQueueLength;

// Manually flush
final sent = await Komissio.flushOfflineQueue();

Getting Your API Key

1. Log in to your Komissio dashboard
2. Go to Settings > API Keys
3. Create a new key with read_write scope
4. Copy the key (starts with km_live_)

Requirements

• Flutter 3.10+
• Dart 3.0+
• A Komissio merchant account

License

MIT License. See LICENSE for details.