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

• アプリを実行しているAmazonデバイスにメッセージを送信する
• Amazonデバイスにインストールされているアプリにクラウドサービスからメッセージを配信する

​

はじめに

​

セットアップ

1. package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。

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

2. ADMにアクセスするために、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"
   

​

使用方法

• manifest.tomlファイルでコンポーネントとプロセスを宣言します。
• App.tsファイル内のサービスにアプリを登録します。
• タスクの実行を処理するコードを追加します。
• ADMメッセージを登録して処理するコードを追加します。

1. manifest.tomlで、ADMメッセージを受信するヘッドレスタスクを宣言します。コンポーネントIDとして、<packageId>. amazon-device-messaging-receiverを使用します。 重要： <packageId>を特定のパッケージ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"]
   
2. App.tsで、アプリをデバイスメッセージングサービスに登録し、登録IDを受け取ります。
    import {
      AmazonDeviceMessagingMessage,
      AmazonDeviceMessagingServer,
      AmazonDeviceMessagingHandler,
    } from '@amazon-devices/kepler-amazon-device-messaging';
   
    export const App = () => {
    const register = async () => {
        try {
          console.log('registerAsyncの呼び出し');
          const registrationId: string =
            await AmazonDeviceMessagingServer.registerAsync();
          console.log('登録ID：' + registrationId);
        } catch (error) {
          console.error('登録に失敗しました：', error);
        }
      }
    };
   
3. task.jsを作成し、HeadlessTaskを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);
   
4. AdmHeadlessTask.tsファイルを作成します。このファイルの基本構造は次のような形式です。
    class AdmHeadlessTask {
   
      async doTask(): Promise<void> {
        console.log('ヘッドレスタスクを開始しました');
        return Promise.resolve();
      }
    }
   
    const AdmHeadlessTaskInstance = new AdmHeadlessTask();
   
    export const doTask = (): Promise<void> => {
      return AdmHeadlessTaskInstance.doTask();
    };
   
5. AdmHeadlessTask.tsで、ヘッドレスタスクに、ADMメッセージを処理するためのAmazonDeviceMessagingHandlerインターフェイスを実装します。
    import {
        AmazonDeviceMessagingServer,
        AmazonDeviceMessagingHandler,
        AmazonDeviceMessagingMessage,
      } from '@amazon-devices/kepler-amazon-device-messaging';
      .
      .
      .
      const handler: AmazonDeviceMessagingHandler = {
        handleOnMessage(message: AmazonDeviceMessagingMessage): Promise<void> {
          // メッセージを処理します
          console.log(
            'アプリが受信したADMメッセージ = ' + JSON.stringify(message.data),
          );
          console.log(
            'アプリが受信したADM通知 = ' + JSON.stringify(message.notification),
          );
          return Promise.resolve();
        },
      };
   
6. ハンドラーを引数としてAdmHeadlessTaskに渡します。
   class AdmHeadlessTask {
     private handler: AmazonDeviceMessagingHandler;
     constructor(handler: AmazonDeviceMessagingHandler) {
       this.handler = handler;
     }
     .
     .
     .
   }
   
7. AmazonDeviceMessagingServer.registerHandler()を呼び出して、handlerという名前のAmazonDeviceMessagingHandlerの実装を登録します。
    class AdmHeadlessTask {
      .
      .
      .
      async doTask(): Promise<void> {
        console.log('ヘッドレスタスクを開始しました');
        AmazonDeviceMessagingServer.registerHandler(handler);
        return Promise.resolve();
      }
      .
      .
      .
    }
   
8. registerHandlerメソッドを呼び出した後、waitForMessageHandlerCompletionAsyncを呼び出します。
    class AdmHeadlessTask {
      .
      .
      .
      async doTask(): Promise<void> {
        console.log('ヘッドレスタスクを開始しました');
        AmazonDeviceMessagingServer.registerHandler(handler);
        try {
          // メッセージ処理の完了を待機する最大時間を渡します。
          // waitパラメーターは5000ミリ秒先のタイムスタンプであり、この例では
          // 現在の時刻から5000ミリ秒後です。
          await AmazonDeviceMessagingServer.waitForMessageHandlerCompletionAsync(
            new Date(Date.now() + 5 * 1000),
          );
        } catch (error) {
            console.error('エラー：', error);
        }
        return Promise.resolve();
      }
      .
      .
      .
    }
   
9. waitForMessageHandlerCompletionAsyncの完了を待機します。メソッドがエラーをスローしない場合、メッセージは正常に処理されています。メッセージの処理中に問題が発生した場合も、ADMはメッセージの配信を再試行しません。

​

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('ヘッドレスタスクを開始しました');
    AmazonDeviceMessagingServer.registerHandler(handler);
    try {
      // メッセージ処理の完了を待機する最大時間を渡します
      await AmazonDeviceMessagingServer.waitForMessageHandlerCompletionAsync(
        new Date(Date.now() + 5 * 1000),
      );
    } catch (error) {
        console.error('エラー：', error);
    }
    console.log('ヘッドレスタスクを完了しました');
    return Promise.resolve();
  }
}

const handler: AmazonDeviceMessagingHandler = {
  handleOnMessage(message: AmazonDeviceMessagingMessage): Promise<void> {
    console.log(
      'サンプルアプリが受信したメッセージ = ' + 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();
};

​

APIリファレンス

​

クラス

• AmazonDeviceMessagingServer

​

インターフェイス

• AmazonDeviceMessagingDataMessage - カスタムのキーと値のペアで定義されたメッセージです。クライアントアプリ
• AmazonDeviceMessagingHandler - クライアントアプリが処理するために実装するインターフェイス
• AmazonDeviceMessagingMessage - Amazon Device Messagingメッセージです。メッセージには次の内容を含めることができます
• AmazonDeviceMessagingNotificationMessage - クライアントアプリのコンテキストでADMサーバーが使用するメッセージ