@amazon-devices/kepler-amazon-device-messaging

This library enables Amazon Device Messaging Service functionality in React Native for Kepler apps. Amazon Device Messaging (ADM) lets you send messages to Amazon devices that are running your app and delivering messages from your cloud service to apps installed on Amazon devices.

Get started

Setup

1. Add the following library dependencies to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

      "@amazon-devices/kepler-amazon-device-messaging": "~1.0.0",
      "@amazon-devices/headless-task-manager": "~0.1.0",
   

2. To access ADM, add following privilege and services in your manifest.toml.

   Copy code Copied to clipboard.

    [needs]
   
    [[needs.privilege]]
    id = "com.amazon.device-messaging.privilege.access"
   
    [wants]
   
    [[wants.module]]
    id = "/com.amazon.ace.messaging.service@IDeviceMessaging"
   
    [[wants.service]]
    id = "com.amazon.ace.messaging.service"
   

Usage

To use the Amazon Device Messaging service you need to:

• Declare your components and processes in your manifest.toml file.
• Register your app with the service in your App.ts file.
• Add code to handle task execution.
• Add code to register and handle the ADM messages.

1. In your manifest.toml, declare a headless task to receive ADM Messages and use <packageId>. amazon-device-messaging-receiver as the component ID.

   IMPORTANT: Replace <packageId> with your specific package id.

   Copy code Copied to clipboard.

    [components]
   
    [[components.task]]
      id = "<packageId>.amazon-device-messaging-receiver"
      runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
   
    [processes]
   
    [[processes.group]]
    component-ids = ["<packageId>.amazon-device-messaging-receiver"]
   

2. In your App.ts, register your app with the Device Messaging service and receive a registration ID.

   Copy code Copied to clipboard.

    import {
      AmazonDeviceMessagingMessage,
      AmazonDeviceMessagingServer,
      AmazonDeviceMessagingHandler,
    } from '@amazon-devices/kepler-amazon-device-messaging';
   
    export const App = () => {
    const register = async () => {
        try {
          console.log('Calling registerAsync');
          const registrationId: string =
            await AmazonDeviceMessagingServer.registerAsync();
          console.log('Registration id: ' + registrationId);
        } catch (error) {
          console.error('Failed to register:', error);
        }
      }
    };
   

3. Create a task.js and register the HeadlessTask with HeadlessEntryPointRegistry.

   Copy code Copied to clipboard.

    import { HeadlessEntryPointRegistry } from "@amazon-devices/headless-task-manager";
   
    import { doTask } from "./src/AdmHeadlessTask";
   
    HeadlessEntryPointRegistry.registerHeadlessEntryPoint("com.amazon.device_messaging.sample.amazon-device-messaging-receiver::doTask",
      () => doTask);
   

4. Create AdmHeadlessTask.ts file. The basic structure of the file will have the following format.

   Copy code Copied to clipboard.

    class AdmHeadlessTask {
   
      async doTask(): Promise<void> {
        console.log('Headless Task Started');
        return Promise.resolve();
      }
    }
   
    const AdmHeadlessTaskInstance = new AdmHeadlessTask();
   
    export const doTask = (): Promise<void> => {
      return AdmHeadlessTaskInstance.doTask();
    };
   

5. In AdmHeadlessTask.ts, implement the AmazonDeviceMessagingHandler interface in your headless task to handle ADM Messages.

   Copy code Copied to clipboard.

    import {
        AmazonDeviceMessagingServer,
        AmazonDeviceMessagingHandler,
        AmazonDeviceMessagingMessage,
      } from '@amazon-devices/kepler-amazon-device-messaging';
      .
      .
      .
      const handler: AmazonDeviceMessagingHandler = {
        handleOnMessage(message: AmazonDeviceMessagingMessage): Promise<void> {
          // Handle the message
          console.log(
            'App received ADM Message = ' + JSON.stringify(message.data),
          );
          console.log(
            'App received ADM Notification = ' + JSON.stringify(message.notification),
          );
          return Promise.resolve();
        },
      };
   

