※ このブログは「Best Practices to Accurately Send State and Change Reports for Your Smart Home Skill」の翻訳です。紹介している機能は日本語に対応していない場合があります。
スマートホームスキルを使えば、先回りしてさまざまな状況を予測できるエクスペリエンスを提供することで、ユーザーがエネルギーを効率的に利用したり、時間やお金を節約したり、自宅で安全に暮らしたりするお手伝いができます。Alexa Hunchesなどの機能は、異常が発生したスマートホームコネクテッドデバイスの状態を、Alexaが先回りして変更できるエクスペリエンスの1つです。たとえば、玄関の鍵をかけていない状態で、「アレクサ、おやすみ」と言ったとします。そんなときは、ユーザーの代わりにAlexaが鍵をかけてくれます。就寝時間にも点いたままの照明があった場合には、 普段一晩中点けたままにしない照明だけをAlexaが消してくれます。ユーザーの代わりにAlexaが行うこうしたエクスペリエンスを提供するには、エンドポイントの状態をプロアクティブに報告する必要があります。正確なデバイスの状態は、Alexaがユーザーに提供するすべてのプロアクティブなアンビエントテクノロジーの基本です。
Works with Alexa認定プログラムに参加している開発者は、エンドポイントの状態をプロアクティブに報告することが、認定を維持するための必須条件となっています。では、正確さをさらに高めるための12の推奨事項を紹介しましょう。
イベントを送信するためにはいくつかの手順を実行する必要があります。まず、イベントを有効にしてから、Alexa.Authorizationインターフェースを実装し、Alexaイベントゲートウェイにイベントを送信する権限をリクエストして、ユーザーごとに認証トークンを取得します。最後に、検出応答を更新する必要があります。
1. 開発者コンソールでAlexaイベントを有効にする
Alexaイベントゲートウェイにレポートを送信するには、スキル内でAlexaイベントを有効にする必要があります。イベントが有効になると、スキルは応答で状態情報を共有したり、状態イベントをプロアクティブに送信したりできるようになります。Alexaイベントを有効にすると、スキルは変更を有効にするため、新しい認定サイクルを経る必要があります。
Alexaイベントを有効にするには、Alexa開発者コンソールの権限タブに移動します。
スマートホームスキル:
マルチ機能スキル:
権限タブのクライアントIDとクライアントシークレットの値はどちらも、ユーザーのアクセストークンをリクエストする際に必要になるため、メモしておいてください。
詳細はこちら:https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html
2. Alexaイベントゲートウェイに送信する非同期のメッセージを有効にする
スキルが変更レポートや状態レポートなどの非同期のメッセージをAlexaイベントゲートウェイに送信する(非同期の状態レポート送信を選択した場合)うえで、Alexa.Authorizationインターフェースは重要な役割を果たします。
このインターフェースを実装すると、Alexaは、ユーザーがアカウントリンクプロセスを実行するたびに、AcceptGrantディレクティブを送信します。
既存のスキルでプロアクティブなレポート送信を有効にすることを検討している場合にも、AlexaはAcceptGrantディレクティブを送信します。既にスキルを有効にしたすべてのユーザーについてAcceptGrantディレクティブを受信する間、スキルはバックフィルプロセスを実行します。スキルは、AcceptGrantメッセージを処理し、認証プロセスを実行する必要があります。
問題が発生し、ユーザーに関連付けられたアクセストークンや更新トークンを失ってしまった場合は、オフサイクルのバックフィルプロセスを実行して新しいトークンをリクエストする必要があります。Amazonは、すべてのユーザーについてAcceptGrantディレクティブの再送信プロセスを繰り返します。
バックフィルプロセスの詳細はこちら:https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html#requesting-new-authorization-codes
Alexa.Authorizationインターフェースの詳細はこちら:https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-authorization.html
1. 対象となるコントローラー
ほとんどのスマートホームAPIコントローラーは状態および変更レポートをサポートします。ただし、CameraStreamControllerはプロアクティブにレポート可能なプロパティを定義しないため、例外となります。これ以外のコントローラーを実装した場合は、状態および変更レポートを送信してください。
各スマートホームデバイスに、デバイスの接続状態をレポートするEndpointHealthを実装する必要があります。レポートを送信するタイミングについてのルールは、以下のセクションで説明します。
2. 検出応答を更新する
実装したすべての機能が状態および変更レポートをサポートすることを確認します。
検出応答の各インターフェースについて、状態および変更レポートのサポートを指定する必要があります。指定するには、retrievableとproactivelyReportedの両方をtrueに設定します。状態および変更レポートのサポートは、ユーザーに最高のプロアクティブエクスペリエンスを提供できるかどうかを左右するため、この設定は重要です。
赤外線通信やスリープ状態のデバイスなど、エンドポイントの中には状態および変更レポートをサポートできないものもありますが、ほとんどのデバイスは状態をサポートするため、retrievable = trueとproactivelyReported = trueを設定する必要があります。
詳細はこちら:https://developer.amazon.com/en-US/docs/alexa/smarthome/state-reporting-for-a-smart-home-skill.html
3. レポート送信のタイミング
以下は、レポートを送信する必要のあるタイミングとレポートの種類のユースケースです。
1. StateReportおよびChangeReportに適用されるルール
レポートする状態の値が正しく処理されるよう、以下の形式ルールを守る必要があります。
例:開発者であるLightBulb Inc.は、電球を制御するスマートホームスキルで、EndpointHealthとPowerControllerをサポートしています。あるユーザーが、インターネットに接続され、Alexaで制御可能なLightBulb Inc.製の電球を持っています。
そのユーザーは、午前10時に「アレクサ、電球をつけて」とリクエストします。開発者LightBulb Inc.は、以下の値を設定してChangeReportを送信します。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "VOICE_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2021-06-03T16:00:50Z",
"uncertaintyInMilliseconds": 60000
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-06-03T16:00:50Z ",
"uncertaintyInMilliseconds": 0
}
]
}
}
接続ステータスは変更されていませんが、電球はオフからオンに変わりました。
1. 状態更新のレイテンシーを抑える
ディレクティブがクラウドに送信された瞬間からデバイスの状態が変更されるまで、ChangeReportイベントは3秒以内に受信する必要があります。
また、イベントレポートが正確に行われないとプロアクティブなスマートホーム機能のパフォーマンスが低下するため、正確な状態レポートも不可欠です。Alexaがエンドポイントに関するReportStateディレクティブを送信し、スキルがStateReportで応答すると、AmazonはStateReport内の値を直前のChangeReport内の値と比較します(下の正確度スコアを参照)。
イベントをよりすみやかに送信するための推奨事項をいくつか紹介します。
開発者ポータルの「レポート」タブで、スキルのパフォーマンスを確認します。
1. 98%超の正確度を維持する
Alexaは、プロアクティブな変更レポート、またはAlexaディレクティブから受け取った更新された状態を通じて、状態レポートで報告される値とエンドポイントがAlexaに報告した直前のプロパティ値を比較することにより、エンドポイント状態の正確度を測定します。 Alexaが状態レポートを受信すると、プロパティの値がエンドポイントについてAlexaが保持しているプロパティの値と比較されます。 すべての値が同じである場合、コントローラーごとの正確度メトリクスは100%となります。データの不一致が検出されると、パーセンテージは低くなります。
2. 開発者ポータルで正確度スコアを確認する
開発者コンソールで、公開中のスキルを選択してメトリクスにアクセスします。「運用メトリクス」で、「変更レポート」を選択します。ページには、変更および状態レポートを受信しているすべてのコントローラーのメトリクスが表示されます。
以下は、状態および変更レポートでよくある問題とその解決策です。
1. コントローラーの平均が一貫して基準値以下の場合:デバイスの状態更新イベントを見落としているか、レポートしていない可能性があります。
2. コントローラーのグラフが変更レポートダッシュボードに表示されない場合:状態イベントを送信していない可能性があります。