登録とメッセージの処理

ヒント： A3L Messaging SDKの統合方法の詳細については、A3L Messaging SDKの統合を参照してください。

このページでは、アプリをAmazon Device Messaging（ADM）に登録し、受信メッセージを処理する方法について説明します。

登録IDの取得
登録とメッセージの処理の実装
ADMを使用できない場合の適切な機能制限
サーバー側の統合
次のステップ

登録IDの取得

メッセージを受信する前に、アプリで登録IDを取得する必要があります。ADMの登録IDは、Firebaseのデバイス登録トークンと似ています。これは、特定デバイスへのアプリのインストールを一意に識別するものです。Firebaseでは、FirebaseMessaging.getInstance().getToken()を呼び出すことでデバイス登録トークンを取得できます。ADMにも、getRegistrationId()という同様のメソッドがあります。

次のコードは、com.amazon.device.messaging.ADMクラス内のメソッドを使用して以下の操作を実行する方法を示しています。

ADMコンテキストのインスタンスを作成する
現在のアプリインスタンス用にADMへの登録を開始する

final ADM adm = new ADM(this);
if (adm.getRegistrationId() == null)
{
   // startRegister()は非同期です。アプリへの通知は、登録IDが利用できるようになると、
   // onRegistered()コールバックで行われます。
   adm.startRegister();
}

このコードをonCreate()メソッドに配置して、アプリを起動するたびに実行します。アプリが登録済みであれば、getRegistrationId()によって現在のアプリインスタンスの登録IDが返され、startRegister()は呼び出されません。デバイスでアプリを初めて起動する場合や、以前の登録が失敗した場合は、このコードによって登録プロセスが開始されます。

注：登録IDの長さは最大1,536文字です。

登録とメッセージの処理の実装

ADMには、拡張が必要な3つのクラスがあります。それぞれの機能については、次の表を参照してください。また、ADM APIリファレンスも確認してください。

クラス	説明
`com.amazon.device.messaging.ADMMessageHandlerJobBase`	最新バージョンのFireデバイスでメッセージを処理するためのクラス
`com.amazon.device.messaging.ADMMessageHandlerBase`	旧バージョンのFireデバイスでメッセージを処理するためのクラス
`com.amazon.device.messaging.ADMMessageReceiver`	適切なメッセージ処理クラスにメッセージを転送するためのクラス

マニフェストで宣言されたブロードキャストレシーバーは、インテントをリッスンし、インテント受信時にアプリを起動します。アプリは、com.amazon.device.messaging.ADMMessageHandlerJobBaseクラスおよびcom.amazon.device.messaging.ADMMessageHandlerBaseクラスで定義された以下のコールバックメソッドを介して、ブロードキャストレシーバーとやり取りします。

コールバックメソッド	説明
`onRegistered`	アプリインスタンスの登録IDが利用可能になると呼び出されます。アプリ側は、この登録IDを開発者サーバーに送信する必要があり、そうすることで、開発者サーバーがアプリインスタンスにメッセージを送信できるようになります。
`onUnregistered`	アプリインスタンスがADMから登録解除された場合に呼び出されます。
`onRegistrationError`	アプリのADM登録リクエストが何らかの理由（デバイスにサインインしているAmazonユーザーがいないなど）で失敗した場合に呼び出されます。
`onMessage`	ADMクライアントがアプリインスタンスにメッセージを配信する際に呼び出されます。これはFCMの`onMessageReceived`コールバックと似ていますが、`RemoteMessage`オブジェクトではなく`Intent`オブジェクトを渡し、このオブジェクトからメッセージコンテンツを抽出します。

com.amazon.device.messaging.ADMMessageHandlerJobBase、com.amazon.device.messaging.ADMMessageHandlerBase、com.amazon.device.messaging.ADMMessageReceiverのサブクラスを実装する場合は、アプリ側でこれらのコールバックをオーバーライドする必要があります。以下のコード例を参照してください。

現在のデバイスが新しいADMサービスをサポートできるようにアップデートされているかどうかを確認します。

 ADMLatestAvailable = false ;
 try{
     Class.forName( "com.amazon.device.messaging.ADMMessageHandlerJobBase" );
     ADMLatestAvailable = true ;
 }
 catch (ClassNotFoundException e)
 {
     // 例外を処理します。
 }

