Skip to content
BranchesTags

Repository files navigation

Postback for Flutter

Mobile attribution and event tracking for Flutter apps, backed by the native iOS and Android Postback SDKs. The Dart layer is a thin pass-through to the same engines as our standalone iOS and Android SDKs, so behavior matches across platforms.

Requirements

  • Flutter 3.22 or later
  • Dart 3.3 or later
  • iOS 14.0 or later
  • Android 7.0 (API 24) or later

Install

Add the package to pubspec.yaml:

dependencies:
  postback_flutter: ^2.0.1

Fetch dependencies:

flutter pub get

The Flutter plugin manages the iOS pod and the Android AAR for you. No extra repository setup needed.

Configure

Call configure once in main(), before runApp. It returns a future that resolves after local state is restored; install registration runs in the background:

import 'package:flutter/material.dart';
import 'package:postback_flutter/postback_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Postback.instance.configure(
    const PostbackConfig(apiKey: 'YOUR_API_KEY'),
  );

  runApp(const MyApp());
}

If you prefer the named-argument form for parity with web SDKs:

await Postback.instance.configure(
  'YOUR_API_KEY',
  endpointBaseUrl: 'https://api.postback.sh',
);

Configuration options

Option Type Default What it does
apiKey String required Your Postback app key.
apiUrl String https://api.postback.sh Override for staging or self-hosted environments.
endpointBaseUrl String alias for apiUrl Accepted for compatibility.
enableAppleAdsAttribution bool true iOS only. Fetches Apple AdServices at install time.
customerUserId String? null Your internal user ID. Persists across launches and replays if the first send fails.
autoTrackSessions bool true Fires session_start on configure() and on foreground, debounced to one event per 30 minutes.
autoRefreshAttribution bool true Refreshes attribution from the backend on configure() and on foreground.
isDebug bool false Forces debug-level logging on the native side.
logLevel int 2 0 = debug, 1 = info, 2 = warn, 3 = error.

Track events

import 'package:postback_flutter/postback_flutter.dart';

await Postback.instance.sendEvent(PostbackEventType.login);
await Postback.instance.sendEvent(PostbackEventType.signUp);

await Postback.instance.sendEvent(
  PostbackEventType.purchase,
  params: {
    'revenue': 9.99,
    'currency': 'USD',
  },
);

await Postback.instance.sendEvent(
  PostbackEventType.custom,
  name: 'onboarding_step',
  params: {
    'screen': 'welcome',
    'step': 1,
  },
);

sendEvent resolves to true once the native side has queued the event locally. It resolves to false when a custom event is ignored because its name is missing or invalid. The actual HTTP send happens on the next flush trigger.

Built-in event types

session_start, login, sign_up, register, purchase, subscribe, start_trial, add_payment_info, add_to_cart, add_to_wishlist, initiate_checkout, view_content, view_item, search, share, tutorial_complete, achieve_level, level_start, level_complete, custom.

Revenue events

Pass revenue (or price as an alias) plus currency. Currency is trimmed, must contain exactly three ASCII letters, and is normalized to uppercase. An invalid currency is omitted while the event still sends.

await Postback.instance.sendEvent(
  PostbackEventType.subscribe,
  params: {
    'revenue': 4.99,
    'currency': 'EUR',
    'plan': 'monthly',
  },
);

Custom events

await Postback.instance.sendEvent(
  PostbackEventType.custom,
  name: 'level_skip',
  params: {'level': 12},
);

Custom events require a name containing 1–255 UTF-16 code units after trimming, with no NUL (U+0000) characters. A custom event with a missing or invalid name is ignored. Keep the name stable so your dashboard groups it correctly.

Names on built-in events are optional; an invalid optional name is omitted while the event still sends. Events restored from an older native queue are revalidated on flush: invalid legacy custom events are dropped, while invalid legacy names on built-in events are omitted. Invalid legacy currency fields are also omitted on Android; current cross-platform calls normalize currency before queuing on either platform.

Read attribution

Once an install registers, attribution is cached on the native side. You can read it any time:

final attribution = await Postback.instance.getAttribution();
final postbackId = await Postback.instance.getPostbackId();

