Documentation

SDKappsprint-flutter

Flutter

Installation, configuration, event tracking, and full API reference for the Flutter SDK.

Requirements

Flutter 3.22+
Dart 3.3+
iOS and Android toolchains installed

1. Install

Git dependency

# pubspec.yaml
dependencies:
  appsprint_flutter:
    git:
      url: https://github.com/app-sprint/appsprint-flutter.git

Run flutter pub get after adding the dependency. On iOS, run pod install from the ios/ directory.

2. Configure

import 'package:appsprint_flutter/appsprint_flutter.dart';

// Call before runApp() or in your first widget's initState
await AppSprint.instance.configure(
  const AppSprintConfig(apiKey: 'as_live_xxxxx'),
);

Call as early as possible. The SDK auto-tracks the install on first launch and flushes queued events. Platform-specific code (AdServices on iOS, device info) runs through method channels.

Configuration options

Option	Type	Default	Description
apiKey	String	—	Your live API key (starts with as_live_).
apiUrl	String	https://api.appsprint.app	Override the API base URL.
enableAppleAdsAttribution	bool	true	Fetch AdServices token on iOS. Ignored on Android.
isDebug	bool	false	Enable debug logging.
customerUserId	String?	null	Set a customer user ID at init time.

3. Track events

// Standard event
await AppSprint.instance.sendEvent(AppSprintEventType.login);

// Revenue event
await AppSprint.instance.sendEvent(
  AppSprintEventType.purchase,
  params: {'revenue': 9.99, 'currency': 'USD'},
);

// Custom event with parameters
await AppSprint.instance.sendEvent(
  AppSprintEventType.custom,
  name: 'level_complete',
  params: {'level': 5, 'score': 1200},
);

Supported event types

loginsign_upregisterpurchasesubscribestart_trialadd_to_cartadd_to_wishlistinitiate_checkoutview_contentview_itemsearchsharetutorial_completelevel_startlevel_completecustom

Use custom with a name parameter for any event not in this list.

4. Read attribution

After configure() completes, the SDK caches the attribution result from the install response. Access it synchronously:

final attr = AppSprint.instance.getAttribution();
print(attr?.source);       // "apple_ads", "fingerprint", or "organic"
print(attr?.confidence);   // 0.0–1.0
print(attr?.campaignName); // Campaign name if available

Field	Description
source	"apple_ads", "fingerprint", or "organic"
confidence	Match confidence from 0.0 to 1.0
campaignName	Campaign name (if attributed to an ad)
utmSource	UTM source from the tracking link
utmMedium	UTM medium from the tracking link
utmCampaign	UTM campaign from the tracking link

API reference

configure(config)

→ Future<void>

Initialize the SDK. Auto-tracks install and flushes queue.

await AppSprint.instance.configure(const AppSprintConfig(apiKey: '…'));

sendEvent(type, {name, params})

→ Future<void>

Send an event. Queued if offline.

await AppSprint.instance.sendEvent(AppSprintEventType.purchase, params: {'revenue': 9.99});

flush()

→ Future<void>

Retry all queued events immediately.

await AppSprint.instance.flush()

clearData()

→ Future<void>

Clear all cached state, queue, and disabled flag.

await AppSprint.instance.clearData()

getAppSprintId()

→ String?

Returns install ID, or null before install completes.

final id = AppSprint.instance.getAppSprintId();

getAttribution()

→ AttributionResult?

Returns cached attribution data.

final attr = AppSprint.instance.getAttribution();

isInitialized()

→ bool

True once configure() has completed.

AppSprint.instance.isInitialized()

sendTestEvent()

→ Future<TestEventResult>

Send a diagnostic event. Returns success/message.

final result = await AppSprint.instance.sendTestEvent();

setCustomerUserId(id)

→ Future<void>

Attach your own user ID.

await AppSprint.instance.setCustomerUserId('user-123');

Offline behavior

Events that fail to send are automatically queued in native storage (up to 100 events).
The queue persists across app restarts.
Queued events are retried automatically when configure() completes, when the app moves to the background, or when you call flush().
If a queued event receives a 401/403, the SDK disables itself and clears the queue.

Platform notes

Flutter wraps the native iOS and Android SDKs through method channels. Apple Ads attribution is only available on iOS.
Device info collection uses native platform code — the Dart layer does not access device APIs directly.
The event queue and offline behavior are handled at the native layer and persist across app restarts.

Integrations

Once the SDK is configured, connect revenue and ad-network integrations:

RevenueCat

Attribute subscriptions and purchases

Superwall

Attribute paywall conversions

Apple Search Ads

Campaign and keyword attribution

Troubleshooting

getAppSprintId() returns null

configure() is async. Await it before reading the ID, or check isInitialized().

Events not appearing in dashboard

Verify your API key. Call sendTestEvent() and check the result message.

SDK disabled after 401/403

Call clearData() and re-configure with a valid key.

iOS pod install fails

Run flutter clean, then flutter pub get, then cd ios && pod install --repo-update.

Connectivity test

final result = await AppSprint.instance.sendTestEvent();
print('${result.success} — ${result.message}');

Verification checklist

Create a blank Flutter app and add the Git dependency.
Call configure() before runApp() or in your first widget.
Verify getAppSprintId() returns a value after first launch.
Send login, purchase, and custom events — confirm in dashboard.
Send an event offline, restart the app online — verify queue flush.
Call sendTestEvent() and confirm { success: true }.