レシーバーとサービスの実装を作成します。

 public class Receiver extends ADMMessageReceiver
 {   
     public Receiver()
     {   // これは下位互換性を維持するために必要です
        super(MyADMLegacyMessageHandler.class);
        // 使用できる場合は、新しいジョブベースを使用します
        if (ADMLatestAvailable) {
            registerJobServiceClass(MyADMMessageHandler.class, <JOB_ID>)
        }
     }
     // 新たな操作は不要です。ブロードキャストレシーバーからサービスに対して
     // 処理対象のインテントが自動的に送信されます。
 }

 public class MyADMMessageHandler extends ADMMessageHandlerJobBase
 {

     @Override
     protected void onRegistered(final Context context, final String newRegistrationId)
     {
         // メインアクティビティでstartRegister()を呼び出して登録プロセスを
         // 開始します。登録IDが利用可能になると、ADMはアプリのonRegistered()を
         // 呼び出します。開発者サーバーが現在のアプリインスタンスにメッセージを送信できるように、
         // 渡された登録IDを開発者サーバーに送信します。onRegistered()は、何らかの理由で
         // 登録IDのローテーションまたは変更が行われた場合にも呼び出されます。
         // その場合、アプリ側は新しい登録IDを開発者サーバーに渡す必要があります。
         // 開発者サーバーは、最大1,536文字の登録IDを処理できる
         // 必要があります。

         // ヘッダーのキーと値のペアを使用してHTTPで登録IDを
         // 開発者サーバーに送信する例は次のとおりです。
         URL url = new URL(YOUR_WEBSERVER_URL);
         HttpURLConnection con = (HttpURLConnection) url.openConnection();
         con.setDoInput(true);
         con.setUseCaches(false);
         con.setRequestMethod("POST");
         con.setRequestProperty("RegistrationId", newRegistrationId);
         con.getResponse();
     }

     @Override
     protected void onUnregistered(final Context context, final String registrationId)
     {
         // このデバイスでアプリが登録解除されている場合は、現在のアプリインスタンスが
         // メッセージの有効なターゲットではなくなっていることを、開発者サーバーに通知します。
     }

     @Override
     protected void onRegistrationError(final Context context, final String errorId)
     {
         // 登録エラーは致命的であるとみなす必要があります。その対応として、
         // アプリの機能を適切に制限するか、アプリの機能のうちこの部分が使用できないことを
         // ユーザーに通知することができます。
     }

     @Override
     protected void onMessage(final Context context, final Intent intent)
     {
         // com.amazon.device.messaging.intent.RECEIVEインテントに
         // アタッチされているエクストラからメッセージコンテンツを抽出します。

         // JSONデータのメッセージフィールドとタイムスタンプフィールドにアクセスするための文字列を作成します。
         final String msgKey = getString(R.string.json_data_msg_key);
         final String timeKey = getString(R.string.json_data_time_key);

         // onMessage()コールバックでトリガーされるインテントアクションを取得します。
         final String intentAction = getString(R.string.intent_msg_action);

         // インテントに含まれていたエクストラを取得します。
         final Bundle extras = intent.getExtras();

         // インテント内のエクストラからメッセージと時刻を抽出します。
         // メッセージの配信や順序は保証されません。
         // ネットワーク状況の変化により、メッセージが複数回配信される場合もあります。
         // アプリ側でメッセージの重複インスタンスを処理できるようにしておく必要があります。
         final String msg = extras.getString(msgKey);
         final String time = extras.getString(timeKey);
     }
 }

public class MyADMLegacyMessageHandler extends ADMMessageHandlerBase
{

