Appstack Flutter Plugin

Track events and revenue with Apple Search Ads attribution in your Flutter app.

pub.dev repository

Here, you will find the pub.dev appstack_plugin documentation. Please use the latest available version of the SDK.

Requirements

iOS

• iOS version: 15.0+
• Xcode: 14.0+

Android

• Minimum SDK: Android 5.0 (API level 21)
• Target SDK: 34+

General

• Flutter: 3.3.0+
• Dart: 2.18.0+

Initial setup

Advanced usage

Attribution parameters

Two methods are available to retrieve attribution parameters:

Method	Mechanism	When to use
getAttributionParams()	Future — request/response over method channel	Simple use cases where timing is predictable
getAttributionParamsWithCallback()	Stream — native background thread pushes result	When retrieval time may vary; frees the platform thread immediately

getAttributionParams()

final params = await AppstackPlugin.getAttributionParams();
if (params != null) {
  print('Attribution params: $params');
}

getAttributionParamsWithCallback()

Spawns a native background thread (Swift Task.detached on iOS, Thread on Android). The stream emits exactly one value then closes.

AppstackPlugin.getAttributionParamsWithCallback().listen(
  (params) {
    if (params != null) {
      print('Attribution params: $params');
    }
  },
  onError: (e) => print('Error: $e'),
);

Checking SDK status

After calling configure(), you can verify the SDK was enabled (for example, that the API key is valid). isSdkDisabled() returns true when the SDK is disabled.

await AppstackPlugin.configure('your-api-key');
if (await AppstackPlugin.isSdkDisabled()) {
  print('SDK is disabled - check your API key');
}

Setting the customer user ID

The customer user ID is your own identifier for the signed-in user. Appstack attaches it to events so server-to-server events — which identify the user by this ID rather than by the install — can be joined back to the install that produced them.

If you already know the ID at startup, pass it to configure(). More often a login reveals it afterwards, so set it whenever it becomes known:

// On login
await AppstackPlugin.setCustomerUserId('user-123');

// On logout — otherwise the previous user's ID stays attached to later events
await AppstackPlugin.setCustomerUserId(null);

• null (or a blank string) clears the stored ID. Unlike configure(), which never clears, a blank value here is an explicit clear rather than "not provided".
• Callable at any time, before or after configure(), as often as you like — the last call wins.
• Applies to every event sent from here on, including ones the native SDK has buffered but not yet flushed. Events already sent are not backfilled and do not need to be: Appstack maps the ID to the install using any event that carries it.
• The call itself sends nothing. Make sure at least one event follows, or no mapping is ever formed.
• Calling configure() again to change the ID does not work — a repeat configure() is a no-op and its customerUserId is ignored.

Getting the Appstack ID

Retrieve the unique Appstack ID for the current user. Returns null if it is not available yet.

final appstackId = await AppstackPlugin.getAppstackId();
print('Appstack ID: $appstackId');

Environment-based configuration

Set up different API keys for different environments:

// Use environment variables or configuration
final apiKey = Platform.isIOS 
    ? const String.fromEnvironment('APPSTACK_IOS_API_KEY')
    : const String.fromEnvironment('APPSTACK_ANDROID_API_KEY');

await AppstackPlugin.configure(apiKey);

Platform-specific considerations

iOS

Apple Ads attribution:

• Only works on iOS 14.3+
• Requires app installation from App Store or TestFlight
• Attribution data appears within 24-48 hours
• User consent may be required for detailed attribution (iOS 14.5+)

if (Platform.isIOS) {
  await AppstackPlugin.enableAppleAdsAttribution();
}

Android

Play Store Attribution

• Install referrer data collected automatically
• Attribution available immediately for Play Store installs
• Works with Android 5.0+ (API level 21)

Cross-platform best practices

Future<void> initializeSDK() async {
  final apiKey = Platform.isIOS 
      ? 'your-ios-api-key' 
      : 'your-android-api-key';

  await AppstackPlugin.configure(apiKey);

  if (Platform.isIOS) {
    await AppstackPlugin.enableAppleAdsAttribution();
  }
}

Limitations

Attribution timing

• iOS: Apple Ads attribution data appears within 24-48 hours after install
• Android: Install referrer data available immediately for Play Store installs
• Attribution only available for apps installed from official stores

Platform constraints

• iOS: Requires iOS 15.0+
• Android: Minimum API level 21 (Android 5.0)
• Flutter: 3.3.0+
• Some Apple Ads features may not work in development/simulator environments

Event tracking

• Event names are case-sensitive and standardized
• For revenue events, always pass a revenue (or price) and a currency parameter
• The SDK must be initialized before any tracking calls
• enableAppleAdsAttribution() only works on iOS and returns false on Android
• Network connectivity required for event transmission (events are queued offline)

Support

For questions or issues:

1. Check the GitHub Repository
2. Contact our support team at support@appstack.tech
3. Open an issue in the repository