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

This library enables Amazon Device Messaging Service functionality in React Native for Vega apps. Amazon Device Messaging (ADM) allows you to:

Send messages to Amazon devices that are running your app
Deliver messages from your cloud service to apps installed on Amazon devices

Get started

Setup

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

      "@amazon-devices/kepler-amazon-device-messaging": "~1.0.19",
      "@amazon-devices/headless-task-manager": "~1.2.4",

To access ADM, add the following privilege and services in your 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 must:

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.

In your manifest.toml, declare a headless task to receive ADM messages and use as the component ID. IMPORTANT: Replace 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"]

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: string =
        await AmazonDeviceMessagingServer.registerAsync();
      console.log('Registration id: ' + registrationId);
    } catch (error) {
      console.error('Failed to register:', error);
    }
  }
};

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("com.amazon.device_messaging.sample.amazon-device-messaging-receiver::doTask",
  () => doTask);

Create an AdmHeadlessTask.ts file. The basic structure of the file has 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();
};

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

Pass the handler as an argument to the AdmHeadlessTask.

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

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

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

After calling the 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();
  }
  .
  .
  .
}

Wait for the completion of waitForMessageHandlerCompletionAsync. If the method doesn’t throw an error, it indicates successful handling of the message. If there is a failure when handling the message, ADM doesn’t reattempt the message delivery.

NOTE: The waitForMessageHandlerCompletionAsync method can throw an error when the handler doesn’t process the message within the time specified by waitDuration or it fails to process the message. These errors are reported to the Lifecycle Manager and it is up to your app to handle them.

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

​Get started

​Setup

​Usage

​Example AdmHeadlessTask.ts

​Classes

​Modules

Get started

Setup

Usage

Example AdmHeadlessTask.ts

Classes

Modules