> ## Documentation Index > Fetch the complete documentation index at: https://docs.appstack.tech/llms.txt > Use this file to discover all available pages before exploring further. # Flutter You are an expert Flutter engineer helping me integrate the Appstack Flutter plugin into my app. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my codebase. Use the reference below to fully wire the plugin. When I paste this prompt and share my Dart and platform files, you should: 1. Provide the exact `pubspec.yaml` changes and `flutter pub` commands required, plus any iOS (`pod install`) and Android (repositories/Gradle) configuration, using the details below. 2. Tell me exactly where to initialize the plugin in my Flutter app and generate idiomatic Dart code to do it, based on the snippets below. 3. Validate my iOS and Android setup (versions, repositories, build settings) against the documentation and highlight anything missing. 4. Summarize the full checklist (install, configure, platform setup, event tracking) so we can confirm that everything from the docs has been applied. *** ## Reference: Appstack Flutter plugin **Requirements** * iOS: 13.0+ (15.0+ required for Apple Ads attribution), Xcode 14.0+ * Android: Min SDK 21, Target SDK 35+ * Flutter: 3.3.0+ * Dart: 2.18.0+ **pubspec.yaml & installation** ```bash theme={null} flutter pub add appstack_plugin flutter pub get ``` (Or add `appstack_plugin` under `dependencies` in `pubspec.yaml` using the **current** version from [pub.dev/packages/appstack\_plugin](https://pub.dev/packages/appstack_plugin).) **iOS configuration** ```bash theme={null} cd ios && pod install ``` * The iOS `AppstackSDK.xcframework` is bundled with the plugin; no extra dependencies required. **Android configuration** ```gradle theme={null} allprojects { repositories { google() mavenCentral() maven { url 'https://jitpack.io' } } } ``` **Quickstart example** ```dart theme={null} 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** ```dart theme={null} await AppstackPlugin.configure('your-api-key-here'); // With optional named parameters await AppstackPlugin.configure( 'your-api-key-here', logLevel: 0, // 0=DEBUG, 1=INFO (default), 2=WARN, 3=ERROR customerUserId: 'user_123', ); ``` **Sending events** ```dart theme={null} // 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', }, ); ``` **EventType values (recommended standard events):** * Authentication: `EventType.login`, `EventType.signUp`, `EventType.register` * Monetization: `EventType.purchase`, `EventType.addToCart`, `EventType.addToWishlist`, `EventType.initiateCheckout`, `EventType.startTrial`, `EventType.subscribe` * Games: `EventType.levelStart`, `EventType.levelComplete` * Engagement: `EventType.tutorialComplete`, `EventType.search`, `EventType.viewItem`, `EventType.viewContent`, `EventType.share` * Custom: `EventType.custom` **Enhanced app campaigns** * For revenue events, send: * `revenue` or `price` (number) * `currency` (e.g. `EUR`, `USD`) * To improve Meta matching, include when possible: * `email` * `name` (first + last name) * `phone_number` (also accepted as `phone` or `phoneNumber`) * `date_of_birth` (`YYYY-MM-DD`; also accepted as `birthdate`, `birthday`, or `dateOfBirth`) * `gender` * Appstack automatically encrypts these matching parameters before using them for attribution matching. ## **Repository** Here, you will find the [pub.dev appstack\_plugin documentation](https://pub.dev/packages/appstack_plugin). Please use the latest available version of the SDK. ## **Quickstart** Use this path when you only need the minimum production integration: 1. Add `appstack_plugin` from pub.dev. 2. Run `flutter pub get` and `cd ios && pod install` for iOS projects. 3. Copy the **Production** API key from **SDK** in Appstack. 4. Call `AppstackPlugin.configure(...)` from `main()` before `runApp`. 5. Send standard events such as `EventType.login`, `EventType.signUp`, `EventType.purchase`, and `EventType.subscribe`. 6. Confirm events appear in the Appstack SDK page before enabling downstream integrations. ```dart theme={null} 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** From your project root: ```text theme={null} flutter pub add appstack_plugin flutter pub get ``` Or add `appstack_plugin` under `dependencies` in `pubspec.yaml` using the **current** version from [pub.dev](https://pub.dev/packages/appstack_plugin), then run `flutter pub get`. **iOS Configuration** Run pod install: ```text theme={null} cd ios && pod install ``` **Note:** The iOS AppstackSDK.xcframework is bundled with the plugin; no additional dependencies are needed. **Android Configuration** Add the repository to your `android/build.gradle`: ```dart theme={null} 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. Follow these steps to get the API key: 1. In Appstack, from the side menu, select **SDK** and ensure you are selecting the correct application. 2. Select the **Production** environment. 3. Copy the **API key**. Examples: ```dart theme={null} 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 } } ``` 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:** ```dart theme={null} // 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', ); ``` Track user actions and revenue in your activities: ```dart theme={null} // 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 values** It 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: 1. `revenue` or `price` (number). 2. `currency`(string, e.g. `EUR`, `USD`). ```dart theme={null} 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. 1. `email`. 2. `name` (first + last name in the same field). 3. `phone_number` — also accepted as `phone` or `phoneNumber`. 4. `date_of_birth` (recommended format: `YYYY-MM-DD`) — also accepted as `birthdate`, `birthday`, or `dateOfBirth`. 5. `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). ```dart theme={null} final String? appstackId = await AppstackPlugin.getAppstackId(); final Map 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: ```dart theme={null} // 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+). ```dart theme={null} 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** ```dart theme={null} Future 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](/Integrations/superwall) to see the correct SDK documentation. ## **Apple Ads** To start using the Apple Ads integration, [click here](/Integrations/apple-ads) 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`. * 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: 1. Check the [GitHub Repository](https://github.com/appstack-tech/appstack-flutter-sdk). 2. Contact our support team at [support@appstack.tech](mailto:support@appstack.tech) 3. Open an issue in the repository. You are an expert Flutter engineer reviewing my existing Appstack Flutter plugin integration. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my Dart and platform-specific code. Your goal is to **validate that my integration fully matches the official Flutter SDK documentation** and identify any missing or incorrect steps. When I paste this prompt and share my project files, you should: 1. **Dependencies & environment** * Inspect my `pubspec.yaml` and lockfile to confirm: * The `appstack_plugin` dependency is present at a **current** version (check pub.dev rather than assuming a fixed constraint). * My environment meets the requirements (Flutter 3.3.0+, Dart 2.18.0+, iOS 13.0+ / 15.0+ for Apple Ads, Android min SDK 21, target SDK 35+). * Suggest exact `flutter pub` commands and any version adjustments needed if something is out of spec. 2. **iOS configuration (Pods)** * Check that: * `cd ios && pod install` has been run and the plugin is integrated. 3. **Android configuration** * Review my Android build files to verify: * Repositories include `google()` and `mavenCentral()` (and `jitpack.io` if required). * Min/target SDK and other settings match the documented requirements. * Note that the plugin should not require extra Android setup beyond repository configuration, but flag any obvious misconfigurations that could break the SDK. 4. **SDK initialization (Dart)** * Locate where I call `AppstackPlugin.configure(...)` and verify: * It is called from `main()` before `runApp` and before any events. * Platform-specific API keys are used correctly (e.g. different keys for iOS and Android via `Platform.isIOS` checks or environment variables). * The optional `logLevel` and `customerUserId` parameters are used appropriately for development vs production when present. * No call still passes the deprecated `isDebug` or `endpointBaseUrl` arguments; both are no-ops in the plugin and should be dropped. * Propose idiomatic Dart initialization code if my current setup is missing, duplicated, or fragile. 5. **Event tracking implementation** * Find all uses of `AppstackPlugin.sendEvent(...)` and verify: * Standard `EventType` values are used where appropriate (e.g. `EventType.purchase`, `EventType.signUp`, `EventType.subscribe`, `EventType.levelComplete`, etc.). * Revenue events send `revenue` (or `price`) and `currency` in the `parameters` map. * Custom events use `EventType.custom` with a descriptive `eventName` and, for EAC / Meta, rich attributes such as `email`, `name`, `phone_number`, and `date_of_birth`, noting that Appstack automatically encrypts these matching parameters before using them for attribution matching. * Highlight missing or inconsistent event usage and suggest concrete `sendEvent` calls that fit my app’s flows. 6. **Platform-specific behavior & limitations** * Validate that my code: * Only calls `enableAppleAdsAttribution()` on iOS (guarded by `Platform.isIOS`). * Respects documented limitations around attribution timing, official store installs, and simulator behavior. * Initializes the SDK from `main()` before `runApp` and does not reconfigure it on every screen unnecessarily. * Flag any code patterns that could conflict with these assumptions. 7. **Validation report & checklist** * Produce a clear summary of: * What is correctly implemented and safe to ship. * What is missing, misconfigured, or risky, with specific Dart and platform file changes.