Topic Based Messaging in A3L

Topic Based Messaging allows you to send messages to groups of users subscribed to the same topic. To use Topic Based Messaging to send messages, your app instance on an Android or Fire OS device must subscribe to a topic. A3L Messaging provides abstractions for the subscribeToTopic() and unsubscribeFromTopic() methods found in the Amazon Device Messaging (ADM) and Firebase Cloud Messaging (FCM) APIs.

Register your security profile
Subscribe or unsubscribe to a topic
Test with server-side scripts
Test with solution-specific APIs

Register your security profile

For Fire OS devices, you must register your security profile for Topic Based Messaging through ADM. For instructions, see Register a security profile for Topic Based Messaging. This step is not required for using Topic Based Messaging in FCM.

To subscribe your app to an ADM or FCM topic, call the A3L Messaging subscribeToTopic() method and pass it the topic name. This method returns a Task that can be used by a completion listener to determine whether the subscription succeeded, as shown in the following code.

A3LMessaging.subscribeToTopic(topic).addOnCompleteListener(
        new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                String msg = "Subscribed";
                if (!task.isSuccessful()) {
                    msg = "Subscribe failed";
                }
                Log.d(TAG, msg);
            }
        }
);

To unsubscribe your app from an ADM or FCM topic, call the A3L Messaging unsubscribeFromTopic() method and pass it the topic name. This method returns a Task that can be used by a completion listener to determine whether unsubscribing was successful, as shown in the following code.

A3LMessaging.unsubscribeFromTopic(topic).addOnCompleteListener(
        new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                String msg = "Unsubscribed";
                if (!task.isSuccessful()) {
                    msg = "Unsubscribe failed";
                }
                Log.d(TAG, msg);
            }
        }
);

Test with server-side scripts

To test Topic Based Messaging, you can use these server-side scripts to send a message to a topic.

ADMSendMessageToTopic.py is a python script that sends a topic-based message to a Fire OS device.
FCMSendMessageToTopic.py is a python script that sends a topic-based message to an Android device.

Click the following buttons to get the code for the scripts. To send a test message, copy the code, paste it into an editor, and update the values indicated in the comments. Then save each as a .py file and run the scripts.

Copied to clipboard.

ADMSendMessageToTopic.py

import requests
import json

# Update these values to send push notification

# Client ID used to send ADM Message
client_id = ""

# Client Secret used to send ADM Message
client_secret = ""

# Topic to which you want to send notification
topic = ""

notification = {"title":"A3L Notification","body":"A3L notification works on Fire OS platform!"}


########### Do not change any code below this line  ##################

Auth_token_URL = "https://api.amazon.com/auth/O2/token"
auth_token_headers = {'Content-Type' : 'application/x-www-form-urlencoded', 'Accept-Charset' : 'application/x-www-form-urlencoded'}
auth_token_data = {'grant_type' : 'client_credentials', 'scope': 'messaging:push', 'client_id': client_id, 'client_secret': client_secret}

send_message_to_topic_url = "https://api.amazon.com/v1/messaging/topic/messages"
send_message_to_topic_headers = {'Accept' : 'application/json', 'Content-Type': 'application/json', 'x-amzn-type-version': 'com.amazon.device.messaging.ADMMessage@1.0', 'x-amzn-accept-type': 'com.amazon.device.messaging.ADMSendResult@1.0'}
a3l_prefix = "a3l.notification."


def transformAndroidNotifcationToA3LNotification(notification):
  a3l_notification = {"data":{}}
  for notification_key, notification_value in notification.items():
    a3l_notification["data"][ a3l_prefix + notification_key] = notification_value
  return a3l_notification


def getAccessToken():
  r = requests.post(Auth_token_URL, data = auth_token_data, headers = auth_token_headers)
  json_response = r.json()
  auth_token = json_response["access_token"]
  return auth_token

def sendMessageToTopic():
  auth_token = "Bearer " + getAccessToken()
  send_message_to_topic_headers['Authorization'] = auth_token
  send_message_data = transformAndroidNotifcationToA3LNotification(notification)
  send_message_data["topic"] = topic
  r = requests.post(send_message_to_topic_url, data = json.dumps(send_message_data), headers = send_message_to_topic_headers)
  print('Successfully sent message:', r.json())

sendMessageToTopic()

Test with solution-specific APIs

You can also test Topic Based Messaging using solution-specific APIs. For detailed instructions on how to send a message to a topic through ADM and FCM APIs, use the following guides.

Last updated: Feb 27, 2023

Topic Based Messaging in A3L

Register your security profile

Subscribe or unsubscribe to a topic

Test with server-side scripts

Test with solution-specific APIs