Developer Console
Sign In
Sign In
Developer Console

ADM Message Types

Amazon Device Messaging (ADM) offers push notifications (messages) that you can use to display messages about your app on a user's device. Make sure you have integrated your app with ADM before you get started with ADM messages.

Message types

In ADM, a message is a communication between a developer app and a developer server. ADM offers three types of messages, described in the table below.

ADM Message Type Description Example Use Cases
Data message Messages handled by your app and defined by custom key-value pairs. Use a data message when you want to use custom logic to process a message. For example, you can use data messages to send messages to your app's background tasks.
Notification message Messages handled by the ADM SDK and defined by preset key-value pairs. Use notification messages for a message that is automatically displayed to users, such as promotional offers or marketing notifications.
Data and notification message A notification message that also contains a data message payload of custom key-value pairs. Use data and notification messages when you want to automatically display a message that a user can take action on. For example, you can send an message that an item in a user's cart has a promotional offer. When the user engages with the message, they are sent to a page requiring a promotional code. The message about the offer is a notification message, while the second page requiring a promotional code is a data message with custom logic.

See the sections below for details on each message type.

Data message

A data message is an ADM message that you create with custom logic and pass to devices using ADM. You need to configure the logic for these notifications in your app. Here's an example of message payload for a data message:

{
    "data":
    {
        "key1":"value1",
        "key2":"value2"
    },
    "consolidationKey":"Some Key",
    "expiresAfter":86400
}

See Send a Message for more details.

Notification message

ADM notifications are messages that ADM sends to user devices. The ADM SDK handles the messages and sends notifications on your behalf.

To programmatically send notification messages, set the notification key and add the key-value pair of the user-visible message. For example, you can set a notification message such as We have a new offer for you! like this:

{
    "notification":
    {
        "title":"ADM Message Notification",      
        "body":"We have a new offer for you!"
    }
    "expiresAfter":86400
}

Notification messages require the use of pre-defined key-value pairs. The table below lists the key-value pairs supported by ADM notifications.

Field Type Description
title string The notification's title.
body string The notification's body text.
icon string The notification's icon. Sets the notification icon to myicon for drawable resource myicon. If you don't send this key in the request, displays the launcher icon specified in your app manifest.
color string The notification's icon color, expressed in #rrggbb format.
sound string The sound to play when the device receives the notification. Supports "default" or the filename of a sound resource bundled in the app. Sound files must reside in /res/raw/.
tag string Identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification. If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.
click_action string The action associated with a user click on the notification. If specified, an activity with a matching intent filter is launched when a user clicks on the notification.
body_loc_key string The key to the body string in the app's string resources to use to localize the body text to the user's current localization.
body_loc_args[] string Variable string values to be used in place of the format specifiers in body_loc_key to use to localize the body text to the user's current localization.
title_loc_key string The key to the title string in the app's string resources to use to localize the title text to the user's current localization.
title_loc_args[] string Variable string values to be used in place of the format specifiers in title_loc_key to use to localize the title text to the user's current localization.
channel_id string The notification's channel id (new in Android O). The app must create a channel with this channel ID before any notification with this channel ID is received. If you don't send this channel ID in the request, or if the channel ID provided has not yet been created by the app, FCM uses the channel ID specified in the app manifest.
ticker string Sets the "ticker" text, which is sent to accessibility services. Prior to API level 21 (Lollipop), sets the text that is displayed in the status bar when the notification first arrives.
sticky boolean When set to false or unset, the notification is automatically dismissed when the user clicks it in the panel. When set to true, the notification persists even when the user clicks it.
event_time string (Timestamp format) Set the time that the event in the notification occurred. Notifications in the panel are sorted by this time. A point in time is represented using protobuf.Timestamp. A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
local_only boolean Set whether or not this notification is relevant only to the current device. Some notifications can be bridged to other devices for remote display, such as a Wear OS watch. This hint can be set to recommend this notification not be bridged.
notification_priority enum (NotificationPriority) Set the relative priority for this notification. Priority is an indication of how much of the user's attention should be consumed by this notification. Low-priority notifications may be hidden from the user in certain situations, while the user might be interrupted for a higher-priority notification. The effect of setting the same priorities may differ slightly on different platforms. Note this priority differs from AndroidMessagePriority. This priority is processed by the client after the message has been delivered, whereas AndroidMessagePriority is an FCM concept that controls when the message is delivered.
default_sound boolean If set to true, use the Android framework's default sound for the notification. Default values are specified in config.xml.
visibility enum (Visibility) Set the Notification.visibility of the notification.
notification_count integer Sets the number of items this notification represents. May be displayed as a badge count for launchers that support badging. For example, this might be useful if you're using just one notification to represent multiple new messages but you want the count here to represent the number of total new messages. If zero or unspecified, systems that support badging use the default, which is to increment a number displayed on the long-press menu each time a new notification arrives.
image string Contains the URL of an image that is going to be displayed in a notification. If present, it will override google.firebase.fcm.v1.Notification.image.

See Send a Message for more details on defining message payloads.

Data and Notification message

You can also send notification messages that contain key-value pairs from data messages by configuring the notification and data payloads. In this scenario, the ADM SDK handles the notification message, while the data message payload is handled by your app.

Here's an example of message payload with notification and data messages:

{
    "data":
    {
        "key1":"value1",
        "key2":"value2"
    },
    "notification":
    {
        "title":"ADM Message Notification",      
        "body":"We have a new offer for you!"
    }
    "expiresAfter":86400
}

Message behavior

The ADM SDK handles your messages with the onMessage method. The behavior of ADM messages on a device depends on the state of your app (whether the app is in the background or foreground).

Foreground apps receive message payloads for both data and notification messages when they are received by the device. Background apps receive notification payloads in a system tray and deliver the message when a user taps the notification.

The table below describes the behavior of messages based on the state of the app.

App state Notification message Data message Data and notification message
Foreground onMessage onMessage onMessage
Background System tray onMessage Notification message: system tray
Data message: in the extras of the intent

Message priority

For both data and notification messages, there are two priority states: normal and high. Normal is the default priority for both message types.

Normal priority messages are delivered to users immediately when the app is in the foreground. When the device is in doze mode, the delivery of normal messages is delayed until the app is in the foreground.

For high priority messages, ADM attempts to deliver the message immediately, regardless of the state of the user's device. The number of high priority messages an app can receive in a day is limited by the app's standby bucket.

You can set the message priority with the priority parameter. Here's an example of a request for a high priority message:

{
    "data":{"key1":"value1","key2":"value2"},
    "priority":"high"
    "expiresAfter":86400
}

See Send a Message for more details.

Test ADM integration

You can confirm that your app is set up with ADM by sending a test notification to a device. See Send a Message for more information.

Last updated: Jun 08, 2022