Flutter

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

Repository

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

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'},
);

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.Parameters:

apiKey (String, required, positional): Your platform-specific API key from the Appstack dashboard.
logLevel (int, default: 1): Console log verbosity — 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR.
customerUserId (String?, default: null): Your own user identifier, attached to the event payload.

Returns: A future that completes when configuration is done. It throws if configuration fails.Example:

// Minimum configuration — the API key is the only required parameter
await AppstackPlugin.configure('your-api-key-here');

// With optional named parameters
await AppstackPlugin.configure(
  'your-api-key-here',
  logLevel: 0, // DEBUG
  customerUserId: 'user_123',
);

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. That can be before configure runs, at configure time via the customerUserId parameter, or later — most often once a login reveals it:

await AppstackPlugin.setCustomerUserId('user_123');

customerUserId (String, positional): your identifier for the signed-in user. Leading and trailing whitespace is trimmed.
Returns a future that completes once the native SDK has accepted the ID, and throws if the platform call fails.
Safe to call at any time. It applies to every event sent from then on, including ones the native SDK has buffered but not yet flushed.
If you also pass a customerUserId to configure(...), that value wins; passing none leaves the ID you already set in place.
The call does not send anything by itself: make sure at least one event follows, or no mapping is ever formed.
Calling configure(...) again to set the ID does not work — a repeat configure(...) is a no-op and its customerUserId is ignored. Use setCustomerUserId instead.

Sending events

Track user actions and revenue in your activities:

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

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

// 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',
  },
);

Available EventType valuesIt is recommended to use standard events for a smoother experience.

EventType.install is tracked automatically on SDK initialization. Do not send it manually.

EventType.login/ EventType.signUp/ EventType.register Authentication
EventType.purchase/ EventType.addToCart/ EventType.addToWishlist/ EventType.initiateCheckout, EventType.startTrial/ EventType.subscribe Monetization
EventType.levelStart/ EventType.levelComplete Game progression
EventType.tutorialComplete/ EventType.search/ EventType.viewItem/ EventType.viewContent/ EventType.share Engagement
EventType.custom For application-specific events

Tracks custom events with optional parameters:

eventType - Event type from the EventType enum (required).
eventName - Event name for custom events (optional, required when eventType is custom).
parameters - Optional map of parameters (e.g., {'revenue': 29.99, 'currency': 'USD'}).

Returns: A future that resolves to true if event was sent successfully.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, we recommend sending:

revenue or price (number).
currency(string, e.g. EUR, USD).

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

To improve matching quality on Meta, send events including the following parameters if you can fulfill them. Appstack automatically encrypts these matching parameters before using them for attribution matching.

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 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() ?? {};

getAppstackId() — Appstack user identifier when a partner expects $appstackId or similar.
getAttributionParams() — Attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners.

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 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();
  }
}

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 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 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.
Allow 24-48 hours for attribution data to appear.

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.

Superwall

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

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

API reference

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

Superwall

Apple Ads

Verification checklist

Support

​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

​Superwall

​Apple Ads

​Verification checklist

​Support

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

Superwall

Apple Ads

Verification checklist

Support