Flutter

Automated

Prefer to automate this? The Appstack CLI detects your project, installs and configures the SDK, then verifies the result:

npx appstack-cli integrate

Already integrated? npx appstack-cli review audits it without changing any files.

AI-assisted

Use Cursor, Claude Code, or another AI to help you integrate the Flutter SDK.

Open in Cursor

Repository

Here, you will find the pub.dev appstack_plugin documentation. Please use the latest available version of the SDK. Current stable release: 2.10.1, published 22 September 2026. See the changelog for everything that changed.

Quickstart

Use this path when you only need the minimum production integration:

Add appstack_plugin from pub.dev.
Run flutter pub get and cd ios && pod install for iOS projects.
Copy the Production API key from SDK in Appstack.
Call AppstackPlugin.configure(...) from main() before runApp.
Send standard events such as EventType.login, EventType.signUp, EventType.purchase, and EventType.subscribe.
Confirm events appear in the Appstack SDK page before enabling downstream integrations.

import 'package:appstack_plugin/appstack_plugin.dart';
import 'dart:io' show Platform;

final apiKey = Platform.isIOS
    ? 'your-ios-production-api-key'
    : 'your-android-production-api-key';

await AppstackPlugin.configure(apiKey);

await AppstackPlugin.sendEvent(
  EventType.purchase,
  parameters: {'revenue': 29.99, 'currency': 'USD'},
);

Watch the video walkthrough

Claude

Codex

AI agent

Manual

Requirements

iOS

iOS version: 13.0+ (15.0+ required for Apple Ads attribution).
Xcode: 14.0+

Android

Minimum SDK: Android 5.0 (API level 21).
Target SDK: 35+

General

Flutter: 3.3.0+
Dart: 2.18.0+

Initial setup

Installation

From your project root:

flutter pub add appstack_plugin
flutter pub get

Or add appstack_plugin under dependencies in pubspec.yaml using the current version from pub.dev, then run flutter pub get.iOS ConfigurationRun pod install:

cd ios && pod install

Note: The iOS AppstackSDK.xcframework is bundled with the plugin; no additional dependencies are needed.Android ConfigurationAdd the repository to your android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

No additional Android configuration is needed after adding the repository. You still need to initialize the plugin before using SDK methods.

Initialization

Follow these steps to get the API key:

In Appstack, from the side menu, select SDK and ensure you are selecting the correct application.
Select the Production environment.
Copy the API key.

Examples:

import 'package:flutter/material.dart';
import 'package:appstack_plugin/appstack_plugin.dart';
import 'dart:io' show Platform;

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

  // Configure the SDK
  final apiKey = Platform.isIOS
      ? 'your-ios-api-key'
      : 'your-android-api-key';

  await AppstackPlugin.configure(apiKey);

  // Enable Apple Ads attribution on iOS
  if (Platform.isIOS) {
    await AppstackPlugin.enableAppleAdsAttribution();
  }

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  void trackPurchase() {
    AppstackPlugin.sendEvent(
      EventType.purchase,
      parameters: {'revenue': 29.99, 'currency': 'USD'}
    );
  }

  @override
  Widget build(BuildContext context) {
    // ... your app
  }
}

Configuration parameters

Initializes the SDK with your API key. Call this from main() before runApp. configure also takes optional logLevel and customerUserId named parameters; see the Flutter API reference for the full signature and options.

await AppstackPlugin.configure('your-api-key-here');

logLevel accepts only 0 DEBUG, 1 INFO, 2 WARN, or 3 ERROR (default 1); an out-of-range value throws.

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.Set it as soon as it is known — at configure time via the customerUserId parameter, or later, most often once a login reveals it. It applies to every event sent from then on, including ones the native SDK has buffered but not yet flushed, and at least one event has to follow for it to take effect. See setCustomerUserId() in the API reference for the full semantics.

await AppstackPlugin.setCustomerUserId('user_123');

Sending events

Track user actions and revenue in your app:

// Track events without parameters
await AppstackPlugin.sendEvent(EventType.signUp);

// Track events with parameters (including revenue)
await AppstackPlugin.sendEvent(
  EventType.purchase,
  parameters: {'revenue': 29.99, 'currency': 'USD'}
);

// Custom events
await AppstackPlugin.sendEvent(
  EventType.custom,
  eventName: 'user_attributes',
  parameters: {
    'email': 'test@example.com',
    'name': 'John Doe',
    'phone_number': '+33060000000',
    'date_of_birth': '2026-02-01',
  },
);

EventType.install is tracked automatically on SDK initialization. Do not send it manually. See the Flutter API reference for the full signature, parameter details, and the complete list of EventType values.Enhanced app campaigns

When running enhanced app campaigns (EACs), it is highly recommended to send multiple parameters with the in-app event to improve matching quality.

For any event that represents revenue, send revenue or price (number) and currency (string, e.g. EUR, USD). To improve matching quality on Meta, also send these when you can:

email.
name (first + last name in the same field).
phone_number — also accepted as phone or phoneNumber.
date_of_birth (recommended format: YYYY-MM-DD) — also accepted as birthdate, birthday, or dateOfBirth.
gender.

Appstack automatically encrypts these matching parameters before using them for attribution matching.

Appstack ID and attribution params

After configure, you can read the Appstack user ID and the attribution map for partner integrations (for example Superwall, RevenueCat).

final String? appstackId = await AppstackPlugin.getAppstackId();
final Map<String, dynamic> attributionParams =
    await AppstackPlugin.getAttributionParams() ?? {};

getAttributionParams() waits for the attribution match to finish, so you do not need a fixed delay after launch. For the full signatures and return values, see the Flutter API reference. A matched install returns something like:

{
  "appstack_adnetwork": "meta",
  "appstack_campaign": "summer_sale",
  "appstack_adset": "lookalike_1pct",
  "appstack_ad": "video_15s",
  "appstack_id": "9f1c8b64-...",
  "appstack_match_status": "matched"
}

appstack_adnetwork is google, meta or tiktok. It is absent when the click carried no recognised network param — for a standard link, read media_source instead. On Google the campaign, ad set and ad values are numeric IDs rather than names. appstack_id comes back on every result, including organic ones, so read appstack_match_status rather than testing whether the map is empty. For the meaning of each appstack_match_status value and how to read it, see the Flutter API reference.

Check for the key rather than assuming it is there — Android does not report it yet.

Development setup

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 15.0+ (below that the call is a no-op)
Requires app installation from App Store or TestFlight.
Attribution is matched within seconds of the app opening.
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();
  }
}

Security and privacy

Never commit API keys to version control.
Use separate production and development keys.
Do not put personally identifiable information in event names.
Only send matching parameters such as email, name, phone_number, and date_of_birth when your app has the right consent and compliance basis. Appstack automatically encrypts these fields before using them for attribution matching.
Prefer standard event types for common flows so event mapping remains consistent across Appstack and ad integrations.

Limitations

Attribution timing

iOS: Apple Ads attribution is matched within seconds of the app opening 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 13.0+; Apple Ads attribution 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 from main() before runApp and before any tracking calls.
enableAppleAdsAttribution() only works on iOS and returns false on Android.
Network connectivity required for event transmission (events are queued offline).

Troubleshooting

Configuration fails

Confirm the API key was copied from the correct app and environment in Appstack.
Confirm AppstackPlugin.configure(...) runs from main() after WidgetsFlutterBinding.ensureInitialized() and before runApp.
Confirm flutter pub get has completed successfully.
For iOS, confirm cd ios && pod install has completed successfully.

Events do not appear

Confirm configure(...) completes before the first sendEvent(...) call.
Confirm the device has network connectivity.
Check that revenue events include a numeric revenue or price value and a valid currency.
Allow a few minutes for events to appear in the dashboard.

iOS attribution does not appear

Confirm the app was installed from the App Store or TestFlight.
Confirm the device runs iOS 15.0+.
Call AppstackPlugin.enableAppleAdsAttribution() only on iOS after initialization.
Attribution is matched within seconds of the app opening.

Android attribution does not appear

Confirm the app was installed from the Play Store.
Confirm Android min SDK is 21+ and target SDK is 35+.
Confirm the required repositories are available in your Android Gradle configuration.

Apple Ads

To start using the Apple Ads integration, click here to see the correct SDK documentation.

Verification checklist

appstack_plugin is installed from pub.dev.
flutter pub get has completed successfully.
iOS dependencies are installed with cd ios && pod install.
App meets Flutter 3.3.0+, Dart 2.18.0+, iOS 13.0+, Android min SDK 21, and target SDK 35+ requirements.
Platform-specific API keys are configured for iOS and Android.
Production API keys are used in production builds.
Development API keys are used only in development builds.
configure(...) runs once from main() before runApp.
The customer user ID is set — via configure(...) or setCustomerUserId(...) — as soon as it is known, and at least one event follows it.
iOS-only Apple Ads calls are guarded with Platform.isIOS.
EventType.install is not sent manually.
Login, signup, purchase, subscription, and other key app events use standard event types where possible.
Revenue events include revenue or price and currency.
Custom events use EventType.custom with a descriptive eventName.
Appstack ID and attribution params are available before wiring partner integrations.
Events are visible in the Appstack SDK page before launch.

Support

For questions or issues:

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

Use Cursor, Claude Code, or another AI to validate your existing Appstack Flutter plugin integration.

Open in Cursor

Getting started

Mobile SDKs

Integrations

Products

Developer tools

Automated

AI-assisted

Repository

Quickstart

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Platform-specific considerations

iOS

Android

Cross-platform best practices

Security and privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS attribution does not appear

Android attribution does not appear

Apple Ads

Verification checklist

Support

​Automated

​AI-assisted

​Repository

​Quickstart

​Requirements

​iOS

​Android

​General

​Initial setup

​Appstack ID and attribution params

​Development setup

​Environment-based configuration

​Platform-specific considerations

​iOS

​Android

​Cross-platform best practices

​Security and privacy

​Limitations

​Attribution timing

​Platform constraints

​Event tracking

​Troubleshooting

​Configuration fails

​Events do not appear

​iOS attribution does not appear

​Android attribution does not appear

​Apple Ads

​Verification checklist

​Support

Automated

AI-assisted

Repository

Quickstart

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Platform-specific considerations

iOS

Android

Cross-platform best practices

Security and privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS attribution does not appear

Android attribution does not appear

Apple Ads

Verification checklist

Support