Flutter Push Notifications

​

Platform Setup

​

iOS

1. In Xcode, enable the Push Notifications capability under your target’s Signing & Capabilities tab.
2. Generate an APNs authentication key (.p8 file) in the Apple Developer Portal.
3. In the AppDNA Console under Settings > Push, in the APNs (iOS) card, paste the contents of the .p8 file into P8 Auth Key, fill in Key ID, Team ID and Bundle ID, pick the Environment, and click Save.

​

Android

1. Set up Firebase Cloud Messaging (FCM) in your Android project.
2. Add the google-services.json file to your android/app/ directory.
3. Upload your Firebase service-account JSON to the AppDNA Console under Settings > Push, in the FCM (Android) card (paste it into Service Account JSON), enter your Firebase Project ID (the project_id in that JSON), and click Save. It must be a service-account key ("type": "service_account", with client_email and private_key); other Google credential types, such as a workload identity federation configuration, are refused.

​

Push Module

final pushModule = AppDNA.push;

​

Request Permission

final granted = await AppDNA.push.requestPermission();

if (granted) {
  print("Push permission granted");
} else {
  print("Push permission denied");
}

​

Set Token Manually

• iOS: pass the APNs token — FirebaseMessaging.instance.getAPNSToken(). It returns null until iOS has registered with APNs (after the permission prompt), so null-check it and retry after requestPermission() resolves and on every app start (onTokenRefresh reports FCM tokens only).
• Android: pass the FCM token — FirebaseMessaging.instance.getToken(), after configure and on every onTokenRefresh.

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

Future<void> registerPushToken() async {
  final messaging = FirebaseMessaging.instance;
  if (Platform.isIOS) {
    final t = await messaging.getAPNSToken();
    if (t != null) {
      await AppDNA.setPushToken(t);
    } // else: not registered with APNs yet — call again after requestPermission() and on next app start
  } else {
    final t = await messaging.getToken();
    if (t != null) {
      await AppDNA.setPushToken(t);
    }
  }
}

// Call after AppDNA.configure(...), after the permission prompt resolves, and on every app start.
// Android only — FCM token refreshes:
FirebaseMessaging.instance.onTokenRefresh.listen((t) {
  if (Platform.isAndroid) AppDNA.setPushToken(t);
});

​

Get Current Token

final token = await AppDNA.push.getToken();
if (token != null) {
  print("Current token: $token");
}

​

Set Permission Status

await AppDNA.push.setPermission(true);

await AppDNA.setPushPermission(true);

​

Track Delivery and Taps

await AppDNA.push.trackDelivered("push-123");

await AppDNA.push.trackTapped("push-123", action: "open_workout");

await AppDNA.trackPushDelivered("push-123");
await AppDNA.trackPushTapped("push-123", action: "open");

​

How push works on iOS

• FlutterFire: getInitialMessage() may also return an AppDNA push that launched the app, depending on install order (with messageId == null and data['appdna'] == '1'). Ignore such messages in your own routing (AppDNA already handled them), or pass them to AppDNA.push.handleTap(message.data) (deduplicated). onMessage / onMessageOpenedApp never fire for AppDNA pushes on iOS.
• Foreground presentation and tracking. When FlutterFire ends up as the outer notification delegate, it keeps deciding how notifications are presented in the foreground — AppDNA pushes included — and AppDNA’s foreground delivered tracking does not run, unless AppDNAForegroundPresentation is set or the delegate AppDNA wrapped implements willPresent. To have AppDNA pushes shown and tracked in the foreground, set the Info.plist key AppDNAForegroundPresentation to an array of banner, list, sound, badge (an empty array = do not present). Trade-off: when AppDNA ends up innermost with no previous delegate, your own FCM pushes then get no foreground presentation — leave the key unset if presenting your own FCM pushes in the foreground matters more.
• Opt out with the Info.plist key AppDNADisableNotificationProxy = YES; AppDNA pushes are then not tracked or routed unless your native iOS code forwards them (see iOS push).
• Delivered tracking on iOS covers foreground delivery only; taps are tracked from any state.

​

Taps on Android

​

If your app already uses Firebase Messaging (Android)

1. Remove the SDK’s service in android/app/src/main/AndroidManifest.xml:
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools">
     <application>
       <service android:name="ai.appdna.sdk.integrations.AppDNAMessagingService" tools:node="remove"/>
     </application>
   </manifest>
   
   or set <bool name="appdna_messaging_service_enabled">false</bool> in android/app/src/main/res/values/bools.xml.
