KeplerAmazonDeviceMessagingTurboModule

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.

"dependencies": {
  "@amazon-devices/kepler-amazon-device-messaging": "^1.0.0",
  "@amazon-devices/headless-task-manager": "^0.1.0"
}

2. Add following module, privilege and service required to access ADM in manifest.toml.

[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.

Add components to manifest

1. In your manifest.toml, declare a headless task to receive ADM Messages and use <packageId>.amazon-device-messaging-receiver as the component ID. The headless task will be automatically launched in the background so that it can receive and process ADM messages sent to your application.

IMPORTANT: Replace <packageId> with your specific package id

[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"]

Register your App

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

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

export const App = () => {
  const register = async () => {
    try {
      console.log('Calling registerAsync');
      const registrationId =
        await AmazonDeviceMessagingServer.registerAsync();
      console.log('App received registration id: ' + registrationId);
    } catch (error: any) {
      console.error('App failed to register:', error);
    }
  };
};

Create and register a task

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

import { HeadlessEntryPointRegistry } from "@amazon-devices/headless-task-manager";
import { doTask } from "./src/AdmHeadlessTask";

HeadlessEntryPointRegistry.registerHeadlessEntryPoint("<packageId>.amazon-device-messaging-receiver::doTask",
    () => doTask);

Create a headless task to receive ADM Messages.

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

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();
};

Handle ADM messages in your headless task

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

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

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

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

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

8. After calling registerHandler method, call waitForMessageHandlerCompletionAsync.

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.

Sample 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();
};