---
updatedAt: 2026-11-02T16:53:53.000Z
agentTools:
  projectIndex: https://marketing.developer.dotdigital.com/llms.txt
---

# Use the Android App Messaging SDK

A tutorial for adding the Android App Messaging SDK code to your app to allow your app users to receive push notifications from your Dotdigital account

Our Android App Messaging SDK uses <Anchor target="_blank" href="https://firebase.google.com/docs/cloud-messaging/">Firebase Cloud Messaging (FCM)</Anchor> to send push notifications to your Android app users. If you have not configured a Firebase project yet, [follow these instructions](https://marketing.developer.dotdigital.com/docs/creating-a-push-notification-profile-new#enter-your-fcm-credentials-in-dotdigital-marketing) first.

Our Android SDK is open source. You can find it on <Anchor target="_blank" href="https://github.com/comapi/comapi-sdk-android">GitHub</Anchor>.

You can find basic sample apps on <Anchor target="_blank" href="https://github.com/comapi/comapi-sdk-android-samples">GitHub</Anchor>.

To embed the SDK in your native Android app, complete the following tasks:

1. [Install the SDK](#installing-the-sdk)
2. [Prepare the push and challenge handler classes](#prepare-the-push-and-challenge-handler-classes)
3. [Initialise the SDK](#initialising-the-android-sdk)
4. [Handle push message callbacks](#handle-push-message-callbacks)
5. [Handle deep links](#handling-deep-links) and [custom data payloads](#handling-custom-data-payloads)
6. *Optional:* [Change the icon or colour of your push notifications](#changing-the-icon-or-colour-of-push-notifications)
7. [Start a session](#sessions)

This diagram shows the order in which Android and the SDK call each other, and which parts you write:

![Diagram: the Android notification lifecycle in three phases, laid out in two columns. The left column shows what Android or the SDK calls; the right column shows what you write. Phase 1, app launch: Android calls Application.onCreate, and you build a ComapiConfig with apiSpaceId, authenticator, and pushMessageListener. You call Comapi.initialiseShared and hold the client, because you need it in phase 3. Initialisation is asynchronous, and the SDK calls back either success with a ComapiClient or error with a Throwable. On Android 13 and later you request the POST\_NOTIFICATIONS permission, and Android shows the runtime permission dialog. A highlighted trap warns that if you skip the request, Android 13 and later discards every notification with no error. You then call startSession, which branches on session.isSuccessfullyCreated: true means the SDK is ready and the device is registered for push, and false is a soft failure with no session and no exception thrown, which you treat as recoverable. Phase 2, a message arrives, branches on what the app is doing. If the app is in the background, Android renders the system tray notification for you. If the app is in the foreground, the SDK calls onMessageReceived with a RemoteMessage, and you build the notification yourself using NotificationCompat and NotificationChannel. Phase 3, the user taps the notification. Highlighted as not what you expect: Android opens your launcher Activity, not the deep-link target, so routing is yours to do. The intent arrives at either onCreate or onNewIntent, depending on your launchMode. You pass the Intent to client.handlePushNotification. A second trap warns that you must handle both onCreate and onNewIntent, or taps stop being tracked on a warm start. The callback returns a PushHandleResult carrying getUrl, getData, isClickRecorded, and isDeepLinkCalled, and you route within your app, but only if the SDK did not already open the link.](https://files.readme.io/2aeb638e2c5a90db098e4f701051e56cc75921da14c40a656f5902c608ab3f96-android-notification-lifecycle.png "The Android notification lifecycle, and the code you must write")

<br />

<Callout icon="📘" theme="info">
  ### Handling asynchronous requests

  You can use standard callbacks or observable streams to handle asynchronous requests. If you use observable streams, note that the SDK uses **RxJava 1** (`rx.*`), not RxJava 2 or RxJava 3. Make sure that your imports match. This tutorial uses standard callbacks, and shows Kotlin coroutine equivalents where they help.
</Callout>

## Installing the SDK

The setup spans two Gradle files and one JSON file. This diagram shows what goes where:

![Annotated file tree showing where each piece of Android setup belongs. At the project root, MyApp slash, the project-level build.gradle or build.gradle.kts declares the Google Services plugin with apply false: declared here, applied in the module. Inside the app slash module folder, the module-level build.gradle or build.gradle.kts holds the com.comapi:foundation dependency, the Firebase BoM and firebase-messaging, applies the Google Services plugin, and sets Java 11 source and target compatibility. Also in the app module folder sits google-services.json, downloaded from your Firebase project. A warning notes that this fails quietly: google-services.json belongs in the app module folder, not the project root, and without the Google Services plugin applied in the module build file, the build never processes the file at all.](https://files.readme.io/ee5a535c0612be71ed67eef87308be2cd5d9bbf8628868702d26f1152b52424d-android-build-files.png "Where each Android build file and setting belongs")

<br />

1. Add the App Messaging SDK to your **module-level** `build.gradle` (Groovy DSL) or `build.gradle.kts` (Kotlin DSL). The SDK requires Java 11. Set `sourceCompatibility` and `targetCompatibility` to `JavaVersion.VERSION_11`, then add the `com.comapi:foundation` dependency.

```groovy build.gradle (Groovy DSL)
android {
    compileSdk 36

    defaultConfig {
        // ...
        minSdkVersion 21
        targetSdkVersion 36
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

dependencies {
    // ...
    implementation 'com.comapi:foundation:1.8.1'

    // Firebase Cloud Messaging. The SDK exposes RemoteMessage in its public API.
    implementation platform('com.google.firebase:firebase-bom:33.1.0')
    implementation 'com.google.firebase:firebase-messaging'
}
```
```kotlin build.gradle.kts (Kotlin DSL)
android {
    compileSdk = 36

    defaultConfig {
        // ...
        minSdk = 21
        targetSdk = 36
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

dependencies {
    // ...
    implementation("com.comapi:foundation:1.8.1")

    // Firebase Cloud Messaging. The SDK exposes RemoteMessage in its public API.
    implementation(platform("com.google.firebase:firebase-bom:33.1.0"))
    implementation("com.google.firebase:firebase-messaging")
}
```

<Callout icon="📘" theme="info">
  ### About the Firebase BoM

  The <Anchor target="_blank" href="https://firebase.google.com/docs/android/learn-more#bom">Firebase Android BoM</Anchor> (Bill of Materials) keeps all Firebase library versions aligned automatically. Declare one BoM version, then leave the individual Firebase artifacts unversioned. For the current BoM version, see the <Anchor target="_blank" href="https://firebase.google.com/support/release-notes/android">Firebase Android release notes</Anchor>.
</Callout>

<Callout icon="🚧" theme="warn">
  ### Seeing a "Manifest merger" error?

  The most common cause is a `minSdkVersion` in your app that is lower than the SDK supports. Set it to 21 or higher to resolve this. The SDK is built against Java 11, so your module must also use Java 11.
</Callout>

2. Add the Google Services plugin to your **project-level** (top-level) build file with the Plugin DSL. Declare it here with `apply false`, so that you can apply it in any module that needs it.

```groovy project-level build.gradle (Groovy DSL)
plugins {
    id 'com.google.gms.google-services' version '4.4.2' apply false
}
```
```kotlin project-level build.gradle.kts (Kotlin DSL)
plugins {
    id("com.google.gms.google-services") version "4.4.2" apply false
}
```

3. Apply the plugin in your **module-level** build file. This step connects `google-services.json` to the build. If you do not apply the plugin, the build does not process the file.

```groovy module-level build.gradle (Groovy DSL)
plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'
}
```
```kotlin module-level build.gradle.kts (Kotlin DSL)
plugins {
    id("com.android.application")
    id("com.google.gms.google-services")
}
```

4. Copy the `google-services.json` file from your Firebase project into your **app module folder**, which is usually `app/google-services.json`. In a Flutter project, the app module folder is inside the Android folder, so the path is `android/app/google-services.json`. Do not put the file in the project root.

<Callout icon="👍" theme="okay">
  ### Sync Now

  Synchronise your Gradle files after you make any changes. In Android Studio, select **File > Sync Project with Gradle Files**.
</Callout>

## Prepare the push and challenge handler classes

Before you configure the Android SDK, you need:

1. The value of the [API space ID field in Dotdigital Marketing](https://marketing.developer.dotdigital.com/docs/creating-a-push-notification-profile-new#find-your-api-space-id).
2. A class that [creates a JWT](https://marketing.developer.dotdigital.com/docs/creating-a-json-web-token-new#android-jwt-code-sample).
3. A placeholder push handler class that implements the `PushMessageListener` interface. You pass the `PushHandler` class into the SDK init method. This class receives push messages that arrive while the app is visible to the user.

```java PushHandler skeleton (Java)
import android.content.Context;

import com.comapi.internal.push.PushMessageListener;
import com.google.firebase.messaging.RemoteMessage;

public class PushHandler implements PushMessageListener {

    private final Context appContext;

    public PushHandler(Context context) {
        this.appContext = context.getApplicationContext();
    }

    @Override
    public void onMessageReceived(RemoteMessage message) {
        // TODO: Add push message handling, such as displaying messages when the app is
        // in the foreground, and handling deep links and custom data.
    }
}
```
```kotlin PushHandler skeleton (Kotlin)
import android.content.Context

import com.comapi.internal.push.PushMessageListener
import com.google.firebase.messaging.RemoteMessage

class PushHandler(context: Context) : PushMessageListener {

    private val appContext = context.applicationContext

    override fun onMessageReceived(message: RemoteMessage) {
        // TODO: Add push message handling, such as displaying messages when the app is
        // in the foreground, and handling deep links and custom data.
    }
}
```

## Initialising the Android SDK

<Callout icon="🚧" theme="warn">
  ### Where to initialise the Android SDK

  Initialise the SDK in the <Anchor target="_blank" href="https://developer.android.com/reference/android/app/Application#onCreate()">`onCreate()`</Anchor> method of your `Application` subclass. This stops the user's profile changing each time the user opens the app. Remember to register that class in the manifest: `<application android:name=".MyApplication">`.
</Callout>

<Callout icon="📘" theme="info">
  ### Firebase is initialised automatically

  The Firebase Android SDK includes a `ContentProvider` (`com.google.firebase.provider.FirebaseInitProvider`) that runs before your `Application.onCreate()`. `FirebaseApp` is therefore ready before the Comapi SDK initialises. You do **not** need to call `FirebaseApp.initializeApp(context)` yourself, unless you use a non-default `FirebaseOptions` configuration.
</Callout>

1. Create a new instance of the `ComapiConfig` class. Pass your API space ID to `apiSpaceId(...)`, your authentication handler to `authenticator(...)`, and your push handler to `pushMessageListener(...)`:

```java Setting up the config (Java)
import com.comapi.ComapiConfig;

ComapiConfig config = new ComapiConfig()
    // Set the id of the API space this device belongs to.
    .apiSpaceId("<API_SPACE_ID>")
    // Handler for authentication challenges, when the SDK asks for a JWT.
    .authenticator(new ChallengeHandler())
    // Listener for pushes that arrive while the app is in the foreground.
    // Android does not render system-tray notifications in this case.
    .pushMessageListener(new PushHandler(this));
```
```kotlin Setting up the config (Kotlin)
import com.comapi.ComapiConfig

val config = ComapiConfig()
    .apiSpaceId("<API_SPACE_ID>")
    .authenticator(ChallengeHandler())
    .pushMessageListener(PushHandler(this))
```

### Configuring logs and proxy servers

`LogConfig` lets you set the log level for three sinks independently: file (the SDK's internal rolling log), console (Logcat), and network (HTTP request and response logging). The default level for all three is `WARNING`. The available levels are `OFF`, `FATAL`, `ERROR`, `WARNING`, `INFO`, and `DEBUG`.

```java Logging configuration (Java)
import com.comapi.internal.log.LogConfig;
import com.comapi.internal.log.LogLevel;

LogLevel level = BuildConfig.DEBUG ? LogLevel.DEBUG : LogLevel.WARNING;

config.logConfig(
    new LogConfig()
        .setFileLevel(level)
        .setConsoleLevel(level)
        .setNetworkLevel(level)
);
```
```kotlin Logging configuration (Kotlin)
import com.comapi.internal.log.LogConfig
import com.comapi.internal.log.LogLevel

val level = if (BuildConfig.DEBUG) LogLevel.DEBUG else LogLevel.WARNING

config.logConfig(
    LogConfig()
        .setFileLevel(level)
        .setConsoleLevel(level)
        .setNetworkLevel(level)
)
```

<Callout icon="🔒" theme="default">
  ### Privacy note

  Network logs at `DEBUG` and `INFO` level usually include request URLs, headers, and bodies. Never ship a release build at a level above `WARNING`.
</Callout>

Set a custom limit for the internal log file size:

```java Log size limit (Java)
config.logSizeLimitKilobytes(2048);
```
```kotlin Log size limit (Kotlin)
config.logSizeLimitKilobytes(2_048)
```

If your app connects through a proxy server, for example when you debug through Charles or mitmproxy:

```java Proxy (Java)
import com.comapi.APIConfig;

config.apiConfiguration(new APIConfig().proxy("http://10.0.2.2:8888")); // emulator to host
```
```kotlin Proxy (Kotlin)
import com.comapi.APIConfig

config.apiConfiguration(APIConfig().proxy("http://10.0.2.2:8888")) // emulator to host
```

<br />

2. Pass the `ComapiConfig` to one of the initialisation methods:

   * `Comapi.initialiseShared(...)`. The SDK stores the client as a singleton. You access it later with `Comapi.getShared()`.
   * `Comapi.initialise(...)`. This is the non-singleton variant. You store the client yourself, for example in your DI container.

<Callout icon="📦" theme="default">
  ### Using Comapi.getShared() after init

  `Comapi.getShared()` and `RxComapi.getShared()` return the non-null singleton after you call `initialiseShared(...)`. The client is created synchronously inside `initialiseShared(...)`, before the asynchronous network init completes. These methods throw a `RuntimeException` only if you call them before `initialiseShared(...)` has run at all. If you initialise in `Application.onCreate()`, it is safe to call `getShared()` from any Activity, Service, or BroadcastReceiver.
</Callout>

```java Example Application class (Java)
package com.example.testapp;

import android.app.Application;
import com.comapi.Callback;
import com.comapi.Comapi;
import com.comapi.ComapiClient;
import com.comapi.ComapiConfig;

public class MyApplication extends Application implements Callback<ComapiClient> {

    @Override
    public void onCreate() {
        super.onCreate();

        ComapiConfig config = new ComapiConfig()
            .apiSpaceId("<API_SPACE_ID>")
            .authenticator(new ChallengeHandler())
            .pushMessageListener(new PushHandler(this));

        // Initialise the SDK asynchronously. The Application class implements
        // Callback<ComapiClient>, so the success and error methods below are called
        // when init finishes. initialiseShared makes the client available later
        // through Comapi.getShared().
        Comapi.initialiseShared(this, config, this);
    }

    @Override
    public void success(ComapiClient client) {
        // SDK initialised. The client is also available through Comapi.getShared().
    }

    @Override
    public void error(Throwable t) {
        // SDK init failed.
    }
}
```
```kotlin Example Application class (Kotlin)
package com.example.testapp

import android.app.Application
import com.comapi.Callback
import com.comapi.Comapi
import com.comapi.ComapiClient
import com.comapi.ComapiConfig

class MyApplication : Application(), Callback<ComapiClient> {

    override fun onCreate() {
        super.onCreate()

        val config = ComapiConfig()
            .apiSpaceId("<API_SPACE_ID>")
            .authenticator(ChallengeHandler())
            .pushMessageListener(PushHandler(this))

        // Initialise the SDK asynchronously. The Application class implements
        // Callback<ComapiClient>, so the success and error methods below are called
        // when init finishes.
        Comapi.initialiseShared(this, config, this)
    }

    override fun success(client: ComapiClient) {
        // SDK initialised. The client is also available through Comapi.getShared().
    }

    override fun error(t: Throwable) {
        // SDK init failed.
    }
}
```

Register your `Application` subclass in `AndroidManifest.xml`:

```xml AndroidManifest.xml
<application
    android:name=".MyApplication"
    ... >
    ...
</application>
```

3. Request the runtime notification permission on Android 13 and later (API 33). Use the Activity Result API instead of `requestPermissions(...)`. The Activity Result API is the recommended path, and it handles configuration changes correctly.

```java Request POST_NOTIFICATIONS (Java)
public class MainActivity extends AppCompatActivity {

    private final ActivityResultLauncher<String> requestNotificationPermission =
            registerForActivityResult(new ActivityResultContracts.RequestPermission(), granted -> {
                // granted == true means the user accepted the prompt.
            });

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        ensureNotificationPermission();
    }

    private void ensureNotificationPermission() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU
                && ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
                    != PackageManager.PERMISSION_GRANTED) {
            requestNotificationPermission.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}
```
```kotlin Request POST_NOTIFICATIONS (Kotlin)
class MainActivity : AppCompatActivity() {

    private val requestNotificationPermission =
        registerForActivityResult(ActivityResultContracts.RequestPermission()) {
            // granted == true means the user accepted the prompt.
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ensureNotificationPermission()
    }

    private fun ensureNotificationPermission() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
            ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
            != PackageManager.PERMISSION_GRANTED
        ) {
            requestNotificationPermission.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}
```

The SDK manifest already declares `POST_NOTIFICATIONS`, so you do not need to declare it in your own manifest. On Android 13 and later, the user must also grant the permission at runtime. If the user does not grant it, the operating system drops every notification without a warning. This includes the notifications that Android renders automatically while your app is in the background.

<br />

## Handle push message callbacks

Complete the push handler class. Whether a notification appears, and who has to draw it, depends on two things: the kind of payload you send, and what your app is doing when the message lands.

![A two by two matrix. The rows are payload type and the columns are app state. Notification payload with the app in the background: nothing to write, because Android renders it in the system tray; the system owns the display and your app need not be running. Notification payload with the app in the foreground: you write this, because the SDK calls onMessageReceived and nothing appears unless you build the notification. Data-only payload with the app in the background, highlighted as the surprising case: nothing is displayed, because no system notification appears; the message still reaches your code but nothing is shown, so this is the cell people report as push being broken. Data-only payload with the app in the foreground: you write this, because the SDK calls onMessageReceived, which is the same work as with a notification payload except that you build it from the data keys. Two notes follow. First, a data-only payload carries no notification object, so message.getNotification() returns null. Second, Android 8 and later needs a notification channel, and without one Android drops the notification whichever cell you are in.](https://files.readme.io/1e70e284cb987cb7b3e34e1e483a2bfc96955f0572349292816fa0eaa8ba6fed-android-notification-matrix.png "What displays an Android notification, by payload type and app state")

<br />

### Push handler callback

In your push handler class that implements `PushMessageListener`, decide what to do with the push message. Implement this inside `onMessageReceived()`.

### Detecting push messages from Dotdigital Marketing

Your app can receive push messages from more than one provider or system. To detect whether Dotdigital Marketing sent a push message, call `parsePushMessage()`. This call returns a `PushDetails` object. Call `isDdOriginated()` on that object. It returns `true` if Dotdigital Marketing sent the message, and `false` if another system sent it.

### Displaying push notifications when the app is in the foreground

Android renders push notifications automatically only when the app is in the background. These notifications appear in the system tray, and they start your app when the user taps them. To display a push message while your app is in the foreground, you must do it yourself.

The example below does four things:

1. It ignores push messages while no user is signed in.
2. It builds a `NotificationCompat.Builder` notification.
3. It copies the push data to the notification's intent, so that a tap routes through your launcher Activity, records the click, and opens the deep link.
4. It guards the `notify()` call with the `POST_NOTIFICATIONS` permission check for Android 13 and later.

```java Foreground notification (Java)
package com.example.testapp;

import android.Manifest;
import android.app.NotificationChannel;
import android.app.NotificationManager;
import android.app.PendingIntent;
import android.content.Context;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.os.Build;

import androidx.core.app.ActivityCompat;
import androidx.core.app.NotificationCompat;
import androidx.core.app.NotificationManagerCompat;
import androidx.core.app.TaskStackBuilder;

import com.comapi.Comapi;
import com.comapi.ComapiClient;
import com.comapi.internal.push.PushDetails;
import com.comapi.internal.push.PushMessageListener;
import com.google.firebase.messaging.RemoteMessage;

import org.json.JSONException;

import java.util.Map;

public class PushHandler implements PushMessageListener {

    private static final String CHANNEL_ID = "comapi_default_channel";

    private final Context appContext;

    public PushHandler(Context context) {
        this.appContext = context.getApplicationContext();
    }

    @Override
    public void onMessageReceived(RemoteMessage message) {
        // Ignore push messages while no user is signed in.
        try {
            ComapiClient client = Comapi.getShared();
            if (client.getSession() == null || !client.getSession().isSuccessfullyCreated()) {
                return;
            }
        } catch (RuntimeException e) {
            // The SDK is not initialised.
            return;
        }

        PushDetails result;
        try {
            result = ComapiClient.parsePushMessage(message);
        } catch (JSONException e) {
            e.printStackTrace();
            return;
        }

        // Only process push messages from Dotdigital Marketing.
        if (!result.isDdOriginated()) {
            return;
        }

        RemoteMessage.Notification notification = message.getNotification();
        if (notification == null) {
            return; // Silent push. See "Handling silent pushes".
        }

        createNotificationChannel();

        // Unique for each notification, so that multiple pushes do not
        // overwrite each other.
        int notificationId = (int) System.currentTimeMillis();

        // Copy the push data to the intent. When the user taps the notification,
        // handlePushNotification() reads dd_deepLink and dd_data from these extras.
        // Without them, the tap records no click and does not open the deep link.
        Intent resultIntent = new Intent(appContext, MainActivity.class);
        for (Map.Entry<String, String> entry : message.getData().entrySet()) {
            resultIntent.putExtra(entry.getKey(), entry.getValue());
        }

        TaskStackBuilder stackBuilder = TaskStackBuilder.create(appContext);
        stackBuilder.addNextIntentWithParentStack(resultIntent);
        PendingIntent resultPendingIntent = stackBuilder.getPendingIntent(
                notificationId,
                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
        );

        NotificationCompat.Builder builder = new NotificationCompat.Builder(appContext, CHANNEL_ID)
                .setAutoCancel(true)
                .setDefaults(NotificationCompat.DEFAULT_ALL)
                .setWhen(System.currentTimeMillis())
                .setSmallIcon(R.drawable.ic_notification)
                .setContentTitle(notification.getTitle())
                .setContentText(notification.getBody())
                .setContentIntent(resultPendingIntent);

        if (ActivityCompat.checkSelfPermission(appContext, Manifest.permission.POST_NOTIFICATIONS)
                == PackageManager.PERMISSION_GRANTED) {
            NotificationManagerCompat.from(appContext).notify(notificationId, builder.build());
        }
    }

    private void createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            NotificationChannel channel = new NotificationChannel(
                    CHANNEL_ID,
                    "Default",
                    NotificationManager.IMPORTANCE_DEFAULT
            );
            channel.setDescription("Default push notifications");

            NotificationManager manager = appContext.getSystemService(NotificationManager.class);
            if (manager != null) {
                manager.createNotificationChannel(channel);
            }
        }
    }
}
```
```kotlin Foreground notification (Kotlin)
package com.example.testapp

import android.Manifest
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.os.Build
import androidx.core.app.ActivityCompat
import androidx.core.app.NotificationCompat
import androidx.core.app.NotificationManagerCompat
import androidx.core.app.TaskStackBuilder
import com.comapi.Comapi
import com.comapi.ComapiClient
import com.comapi.internal.push.PushMessageListener
import com.google.firebase.messaging.RemoteMessage
import org.json.JSONException

class PushHandler(context: Context) : PushMessageListener {

    private val appContext = context.applicationContext

    override fun onMessageReceived(message: RemoteMessage) {
        // Ignore push messages while no user is signed in.
        val client = try {
            Comapi.getShared()
        } catch (e: RuntimeException) {
            null // The SDK is not initialised.
        }
        if (client?.session?.isSuccessfullyCreated != true) {
            return
        }

        val result = try {
            ComapiClient.parsePushMessage(message)
        } catch (e: JSONException) {
            e.printStackTrace()
            return
        }

        // Only process push messages from Dotdigital Marketing.
        if (!result.isDdOriginated()) {
            return
        }

        // Silent push. See "Handling silent pushes".
        val notification = message.notification ?: return

        createNotificationChannel()

        // Unique for each notification, so that multiple pushes do not
        // overwrite each other.
        val notificationId = System.currentTimeMillis().toInt()

        // Copy the push data to the intent. When the user taps the notification,
        // handlePushNotification() reads dd_deepLink and dd_data from these extras.
        // Without them, the tap records no click and does not open the deep link.
        val resultIntent = Intent(appContext, MainActivity::class.java)
        message.data.forEach { (key, value) -> resultIntent.putExtra(key, value) }

        val stackBuilder = TaskStackBuilder.create(appContext)
        stackBuilder.addNextIntentWithParentStack(resultIntent)
        val resultPendingIntent: PendingIntent? = stackBuilder.getPendingIntent(
            notificationId, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )

        val builder = NotificationCompat.Builder(appContext, CHANNEL_ID)
            .setAutoCancel(true)
            .setDefaults(NotificationCompat.DEFAULT_ALL)
            .setWhen(System.currentTimeMillis())
            .setSmallIcon(R.drawable.ic_notification)
            .setContentTitle(notification.title)
            .setContentText(notification.body)
            .setContentIntent(resultPendingIntent)

        if (ActivityCompat.checkSelfPermission(appContext, Manifest.permission.POST_NOTIFICATIONS)
            == PackageManager.PERMISSION_GRANTED
        ) {
            NotificationManagerCompat.from(appContext).notify(notificationId, builder.build())
        }
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                CHANNEL_ID,
                "Default",
                NotificationManager.IMPORTANCE_DEFAULT
            ).apply { description = "Default push notifications" }

            appContext.getSystemService(NotificationManager::class.java)
                ?.createNotificationChannel(channel)
        }
    }

    companion object {
        private const val CHANNEL_ID = "comapi_default_channel"
    }
}
```

<Callout icon="🚧" theme="warn">
  ### Copy the push data to the notification's intent

  When the user taps a notification that Android displays in the system tray, Android puts the push data on the launcher intent for you. A notification that your app builds itself has no push data unless you add it.

  `handlePushNotification()` reads `dd_deepLink` and `dd_data` from the intent extras. If you do not copy them, a tap on your notification records no click and does not open the deep link.
</Callout>

## Handling deep links

The SDK can handle deep links for you and track their usage. This is the recommended setup.

For platform guidance on deep links in Android apps, see <Anchor target="_blank" href="https://developer.android.com/training/app-links">Android App Links</Anchor> and <Anchor target="_blank" href="https://developer.android.com/training/app-links/deep-linking">Create deep links to app content</Anchor>.

A push message can carry a custom scheme such as `myappscheme://product/123`, or a web address such as `https://example.com/product/123`. Android opens a web address in the browser, unless your app claims that address with an Android App Link. To choose what a message sends, see [Send a deep link or custom data with a push message](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data).

To enable deep-link handling:

1. Declare an intent filter on the Activity that must open when the deep link is invoked. This example uses a deep link in the form `myappscheme://mycustomhost`:

```xml Android Manifest
<activity
    android:name=".MyActivity"
    android:exported="true">
    <intent-filter android:label="Open Activity in Dotdigital Marketing Sample App">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "myappscheme://mycustomhost" -->
        <data
            android:host="mycustomhost"
            android:scheme="myappscheme" />
    </intent-filter>
</activity>
```

2. In your launcher Activity, pass the `Intent` from `onCreate(...)` and `onNewIntent(...)` to `client.handlePushNotification(...)`. When the user taps a system-tray notification, the system puts Dotdigital Marketing extras on the launcher intent. The SDK reads these extras, records the click for analytics, and can also start the deep-link target.

```java MainActivity: handle the launcher intent (Java)
public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        handlePush(getIntent());
    }

    // If you use android:launchMode="singleTop", the system delivers a new intent
    // here instead of recreating the Activity.
    @Override
    protected void onNewIntent(@NonNull Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
        handlePush(intent);
    }

    private void handlePush(@NonNull Intent intent) {
        // Safe to call after Application.onCreate has run Comapi.initialiseShared(...).
        ComapiClient client = Comapi.getShared();
        client.handlePushNotification(this, intent, /* startActivity = */ true,
            new Callback<PushHandleResult>() {
                @Override public void success(PushHandleResult result) {
                    if (result == null) return;
                    String url = result.getUrl();                 // Dotdigital Marketing deep link
                    JSONObject data = result.getData();           // custom data payload
                    boolean clickRecorded = result.isClickRecorded();
                    boolean deepLinkLaunched = result.isDeepLinkCalled();
                    // Route within your app as appropriate.
                }
                @Override public void error(Throwable t) { /* ... */ }
            });
    }
}
```
```kotlin MainActivity: handle the launcher intent (Kotlin)
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handlePush(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handlePush(intent)
    }

    private fun handlePush(intent: Intent) {
        // Safe to call after Application.onCreate has run Comapi.initialiseShared(...).
        val client = Comapi.getShared()
        client.handlePushNotification(this, intent, /* startActivity = */ true,
            object : Callback<PushHandleResult> {
                override fun success(result: PushHandleResult?) {
                    result ?: return
                    val url: String? = result.url                  // Dotdigital Marketing deep link
                    val data: JSONObject? = result.data            // custom data payload
                    val clickRecorded: Boolean = result.isClickRecorded
                    val deepLinkLaunched: Boolean = result.isDeepLinkCalled
                    // Route within your app as appropriate.
                }

                override fun error(t: Throwable) { /* ... */ }
            })
    }
}
```

<Callout icon="📘" theme="info">
  ### What the callback flags mean

  `PushHandleResult.isClickRecorded()` shows that the SDK tracked the click against Dotdigital Marketing analytics.

  `PushHandleResult.isDeepLinkCalled()` shows that the SDK started the deep-link `ACTION_VIEW` intent.

  Either flag can be `false`. `isDeepLinkCalled()` is `false` if the payload contained no deep link, or if no Activity is registered for the scheme and host of the URL.

  `isClickRecorded()` is `false` when the message carries no tracking URL. Dotdigital Marketing adds one only for the deep link and survey tap actions, so a message that sends custom data only records no tap. See [Send a deep link or custom data with a push message](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data).
</Callout>

<Callout icon="📘" theme="info">
  ### If you bridge the SDK to Flutter or React Native

  When a user taps a notification while your app is closed, Android starts your app and delivers the intent to `onCreate()` before your Flutter or React Native code is running. A tap that you pass across your bridge at that moment is lost, because nothing is listening yet.

  Call `handlePushNotification()` in `onCreate()` as usual, so that the SDK records the click. Call it once for each tap. Keep the `PushHandleResult` in your native code, and let your Dart or JavaScript code fetch it when it is ready, for example with a `getInitialNotification()` method on your bridge.

  If your cross-platform code does the routing, pass `false` as the `startActivity` argument, so that the SDK does not also open the deep link.

  For a working example, see our <Anchor target="_blank" href="https://github.com/comapi/comapi-sdk-flutter-sample">Flutter sample app</Anchor>.
</Callout>

### Extracting a deep link without launching it

You may want to extract the deep-link URL yourself instead of letting the SDK start it. To do this, use the static `ComapiClient.parsePushMessage(...)` helper. This method throws a `JSONException` if the payload is malformed.

```java Extracting the deep link URL (Java)
@Override
public void onMessageReceived(RemoteMessage message) {
    try {
        PushDetails details = ComapiClient.parsePushMessage(message);
        Log.i("Comapi", "url = " + details.getUrl());
    } catch (JSONException e) {
        Log.w("Comapi", "Failed to parse push payload", e);
    }
}
```
```kotlin Extracting the deep link URL (Kotlin)
override fun onMessageReceived(message: RemoteMessage) {
    try {
        val details = ComapiClient.parsePushMessage(message)
        Log.i("Comapi", "url = ${details.url}")
    } catch (e: JSONException) {
        Log.w("Comapi", "Failed to parse push payload", e)
    }
}
```

## Handling custom data payloads

`parsePushMessage(...)` also returns the Dotdigital Marketing custom data field. To read it, call `getData()` on the returned `PushDetails` object:

```java Extracting the custom data payload (Java)
@Override
public void onMessageReceived(RemoteMessage message) {
    try {
        PushDetails details = ComapiClient.parsePushMessage(message);
        JSONObject data = details.getData();
        Log.i("Comapi", "data = " + (data != null ? data.toString() : "null"));
    } catch (JSONException e) {
        Log.w("Comapi", "Failed to parse push payload", e);
    }
}
```
```kotlin Extracting the custom data payload (Kotlin)
override fun onMessageReceived(message: RemoteMessage) {
    try {
        val details = ComapiClient.parsePushMessage(message)
        Log.i("Comapi", "data = ${details.data?.toString() ?: "null"}")
    } catch (e: JSONException) {
        Log.w("Comapi", "Failed to parse push payload", e)
    }
}
```

<Callout icon="📘" theme="info">
  ### The values arrive as JSON strings

  An FCM data payload can hold only text values, so Dotdigital Marketing converts the `dd_data` and `dd_deepLink` objects to JSON strings before it sends them.

  `ComapiClient.parsePushMessage()` converts them back for you, and returns `getData()` as a `JSONObject`. If you read `RemoteMessage.getData()` directly instead, you get the raw JSON string and must parse it yourself.
</Callout>

For example, `RemoteMessage.getData()` holds values like these. Each value is a string, including the nested objects and the `dd_originated` flag:

```json Deep link message
{
  "dd_originated": "true",
  "dd_deepLink": "{\"url\":\"myappscheme://product/123\",\"trackingUrl\":\"https://<tracking URL>\"}"
}
```
```json Custom data message
{
  "dd_originated": "true",
  "dd_data": "{\"screen\":\"product-detail\",\"productId\":\"123\"}"
}
```

The map can also hold other keys.

<Callout icon="🚧" theme="warn">
  ### Validate the custom data

  Your app decides what the data means, so treat every value as untrusted input. Check that each key exists and has the type you expect before you use it. A malformed or unexpected payload must not crash your app.

  `parsePushMessage()` throws a `JSONException` when the payload is malformed, so always catch it.
</Callout>

To find out how to send custom data, and what you can put in it, see [Send a deep link or custom data with a push message](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data#send-custom-data).

## Handling silent pushes

A silent push delivers data to your app without notifying the user. Use it to start an action in the background, for example to refresh cached content.

Dotdigital Marketing sends a silent push as a data-only payload, with no `notification` object. Android therefore displays nothing, and `message.getNotification()` returns `null`. The SDK still calls `onMessageReceived`, so your app receives the data and decides what to do with it.

The foreground notification example above returns early when `getNotification()` is `null`. To act on a silent push, read the custom data instead of returning:

```java Handling a silent push (Java)
@Override
public void onMessageReceived(RemoteMessage message) {
    try {
        PushDetails details = ComapiClient.parsePushMessage(message);
        if (!details.isDdOriginated()) {
            return;
        }

        if (message.getNotification() == null) {
            // Silent push. Act on the data without showing a notification.
            JSONObject data = details.getData();
            // Refresh content, update state, or start your own work here.
            return;
        }

        // Notification payload. Build and show the notification.
    } catch (JSONException e) {
        Log.w("Comapi", "Failed to parse push payload", e);
    }
}
```
```kotlin Handling a silent push (Kotlin)
override fun onMessageReceived(message: RemoteMessage) {
    try {
        val details = ComapiClient.parsePushMessage(message)
        if (details?.isDdOriginated() != true) {
            return
        }

        if (message.notification == null) {
            // Silent push. Act on the data without showing a notification.
            val data = details.data
            // Refresh content, update state, or start your own work here.
            return
        }

        // Notification payload. Build and show the notification.
    } catch (e: JSONException) {
        Log.w("Comapi", "Failed to parse push payload", e)
    }
}
```

<Callout icon="🚧" theme="warn">
  ### Android does not guarantee silent push delivery

  Android restricts background work in Doze mode and when the device is idle, so the system may delay a silent push or not deliver it. Manufacturers including Xiaomi, Huawei, Oppo, and Samsung apply further restrictions. Do not rely on a silent push for anything critical.
</Callout>

To find out how to send a silent push, see [Send a silent push message](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data#send-a-silent-push-message).

## Changing the icon or colour of push notifications

The Android SDK uses <Anchor target="_blank" href="https://firebase.google.com/docs/cloud-messaging/">Firebase Cloud Messaging (FCM)</Anchor> to deliver push notifications. Use the Android `<meta-data>` <Anchor target="_blank" href="https://developer.android.com/guide/topics/manifest/meta-data-element">element</Anchor> in your `AndroidManifest.xml` to set the default icon and accent colour. Android uses these defaults when the server payload does not specify an icon or a colour.

```xml AndroidManifest.xml
<!-- Default icon for incoming notification messages, used when the payload
     does not supply one. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@mipmap/ic_launcher_round" />

<!-- Default accent colour for incoming notification messages. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
```

## Sessions

### Starting a session

**The SDK requires an active session to receive push messages and to register push tokens.**

To create a session, you need two things. You need a client that initialised successfully. You also need an identifier for the [`sub` claim](https://marketing.developer.dotdigital.com/docs/creating-a-json-web-token-new#the-role-of-the-sub-claim) of the JWT. This is usually the ID of the signed-in user, or a stable device-scoped GUID for anonymous users.

```java Start session (callback) (Java)
client.service().session().startSession(new Callback<Session>() {
    @Override public void success(Session session) {
        if (session.isSuccessfullyCreated()) {
            // Session is ready for profile session.getProfileId()
        }
    }
    @Override public void error(Throwable t) { /* ... */ }
});
```
```kotlin Start session (callback) (Kotlin)
client.service().session().startSession(object : Callback<Session> {
    override fun success(session: Session) {
        if (session.isSuccessfullyCreated) {
            // Session is ready for profile ${session.profileId}
        }
    }
    override fun error(t: Throwable) { /* ... */ }
})
```
```java Start session (reactive) (Java)
// Obtain the reactive client. Use RxComapi.getShared() if you initialised
// with Comapi.initialiseShared(...).
RxComapiClient rxClient = RxComapi.getShared();

rxClient.service().session().startSession()
    .subscribe(new Observer<Session>() { /* implement */ });
```
```kotlin Start session (reactive) (Kotlin)
// Obtain the reactive client. Use RxComapi.getShared() if you initialised
// with Comapi.initialiseShared(...).
val rxClient = RxComapi.getShared()

rxClient.service().session().startSession()
    .subscribe(object : Observer<Session> { /* implement */ })
```

Treat `isSuccessfullyCreated() == false` as a soft failure. The `success` path can run even when the server returns an incomplete session. Always check this flag before you treat the SDK as authenticated.

### Ending a session

End the current session only when the user signs out, or when you want to change users on the same device. Ending the session removes the push token from Dotdigital Marketing.

Do not also delete the device's FCM token. The token belongs to the device, not to the user, and the SDK registers it against the next user's session when they sign in. For more information, see [Unregistering app users](https://marketing.developer.dotdigital.com/docs/registering-your-app-users-for-push#unregistering-app-users).

```java Stop session (callback) (Java)
client.service().session().endSession(new Callback<ComapiResult<Void>>() {
    @Override
    public void success(ComapiResult<Void> result) {
        // Session ended. The push token is removed from Dotdigital Marketing.
    }

    @Override
    public void error(Throwable t) {
        // Handle error.
    }
});
```
```kotlin Stop session (callback) (Kotlin)
client.service().session().endSession(object : Callback<ComapiResult<Void>> {
    override fun success(result: ComapiResult<Void>?) {
        // Session ended. The push token is removed from Dotdigital Marketing.
    }

    override fun error(t: Throwable) {
        // Handle error.
    }
})
```
```java Stop session (reactive) (Java)
rxClient.service().session().endSession()
    .subscribe(new Observer<ComapiResult<Void>>() {
        @Override
        public void onNext(ComapiResult<Void> result) {
            // Session ended. The push token is removed from Dotdigital Marketing.
        }

        @Override
        public void onCompleted() {}

        @Override
        public void onError(Throwable e) {
            // Handle error.
        }
    });
```
```kotlin Stop session (reactive) (Kotlin)
rxClient.service().session().endSession()
    .subscribe(object : Observer<ComapiResult<Void>> {
        override fun onNext(result: ComapiResult<Void>?) {
            // Session ended. The push token is removed from Dotdigital Marketing.
        }

        override fun onCompleted() {}

        override fun onError(e: Throwable) {
            // Handle error.
        }
    })
```

<br />

<Callout icon="🚧" theme="warn">
  ### Only users that have both an email address and a push token are created in Dotdigital Marketing

  Read the [Register your app users for push](https://marketing.developer.dotdigital.com/docs/registering-your-app-users-for-push) page to understand the requirements for syncing your app users with Dotdigital Marketing. Dotdigital Marketing syncs only the users who have both an email address and a push token. Only these users can receive push messages.
</Callout>

<Callout icon="👍" theme="okay">
  ### Next steps

  Make sure that your app passes an email address to the SDK for the app user. Dotdigital Marketing then creates a contact for that user. To do this, [follow these instructions](https://marketing.developer.dotdigital.com/docs/setting-up-push-notifications#3-pass-app-user-information-to-the-sdk).

  When your app can receive push messages, decide what each message does. See [Send a deep link or custom data with a push message](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data).
</Callout>

# Sibling pages

* [Set up mobile push notifications](https://marketing.developer.dotdigital.com/docs/setting-up-push-notifications.md)
* [Create a push notification profile](https://marketing.developer.dotdigital.com/docs/creating-a-push-notification-profile-new.md)
* [Create a JWT](https://marketing.developer.dotdigital.com/docs/creating-a-json-web-token-new.md)
* [Use the iOS SDK](https://marketing.developer.dotdigital.com/docs/ios-sdk-new.md)
* [Use the JavaScript SDK with cross-platform apps](https://marketing.developer.dotdigital.com/docs/javascript-sdk-new.md)
* [Register your app users for push](https://marketing.developer.dotdigital.com/docs/registering-your-app-users-for-push.md)
* [Sending push deep links and custom data](https://marketing.developer.dotdigital.com/docs/sending-push-deep-links-and-custom-data.md)
* [Push troubleshooting](https://marketing.developer.dotdigital.com/docs/push-troubleshooting.md)

# What’s Next

* [Registering your app users for push](https://marketing.developer.dotdigital.com/docs/registering-your-app-users-for-push.md)