6. Pass the handler as an argument to the AdmHeadlessTask.

   Copy code Copied to clipboard.

    class AdmHeadlessTask {
      private handler: AmazonDeviceMessagingHandler;
      constructor(handler: AmazonDeviceMessagingHandler) {
        this.handler = handler;
      }
      .
      .
      .
    }
   

7. Call AmazonDeviceMessagingServer.registerHandler() to register the implementation of AmazonDeviceMessagingHandler implementation which we named handler.

   Copy code Copied to clipboard.

    class AdmHeadlessTask {
      .
      .
      .
      async doTask(): Promise<void> {
        console.log('Headless Task Started');
        AmazonDeviceMessagingServer.registerHandler(handler);
        return Promise.resolve();
      }
      .
      .
      .
    }
   

8. After calling the registerHandler method, call waitForMessageHandlerCompletionAsync.

   Copy code Copied to clipboard.

    class AdmHeadlessTask {
      .
      .
      .
      async doTask(): Promise<void> {
        console.log('Headless Task Started');
        AmazonDeviceMessagingServer.registerHandler(handler);
        try {
          // Pass in maximum amount of duration to wait for Message handling to complete.
          // The wait parameter is a timestamp in the future, 5000 milliseconds after 
          // current time in this example.
          await AmazonDeviceMessagingServer.waitForMessageHandlerCompletionAsync(
            new Date(Date.now() + 5 * 1000),
          );
        } catch (error) {
            console.error('Error:', error);
        }
        return Promise.resolve();
      }
      .
      .
      .
    }
   

9. Wait for the completion of waitForMessageHandlerCompletionAsync. If the method doesn't throw an error, it indicates successful handling of message. In case of failure while handling the message, ADM doesn't re-attempt the message delivery.

NOTE: waitForMessageHandlerCompletionAsync can throw an error when the handler doesn't process the message within waitDuration or fails to process message. It is up to your app to handle failures that are reported to the Lifecyle Manager.

Example AdmHeadlessTask.ts

import {
  AmazonDeviceMessagingMessage,
  AmazonDeviceMessagingServer,
  AmazonDeviceMessagingHandler,
} from '@amazon-devices/kepler-amazon-device-messaging';

class AdmHeadlessTask {
  private handler: AmazonDeviceMessagingHandler;
  constructor(handler: AmazonDeviceMessagingHandler) {
    this.handler = handler;
  }

  async doTask(): Promise<void> {
    console.log('Headless Task Started');
    AmazonDeviceMessagingServer.registerHandler(handler);
    try {
      // Pass in maximum amount of duration to wait for Message handling to complete
      await AmazonDeviceMessagingServer.waitForMessageHandlerCompletionAsync(
        new Date(Date.now() + 5 * 1000),
      );
    } catch (error) {
        console.error('Error:', error);
    }
    console.log('Headless Task completed');
    return Promise.resolve();
  }
}

const handler: AmazonDeviceMessagingHandler = {
  handleOnMessage(message: AmazonDeviceMessagingMessage): Promise<void> {
    console.log(
      'Sample APP received Message = ' + JSON.stringify(message.data),
    );
    console.log(
      'Sample APP received Notification = ' +
        JSON.stringify(message.notification),
    );
    return Promise.resolve();
  }
};

const admHeadlessTaskInstance = new AdmHeadlessTask(handler);

export const doTask = (): Promise<void> => {
  return admHeadlessTaskInstance.doTask();
};

Classes

• AmazonDeviceMessagingServer

Interfaces

• AmazonDeviceMessagingDataMessage
• AmazonDeviceMessagingHandler
• AmazonDeviceMessagingMessage
• AmazonDeviceMessagingNotificationMessage

Last updated: Sep 30, 2025