    @Override
    protected void onRegistered(final String newRegistrationId)
    {
        // メインアクティビティでstartRegister()を呼び出して登録プロセスを
        // 開始します。登録IDが利用可能になると、ADMはアプリのonRegistered()を
        // 呼び出します。開発者サーバーが現在のアプリインスタンスにメッセージを送信できるように、
        // 渡された登録IDを開発者サーバーに送信します。onRegistered()は、何らかの理由で
        // 登録IDのローテーションまたは変更が行われた場合にも呼び出されます。
        // その場合、アプリ側は新しい登録IDを開発者サーバーに渡す必要があります。
        // 開発者サーバーは、最大1,536文字の登録IDを処理できる
        // 必要があります。

        // ヘッダーのキーと値のペアを使用してHTTPで登録IDを
        // 開発者サーバーに送信する例は次のとおりです。
        URL url = new URL(YOUR_WEBSERVER_URL);
        HttpURLConnection con = (HttpURLConnection) url.openConnection();
        con.setDoInput(true);
        con.setUseCaches(false);
        con.setRequestMethod("POST");
        con.setRequestProperty("RegistrationId", newRegistrationId);
        con.getResponse();
    }

    @Override
    protected void onUnregistered(final String registrationId)
    {
        // このデバイスでアプリが登録解除されている場合は、現在のアプリインスタンスが
        // メッセージの有効なターゲットではなくなっていることを、開発者サーバーに通知します。
    }

    @Override
    protected void onRegistrationError(final String errorId)
    {
        // 登録エラーは致命的であるとみなす必要があります。その対応として、
        // アプリの機能を適切に制限するか、アプリの機能のうちこの部分が使用できないことを
        // ユーザーに通知することができます。
    }

    @Override
    protected void onMessage(final Intent intent)
    {
        // com.amazon.device.messaging.intent.RECEIVEインテントに
        // アタッチされているエクストラからメッセージコンテンツを抽出します。

        // JSONデータのメッセージフィールドとタイムスタンプフィールドにアクセスするための文字列を作成します。
        final String msgKey = getString(R.string.json_data_msg_key);
        final String timeKey = getString(R.string.json_data_time_key);

        // onMessage()コールバックでトリガーされるインテントアクションを取得します。
        final String intentAction = getString(R.string.intent_msg_action);

        // インテントに含まれていたエクストラを取得します。
        final Bundle extras = intent.getExtras();

        // インテント内のエクストラからメッセージと時刻を抽出します。
        // メッセージの配信や順序は保証されません。
        // ネットワーク状況の変化により、メッセージが複数回配信される場合もあります。
        // アプリ側でメッセージの重複インスタンスを処理できるようにしておく必要があります。
        final String msg = extras.getString(msgKey);
        final String time = extras.getString(timeKey);
    }
}

ADMを使用できない場合の適切な機能制限

マニフェストファイルでは、ADMを使用できない場合にアプリが動作する（android:required="false"）か、動作しない（android:required="true"）かを宣言します。ここでandroid:required="false"を指定した場合、ADMが利用できないときにアプリの機能が適切に制限されるようにする必要があります。

ADMがなくても動作するアプリを設計すれば、単一のAPKを構築するだけで、ADMのありなしにかかわらずデバイスにインストールして実行することができます。

適切な機能制限が行われるようにアプリを修正するには、次の手順に従います。

次のようなコードを使用して、ADMを利用できるかどうか確認します。

ADMAvailable = false ;
try
{
    Class.forName( "com.amazon.device.messaging.ADM" );
    ADMAvailable = true ;
}
catch (ClassNotFoundException e)
{
    // 例外を処理します。
}

ADMライブラリランタイムを必要とするコードに、次のコードを追加します。
```
if (ADMAvailable)
{
    // ADMを必要とするコードをここに挿入します。
}
```
AndroidManifest.xmlファイルのapplication要素で、次のように指定されていることを確認します。
```
amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"
```

サーバー側の統合

サーバーがADMを使用するようにセットアップされていることを確認するには、以下のガイドを参照してください。

アクセストークンのリクエスト方法：認証情報を使用してアクセストークンをリクエストする方法について説明します。
メッセージの送信方法：メッセージペイロード、リクエスト形式、レスポンス形式について説明します。

単一のデバイスにメッセージを送信する場合は、開発者コンソールを使用できます。詳細については、手順4：検証する - アプリのテストを参照してください。

次のステップ

次の手順4：検証する - アプリのテストに進みます。

Last updated: 2022年3月24日