Android push notifications

Set up Workflows push notifications in the Android SDK. For the concept and channel setup, see Push notifications.

Available in the Android SDK version 3.58.0 and newer. Sends go out through the FCM channel you connect in Workflows > Channels, so the Firebase project on that channel must match your app.

Requirements

Set up Firebase Cloud Messaging and request the POST_NOTIFICATIONS runtime permission from the user (required on Android 13+) so the system can show notifications.

Automatic registration and open tracking (default)

Both behaviors are on by default. When firebase-messaging is on your classpath, the SDK registers this device's FCM token with PostHog, and it auto-captures a $push_notification_opened event when a user opens the app from a notification tray tap.

val config = PostHogAndroidConfig(apiKey = "<ph_project_api_key>").apply {
    capturePushNotificationSubscriptions = true // register the FCM token with PostHog
    capturePushNotificationOpened = true         // capture `$push_notification_opened`
}
PostHogAndroid.setup(context, config)

Initialize the SDK in your Application.onCreate, not an Activity. The SDK installs its open-tracking hook during setup(), so it has to run before the launching Activity is created. If you initialize inside an Activity, a cold-start tap on a notification won't be captured.

Firebase delivers rotated tokens through onNewToken, which the SDK can't observe on its own, so forward it to keep the registered token current:

class MyFirebaseMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        PostHog.registerPushNotificationToken(token, appId = "your-firebase-project-id")
    }
}

Manual registration

// Register a device token (appId = your Firebase project id):
PostHog.registerPushNotificationToken(token, appId = "your-firebase-project-id")

// Unregister when a user signs out:
PostHog.unregisterPushNotificationToken()

Calling PostHog.reset() on logout unregisters the token for the signed-out user and re-registers it under the new anonymous id.

Registration and unregistration are durable. If the device is offline or the request fails, the SDK retries on the next flush(), identity change, or app launch.

Capturing opens

Automatic open capture detects cold-start taps on a notification from the system tray, recognized by the google.message_id extra that Firebase puts on the intent.

Android gives libraries no way to observe Activity.onNewIntent, so a tap that arrives while your app is already running needs one line in your activity:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    PostHogAndroid.capturePushNotificationOpened(intent)
}

Your launcher activity needs android:launchMode="singleTop", or the system resumes the task instead of delivering the tap here. Requires Android SDK 3.62.0 or newer. PostHogAndroid.capturePushNotificationOpened is deduplicated against the automatic path by message ID, so it can't double-count. From Android SDK 3.65.0, PostHog.capturePushNotificationOpened below is deduplicated too: a repeat of a notification PostHog sent, captured in the last 5 minutes, is skipped, so one tap counts once whichever path reports it. Notifications PostHog didn't send are never deduplicated.

Notifications you display yourself from a foreground data message, and push delivered outside FCM, aren't detected at all. Capture those with the fully manual API:

PostHog.capturePushNotificationOpened(
    title = title,
    body = body,
    payload = message.data,
)

The $push_notification_opened event includes $notification_title and $notification_body, plus $notification_action for action-button taps. Android taps captured automatically carry no title or body – Firebase strips the notification content from the intent it hands the app, so there is nothing to read. Title and body are only set when you pass them to PostHog.capturePushNotificationOpened yourself.

Identity verification

If your push channel requires identity verification, supply a backend-minted token through pushIdentityProvider:

config.pushIdentityProvider = { distinctId, appId, completion ->
    // Fetch a freshly-minted token from your backend for this user, then:
    completion(token) // or completion(null) to send without one
}

Troubleshooting