AttributionResult.source is one of apple_ads, tracking_link, or organic.

Link RevenueCat or Superwall

For revenue webhooks, set only the postbackId subscriber/user attribute. Do not forward the full getAttributionParams() map to RevenueCat; it contains attribution details such as source and isAttributed for diagnostics and custom integrations.

final postbackId = await Postback.instance.getPostbackId();
if (postbackId != null) {
  await Purchases.setAttributes({'postbackId': postbackId});
}

Manual refresh

If you need the latest server-side resolution, call refreshAttribution():

final updated = await Postback.instance.refreshAttribution();
debugPrint('source = ${updated?.source}');

Privacy on iOS

Postback does not show an ATT prompt. IDFA is used only if the host app already has authorized access; Apple Ads attribution works through AdServices independently. See the Postback Privacy Policy. Host apps remain responsible for their own privacy notices, App Store answers, and permissions.

Google Advertising ID (Android only)

The native Android SDK reads GAID during install registration, off the main thread, honoring Limit Ad Tracking and dropping the all-zero ID. The plugin declares INTERNET, ACCESS_NETWORK_STATE, and com.google.android.gms.permission.AD_ID. If your app cannot collect advertising IDs (children's apps, regional policies), remove the permission in android/app/src/main/AndroidManifest.xml:

<manifest xmlns:tools="http://schemas.android.com/tools" ...>
    <uses-permission
        android:name="com.google.android.gms.permission.AD_ID"
        tools:node="remove" />
</manifest>

What happens behind the scenes

  • configure() resolves after local-state restore. Install registration runs in the background and retries with backoff on transient failures.
  • Events queue locally on native storage and survive app restarts.
  • iOS fails fast on connectivity errors and retries through the SDK queue, so blocked or offline requests surface real errors instead of sitting in an OS connectivity wait.
  • A rejected API key (401 or 403) disables the SDK. Future events drop until clearData() is called.
  • Late identity updates (setCustomerUserId, iOS Apple Ads opt-in) retry automatically on the next configure() or foreground. If the cached install is no longer recognized, the SDK self-heals by re-registering.

Privacy

For Android, include advertising ID collection, device IDs, approximate location/network-derived country, device or other identifiers, app activity, and (if you set customerUserId) user ID in your Play Console Data safety answers.

Don't pass raw PII through params or customerUserId. Both persist to native storage for retry durability. Use hashed or opaque identifiers instead (SHA-256 of an email, RevenueCat or Superwall app_user_id, your internal user UUID).

Local development

await Postback.instance.configure(
  const PostbackConfig(
    apiKey: 'YOUR_DEV_KEY',
    apiUrl: 'http://localhost:3000',
    isDebug: true,
  ),
);

On Android emulator, use http://10.0.2.2:3000 to reach the host machine's localhost.

isDebug: true raises native log level to debug. iOS logs flow into Console.app; Android logs flow into logcat under the Postback tag.

Public API reference

Postback

import 'package:postback_flutter/postback_flutter.dart';
  • Postback.instance.configure(config) initializes the SDK.
  • sendEvent(eventType, {name, params}) enqueues an event.
  • flush() drains the queue immediately.
  • refreshAttribution() fetches the latest attribution from the backend.
  • setCustomerUserId(userId) updates the customer user ID.
  • getAttribution() returns the cached attribution.
  • getAttributionParams() returns a flat attribution/debug payload for custom integrations.
  • getPostbackId() returns the SDK install identifier.
  • enableAppleAdsAttribution() re-enables Apple Ads at runtime on iOS; returns false on Android.
  • sendTestEvent() posts a diagnostic event and resolves to { success, message }. If the backend says the cached install no longer exists, the native SDK re-registers once and retries the test event once; it never loops.
  • isInitialized() reports whether configure() resolved.
  • isSdkDisabled() reports whether a rejected API key disabled the SDK.
  • clearData() wipes local state.
  • destroy() removes native lifecycle observers.

Support

Issues and feature requests on the GitHub repo. Direct support at support@postback.sh.

License

MIT

About

Postback mobile attribution SDK for Flutter apps

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages