Android Push Notifications

​

Prerequisites

1. Add google-services-appdna.json (or your project’s google-services.json) to your app/src/main/assets/ directory.
2. Apply the com.google.gms.google-services Gradle plugin in your app module.
3. Enable Firebase Cloud Messaging in the Firebase Console.
4. Upload your FCM 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.

​

How the SDK handles messages

​

If your app already uses Firebase Messaging

1. Remove the SDK’s service in your app manifest (with xmlns:tools="http://schemas.android.com/tools" on the <manifest> element):
   <service
       android:name="ai.appdna.sdk.integrations.AppDNAMessagingService"
       tools:node="remove" />
   
   Or disable it with a resource in your own res/values/:
   <resources>
       <bool name="appdna_messaging_service_enabled">false</bool>
   </resources>
   
2. Pass the FCM token after configure and on every token refresh:
   class MyFirebaseMessagingService : FirebaseMessagingService() {
       override fun onNewToken(token: String) {
           super.onNewToken(token)
           AppDNA.setPushToken(token)
       }
   
       override fun onMessageReceived(message: RemoteMessage) {
           super.onMessageReceived(message)
           // Forward AppDNA messages; returns false and does nothing for any other message.
           // handleMessageData never posts a notification — display stays with you.
           if (AppDNA.push.handleMessageData(message.data)) return
           // ... your own handling
       }
   }
   
   AppDNA.push.handleMessageData(data) tracks delivery (with its delivery_id) and fires onPushReceived; it never posts a notification — display stays with you. Server pushes carry a notification block, which FCM displays itself while the app is in the background; in the foreground FCM displays nothing and hands the message to your service, so showing it then is up to you. AppDNA.push.isAppDNAMessage(data) tells you whether a message is AppDNA’s without handling it. If you would rather let the SDK display AppDNA messages, forward the whole message with AppDNA.push.handleMessage(message) instead: it does the same tracking and, for an AppDNA message that has a title or body, posts the notification as the SDK’s own service would. That includes a message with a notification block: your service receives one only while the app is in the foreground, where FCM does not display it (in the background FCM displays it and your service is not called), so it is shown once either way.
3. Taps: call AppDNA.handlePushTap(intent) from your launch activity (onCreate and onNewIntent), or, when you build the notification yourself, AppDNA.push.handleTapData(data, actionId). Both track push_tapped (with delivery_id), fire onPushTapped and route the AppDNA action; they share one dedup, so calling both for one tap is safe. Both return false and do nothing unless the data carries the AppDNA marker. After a tap it handled, handlePushTap(intent) removes the appdna, push_id and delivery_id extras from the intent, so a re-created Activity does not track or route the same tap twice. If your code reads any of those extras, read them before calling handlePushTap. Other extras are left in place.

​

Request Permission

import androidx.lifecycle.lifecycleScope

class MainActivity : androidx.activity.ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lifecycleScope.launch {
            val granted = AppDNA.push.requestPermission(activity = this@MainActivity)
            Log.d("Push", "Permission granted: $granted")
        }
    }
}

​

Set Token Manually

import ai.appdna.sdk.AppDNA
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class MyFirebaseMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        AppDNA.setPushToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
        // Handle message
    }
}

AppDNA.onNewPushToken(token)

​

Set Permission Status

AppDNA.setPushPermission(granted = true)

​

Track Delivery and Taps

AppDNA.trackPushDelivered(pushId = "push-123")

AppDNA.trackPushTapped(pushId = "push-123", action = "open_workout")

​

Push Module

val pushModule = AppDNA.push

​

PushModule Methods

​

AppDNAPushDelegate

• onPushTokenRegistered(token) — fires whenever the SDK registers a new FCM token (or detects a change). Token registration with the AppDNA backend continues regardless of whether you implement this method.
• onPushReceived(notification, inForeground) — fires when an AppDNA push arrives (not for your own FCM messages; use your own handler for those).
• onPushTapped(notification, actionId) — fires when the user taps an AppDNA notification (appdna: "1") or one of its action buttons; not for your own FCM messages.

interface AppDNAPushDelegate {
    fun onPushTokenRegistered(token: String)
    fun onPushReceived(notification: PushPayload, inForeground: Boolean)
    fun onPushTapped(notification: PushPayload, actionId: String?)
}

​

Example Implementation

import ai.appdna.sdk.AppDNAPushDelegate
import ai.appdna.sdk.PushPayload

class MyPushDelegate : AppDNAPushDelegate {

    override fun onPushTokenRegistered(token: String) {
        Log.d("Push", "Token registered: $token")
    }

    override fun onPushReceived(notification: PushPayload, inForeground: Boolean) {
        if (inForeground) {
            // Show in-app notification banner
            showBanner(title = notification.title, body = notification.body)
        }
    }

    override fun onPushTapped(notification: PushPayload, actionId: String?) {
        val action = notification.action
        if (action != null) {
            // Handle deep link or custom action
            handleAction(action)
        }
    }

    private fun showBanner(title: String, body: String) { /* ... */ }
    private fun handleAction(action: Any) { /* ... */ }
}

// Register the delegate
AppDNA.push.setDelegate(MyPushDelegate())

​

Action buttons and custom sound

