appstack_plugin 0.0.4

Track events and revenue with Apple Search Ads attribution for Flutter apps. Supports iOS 14.3+ and Android 5.0+.

Appstack Flutter Plugin

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

Installation

Add to your pubspec.yaml:

dependencies:
  appstack_plugin: ^0.0.4

Then run:

flutter pub get

Platform Configuration

iOS Configuration:

• iOS version 14.3+ recommended to use Apple Search Ads
• The plugin includes the AppstackSDK.xcframework bundled locally

Add to ios/Runner/Info.plist:

<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://ios-appstack.com/</string>

Run pod install in the ios directory:

cd ios && pod install

Note: The iOS AppstackSDK.xcframework is included in the plugin and doesn't require any additional dependencies.

Android Configuration:

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

Add the Appstack SDK repository to your android/build.gradle:

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

No additional configuration needed for Android - the SDK will work automatically after installation.

Quick Start

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 Search Ads attribution on iOS
  if (Platform.isIOS) {
    await AppstackPlugin.enableAppleAdsAttribution();
  }
  
  runApp(MyApp());
}

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

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

API

configure(String apiKey, {bool isDebug, String? endpointBaseUrl, int logLevel}): Future<bool>

Initializes the SDK with your API key. Must be called before any other SDK methods.

Parameters:

• apiKey - Your platform-specific API key from the Appstack dashboard
• isDebug - Enable debug mode (optional, default false)
• endpointBaseUrl - Custom endpoint base URL (optional)
• logLevel - Log level: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR (optional, default 1)

Returns: Future that resolves to true if configuration was successful

Example:

final success = await AppstackPlugin.configure('your-api-key-here');
if (!success) {
  print('SDK configuration failed');
}

// With all parameters
await AppstackPlugin.configure(
  'your-api-key-here',
  isDebug: true,
  logLevel: 0, // DEBUG
);

sendEvent(EventType eventType, {String? eventName, double? revenue}): Future<bool>

Tracks custom events with optional revenue data. Use this for all user actions you want to measure.

Parameters:

• eventType - Event type from the EventType enum (required)
• eventName - Event name for custom events (optional)
• revenue - Optional revenue amount in dollars (e.g., 29.99 for $29.99)

Returns: Future that resolves to true if event was sent successfully

Examples:

import 'package:appstack_plugin/appstack_plugin.dart';

// Using EventType enum (recommended)
await AppstackPlugin.sendEvent(EventType.purchase, revenue: 29.99);
await AppstackPlugin.sendEvent(EventType.signUp);
await AppstackPlugin.sendEvent(EventType.addToCart);

// Custom events with custom names
await AppstackPlugin.sendEvent(
  EventType.custom, 
  eventName: 'my_custom_event', 
  revenue: 15.50
);

Available EventType values:

• install, login, signUp, register
• purchase, addToCart, addToWishlist, initiateCheckout, startTrial, subscribe
• levelStart, levelComplete
• tutorialComplete, search, viewItem, viewContent, share
• custom (for application-specific events)

enableAppleAdsAttribution(): Future<bool> (iOS only)

Enables Apple Search Ads attribution tracking. Call this after configure() on iOS to track App Store install sources.

Returns: Future that resolves to true if attribution was enabled successfully

Requirements:

• iOS 14.3+
• App installed from App Store or TestFlight
• Attribution data appears within 24-48 hours

Example:

import 'dart:io' show Platform;

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

---

Advanced

Security Considerations

Data Privacy:

• Event names and revenue data are transmitted securely over HTTPS
• No personally identifiable information (PII) should be included in event names
• The SDK does not collect device identifiers beyond what's required for attribution

Network Security:

• All API communications use TLS 1.2+ encryption
• Certificate pinning is implemented for additional security
• Requests are authenticated using your API key

Limitations

Attribution Timing:

• Apple Search Ads attribution data appears within 24-48 hours after install
• Attribution is only available for apps installed from App Store or TestFlight
• Attribution requires user consent on iOS 14.5+ (handled automatically)

Platform Constraints:

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

Event Tracking:

• Event names are case-sensitive and standardized
• Revenue values need to be in USD
• SDK must be initialized before any tracking calls
• enableAppleAdsAttribution only works on iOS and will return false on Android
• Network connectivity required for event transmission (events are queued offline)

Documentation

• Complete Usage Guide
• GitHub Repository

License

MIT License - see LICENSE file for details