2. Keep firebase_messaging as the only handler.
3. Register the token as shown in Set Token Manually — the FCM token on Android, the APNs token on iOS.
4. Forward messages your handler receives:
   FirebaseMessaging.onMessage.listen((message) async {
     if (await AppDNA.push.isAppDNAMessage(message.data)) {
       await AppDNA.push.handleMessage(message.data);
     }
   });
   
   handleMessage tracks delivery (with its delivery_id) and fires onPushReceived; it never displays anything (on Android it calls the native AppDNA.push.handleMessageData, not the native handleMessage, which posts the notification for any AppDNA message with a title or body). Display is unaffected: AppDNA pushes carry a notification block, which FCM displays while the app is in the background; on Android, in the foreground FCM displays nothing, so showing the message then is up to your app.
5. Forward taps — taps that reach the running app, and the tap that launched it (at configure), are handled by the plugin (Taps on Android). Forwarding them as well is safe: await AppDNAPush.handlePushTap() after configure (it takes no argument; the plugin reads the newest intent — the last one through onNewIntent, else the launch intent — and leaves its extras in place), or:
   FirebaseMessaging.onMessageOpenedApp.listen((message) async {
     await AppDNA.push.handleTap(message.data);
   });
   final initial = await FirebaseMessaging.instance.getInitialMessage();
   if (initial != null) await AppDNA.push.handleTap(initial.data);
   
   Both paths share one dedup, so doing both is safe. Every forwarding call returns false and does nothing for a message without the AppDNA marker, so you can forward every message.

​

AppDNAPushDelegate

• onPushTokenRegistered(token) — fires whenever the SDK registers a new APNs (iOS) or FCM (Android) token (or detects a change). Token registration with the AppDNA backend continues regardless of whether you implement this method.
• onPushReceived(notification, inForeground) — fires when a push arrives. notification is the full payload map; inForeground is true when the app is active.
• onPushTapped(notification, actionId) — fires when the user taps a notification or one of its action buttons. actionId is the identifier of the tapped action button if the user tapped one, otherwise null.

abstract class AppDNAPushDelegate {
  void onPushTokenRegistered(String token);
  void onPushReceived(Map<String, dynamic> notification, bool inForeground);
  void onPushTapped(Map<String, dynamic> notification, String? actionId);
}

​

Example Implementation

class MyPushHandler implements AppDNAPushDelegate {
  @override
  void onPushTokenRegistered(String token) {
    print("Token registered: $token");
  }

  @override
  void onPushReceived(Map<String, dynamic> notification, bool inForeground) {
    if (inForeground) {
      // Show in-app notification banner
      print("Received in foreground: ${notification['title']}");
    }
  }

  @override
  void onPushTapped(Map<String, dynamic> notification, String? actionId) {
    print("Push tapped, action: $actionId");
    // Handle deep link or custom action
  }
}

// Set the delegate before `AppDNA.configure(...)`, so it also hears the tap that launched the app
AppDNA.push.setDelegate(MyPushHandler());

​

AppDNAPush Helper Methods

final granted = await AppDNAPush.requestPermission();
if (granted) {
  await AppDNAPush.registerForPush();
}

​

Notification Payload Shape

@override
void onPushTapped(Map<String, dynamic> notification, String? actionId) {
  final action = notification['action'] as Map<String, dynamic>?;
  final value = action?['value'] as String?;
  if (value != null) {
    // Navigate to the action target
  }
  // A button tap: look the button up by its id.
  final buttons = notification['actions'] as List<Map<String, dynamic>>? ?? const [];
  final tapped = buttons.where((b) => b['id'] == actionId).firstOrNull;
}

​

Auto-Tracked Events

​

Full Example

import 'package:appdna_sdk/appdna_sdk.dart';

class MyPushHandler implements AppDNAPushDelegate {
  @override
  void onPushTokenRegistered(String token) {
    print("Token: $token");
  }

  @override
  void onPushReceived(Map<String, dynamic> notification, bool inForeground) {
    if (inForeground) {
      showInAppBanner(notification);
    }
  }

  @override
  void onPushTapped(Map<String, dynamic> notification, String? actionId) {
    navigateToContent(notification, actionId);
  }
}

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

  // Set up the push delegate first: the tap that launched the app is delivered during configure
  AppDNA.push.setDelegate(MyPushHandler());

  await AppDNA.configure(
    apiKey: "adn_live_xxx",
    env: AppDNAEnvironment.production,
  );

  // Request permission
  final granted = await AppDNA.push.requestPermission();
  print("Push permission: $granted");

  runApp(const MyApp());
}

​

Scheduled pushes in the user’s time zone

1. the timezone trait your app passes to identify (an IANA name such as Europe/Berlin), if you set one — it always takes precedence, and the device’s zone never overwrites it;
2. the zone the user’s device last reported;
3. the app’s time zone;
4. UTC.

await AppDNA.identify("user-123", traits: {"timezone": "Europe/Berlin"}); // the zone the user chose in your app