• Buttons arrive as data.actions, a JSON array of {id, label, action_type, action_value, foreground}. The SDK adds them to every notification it builds itself: every AppDNA push its own service or AppDNA.push.handleMessage displays (a data-only message, or a push with a notification block while the app is in the foreground). A push that FCM displays itself — a notification block while the app is in the background — shows no buttons: Android gives FCM’s own display none.
  • A button that opens the app launches it with action_id and the button’s action_type / action_value extras. AppDNA.handlePushTap(intent) tracks push_tapped with the button’s id as action, fires onPushTapped(notification, actionId) and routes the button’s action. deep_link and open_url (the Console’s URL type) go to your deep-link handler; show_screen opens that screen.
  • dismiss, and any button with Open app in foreground switched off, go to the SDK’s PushActionReceiver and do not open the app, as on iOS. The receiver tracks the tap, fires onPushTapped with the button’s id and routes the button’s action. dismiss routes nowhere. Android does not let a notification button start an activity from the background (Android 10+ background-start and Android 12+ trampoline limits), so a route that needs the app on screen, such as show_screen, takes effect only if the app is already in front; keep Open app in foreground on for a button that must show something. If the app was not running, the receiver waits up to 8 seconds for AppDNA.configure (called from your Application.onCreate) before it handles the tap, so the tap is still tracked.
  • A text_reply button carries a RemoteInput whose hint is the button’s value. The typed text reaches onPushTapped as notification.data["reply_text"].
  • The notification is removed when one of its buttons is tapped: by the receiver for a button that does not open the app, and by AppDNA.handlePushTap(intent) for one that does (Android does not remove it on a button tap by itself).
• Custom sound. The Console value is a file name with its extension. Android plays res/raw/<name>: lower-case, extension dropped, and any character outside a-z, 0-9 and _ replaced by _ (Chime.wav → res/raw/chime). On Android 8+ a notification plays its channel’s sound, so each sound gets its own channel, appdna_sound_<name>. The SDK creates that channel the first time it sees the sound, from any AppDNA message it receives, including one forwarded with handleMessageData. The server names the same channel in android.notification.channel_id (and sound for Android 7 and older). Until the channel exists on a device, FCM falls back to the app’s default channel and its sound. A sound that is not bundled leaves the usual channel and the default sound. A Channel ID set in the campaign is used only for a push without a custom sound (a sound of default is not a custom sound). The server sends it as android.notification.channel_id, which FCM uses when it displays the push, and as channel_id in the message data, which the SDK uses when it displays the push itself. The channel the SDK creates for a sound takes the campaign’s Sound Channel Importance (default high), Name (the sound is appended) and Description, sent as channel_importance, channel_name and channel_description in the message data. The server sends them only with a custom sound; a push without one carries none of them. A channel that already exists on the device keeps its settings. A push without a custom sound that the SDK displays posts on the campaign’s Channel ID, or on the SDK’s default channel, appdna_push, when the campaign sets none. If that channel does not exist on the device yet, the SDK creates it with its own settings: importance high, no description, and the name “Push Notifications” for appdna_push or “Push Notifications (<id>)” for any other channel id (for example “Push Notifications (orders)”). It ignores the push’s channel_importance, channel_name and channel_description there, so a campaign sent at Low or Min importance never changes the channel every later push uses. A channel_group in the message data still puts a channel other than appdna_push in that group (the SDK creates the group if needed); appdna_push joins no group. The campaign’s Android Channel Group sets it: the server sends it as channel_group in the message data together with the campaign’s Channel ID, and only for a push without a custom sound. The SDK looks the sound up by name at runtime, so resource shrinking (shrinkResources true) cannot see that it is used and removes it from a release build. Keep your push sounds with a res/raw/keep.xml in the app:
  <?xml version="1.0" encoding="utf-8"?>
  <resources xmlns:tools="http://schemas.android.com/tools"
      tools:keep="@raw/chime,@raw/notification_chime" />
  
• Image, colour and priority. The campaign’s Media URL and Android Color are sent where FCM’s own display reads them (notification.image, android.notification.color) and also in the message data as image_url and color, where the SDK reads them when it displays the push itself, so a push the SDK builds shows the same image and accent colour.
• Android Priority is FCM’s delivery priority. It is sent as the message’s android.priority (normal or high; high when the campaign leaves it unset), which tells FCM how urgently to deliver the message. When the campaign sets it, it is also sent as data.priority. A push the SDK builds itself is posted with NotificationCompat.PRIORITY_HIGH when data.priority is high, and with PRIORITY_DEFAULT when it is normal or not sent. Android reads that value only on 7.1 and lower. On 8.0 and later the notification channel’s importance decides how the push is shown.
• Media Type. It is sent as data.media_type, only together with a Media URL. When the SDK builds the push itself, a value containing gif decodes the media’s first GIF frame, video or video/… a frame near the start of the video, and image/… the image. Anything else, including image and no value at all, falls back to the URL’s file extension: .gif is a GIF, .mp4, .mov, .webm, .m4v and .3gp are videos, and every other URL is decoded as an image. When FCM displays the push (notification.image), FCM shows the image itself and Media Type is not used.

​

PushPayload

​

PushAction

​

Auto-Tracked Events

​

Full Example

import android.app.Application
import ai.appdna.sdk.AppDNA
import ai.appdna.sdk.Environment

class MyApplication : Application() {

    private val pushHandler = MyPushDelegate()

    override fun onCreate() {
        super.onCreate()
        AppDNA.configure(
            context = applicationContext,
            apiKey = "adn_live_xxx",
            environment = Environment.PRODUCTION,
        )

        AppDNA.push.setDelegate(pushHandler)
    }
}

// In MainActivity.onCreate(...):
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Request POST_NOTIFICATIONS on Android 13+
    lifecycleScope.launch {
        AppDNA.push.requestPermission(activity = this@MainActivity)
    }
}

​

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.

AppDNA.identify(userId = "user-123", traits = mapOf("timezone" to "Europe/Berlin")) // the zone the user chose in your app

​

Next Steps

• Set up Billing to handle in-app purchases
• Configure Onboarding flows
• Present Paywalls with purchase handling
• Learn about Offline Support for event resilience