ビデオスキルの状態レポート



ビデオスキルの状態レポート

ビデオスキルを実装すると、Alexaのエンドポイントの状態を更新することができます。Alexaはこの情報を使用して、ユーザーエクスペリエンスを向上させます。

ビデオスキルは、状態レポートの一種である変更レポートをサポートしており、Alexaは現在使用されているエンドポイントを取得できます。変更レポートとは、ビデオエンドポイントの特定のプロパティが何らかの理由によって変化したときに、ビデオスキルからAlexaイベントゲートウェイに送信し、Alexaに通知するイベントです。このレポートは、スキルがAlexaからディレクティブを受信したときに送信するAlexa.Responseイベントと共に送信されます。たとえば、ChangeReportイベントを使用して、ユーザーがビデオエンドポイントをオンにしたことや、ユーザーがメディア再生を開始、停止、一時停止したことをAlexaに通知します。手動か音声対話かなど、電源や再生状態がどうやって変更されたかは関係ありません。状態レポートの詳細については、スマートホームスキルの状態レポートを参照してください。

ビデオスキルの変更レポートを実装する理由

ビデオスキルに変更レポートを実装する理由はいくつかあります。

  • Alexaにコンテキストを知らせてユーザーエクスペリエンスを向上させます
  • デバイスのルーティングを可能にします
  • ホーム全体のエクスペリエンスを改善します

ユーザーのコンテキスト

変更レポートを使用すると、Alexaがユーザーのコンテキストを設定しやすくなります。現在、ユーザーがコンテンツの再生をリクエストするときのAlexaのデフォルト動作は、楽曲の再生を想定したものです。ビデオスキルに変更レポートを実装すると、ユーザーがビデオエンドポイントを使用していることをAlexaに通知し、Alexaへのリクエストのコンテキストを設定できます。つまり、コンテンツの再生リクエストのデフォルトが楽曲からビデオに変わります。ユーザーにとっては、Alexaが自動で楽曲かビデオのコンテンツを操作し、ユーザーのコンテキストを理解してくれることを意味します。

デバイスのルーティングとオーケストレーション

変更レポートは現在使用しているエンドポイントをAlexaに知らせます。Alexaで動作する家庭用のビデオエンドポイントの数は増加しています。チューナーとFire TVのどちらもAlexaで動作します。どのビデオエンドポイントが使用されているかがわかれば、「アレクサ、仮面ライダーアマゾンズを再生して」などとリクエストしたときに適切なエンドポイントを処理できるようになります。Alexaは、ユーザーのリクエストのディレクティブのルーティング先を決める際、最新の変更レポートがどのエンドポイントだったかに基づいて評価します。たとえば、ユーザーがチューナーを使っている場合、「仮面ライダーアマゾンズ」という発話はチューナーを制御するスキルに送られます。ユーザーがその後Fire TVに切り替えた場合、「仮面ライダーアマゾンズを再生して」のリクエスト結果のディレクティブはFire TVスキルに送られます。変更レポートがない場合、Alexaはディレクティブの送信先を判断できない場合もあります。

Alexaのホーム全体のエクスペリエンス

変更レポートイベントにより、Alexaはユーザーのリクエストがビデオエンドポイントに対するものか、家の中の他のエンドポイント(スマートスピーカーや家全体のオーディオシステムなど)のいずれかに対するものかを知ることができます。たとえば、ユーザーがFire TVのホーム画面を見ていてメディアが再生されていない場合、変更レポートがあれば「アレクサ、一時停止して」というリクエストを別の部屋で再生中のオーディオデバイスの楽曲にルーティングできます。

変更レポートでサポートされるプロパティと条件

ビデオエンドポイントの電源や再生の状態が変更されたときにレポートを送信する必要があります。以下の表は、ビデオスキルから変更レポートを送信する際のプロパティ、値、変更条件を示しています。

プロパティ 条件/アクション
powerState ON エンドポイントの電源がオンになったか、スリープ状態から復帰しました
powerState OFF エンドポイントの電源がオフになったか、スリープ状態に入りました
playbackState PLAYING ユーザーがチャンネルを変えたか、ビデオ再生を開始したか、プライムビデオなどのアプリを起動しました
playbackState PAUSED メディアプレーヤーが一時停止しました
playbackState STOPPED ユーザーがプレーヤーを終了し、メディアのコントロールもできなくなりました。ユーザーがデバイスのホーム画面に移動したり、検索結果を全画面表示した場合などに発生します。

変更レポートを送信する手順

以下で、変更レポートを送信する手順を説明します。そのほかのドキュメントへのリンクも記載しています。

ステップ1 - イベント送信の権限をリクエストする

ChangeReportsイベントは、Alexaイベントゲートウェイに送信されます。ユーザーごとに認証トークンが必要です。開発者コンソールでスキルを検索し、アクセス権限セクションでAlexaイベントを送るを選択します。クライアントIDとクライアントシークレットは、Login with Amazon(LWA)を使用してユーザーを認証する次のステップで使用するため、記録しておいてください。

ステップ2 - AcceptGrantディレクティブを処理するコードを追加する

Alexaイベントを送信する権限をリクエストしたら、スキルのLambda関数はユーザーごとにAcceptGrantディレクティブを受信します。AcceptGrantディレクティブには、ユーザーの認証トークンの取得に使用する認可コードが含まれます。ユーザーと同じ地域でトークンの取得と保存を行うには、コードを追加する必要があります。AcceptGrantディレクティブが正常に処理された場合、AcceptGrant.Responseイベントを使用して応答します。AcceptGrantディレクティブの処理でエラーが発生した場合、ErrorResponseイベントを使用して同期的に応答する必要があります。

この処理を行う詳細な手順については、アクセス権限を設定してAlexaへのユーザー認証を実現するを参照してください。

ステップ3 - 検出中、プロパティにプロアクティブにレポートされることを表示する

検出中にエンドポイントプロパティについての変更レポートを送信することを示す必要があります。検出の応答でプロパティをproactivelyReportedに指定します。詳細については、スマートホームスキルの状態レポートを参照してください。

ステップ4 - Alexaイベントゲートウェイに変更レポートイベントを送信する

最後に、レポート可能なプロパティが変更されたときにイベントゲートウェイに対して変更レポートの送信を開始します。つまり、powerStateまたはplaybackStateのプロパティが何らかの理由で変更されたら、AlexaイベントゲートウェイにChangeReportイベントを送信します。イベントには、プロパティの現在の状態を含めます。イベントゲートウェイへの各メッセージには、HTTPヘッダーとして、またメッセージの本文にも認証トークンを含める必要があります。

変更レポートの送信方法と送信先、変更レポートのフォーマットについては、イベントゲートウェイにイベントを送信するを参照してください。

例:powerStateの変更

この例のChangeReportイベントは、Alexa.PowerControllerインターフェースを実装したエンドポイント向けのものです。イベントは、エンドポイントの物理的な操作によってエンドポイントのpowerStateがOFFからONに変わったことをレポートします。


POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
    "context": {},
    "event": {
        "header": {
            "messageId": "2b3409df-d686-4a52-9bba-d361860bac61",
            "namespace": "Alexa",
            "name": "ChangeReport",
            "payloadVersion": "3"
        },
         "endpoint": {
           "scope": {
             "type":"BearerToken",
             "token": "access-token-from-Amazon"
           },
           "endpointId": "appliance-001"
         },
            "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PowerController",
                    "name": "powerState",
                    "value": "ON",
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    }
}

例:playbackStateの変更

この例のChangeReportは、PlaybackStateReporterインターフェースを実装したエンドポイント向けのものです。このイベントは、エンドポイントのplaybackStateが物理的な操作によってPLAYINGに変更されたことをレポートします。また、powerStateは変更されなかったため、powerStateをContextオブジェクトでレポートします。


POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
    "context": {
        "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }]
    },
    "event": {
        "header": {
            "messageId": "2b3409df-d686-4a52-9bba-d361860bac61",
            "namespace": "Alexa",
            "name": "ChangeReport",
            "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type":"BearerToken",
            "token": "access-token-from-Amazon"
          },
          "endpointId": "appliance-001"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PlaybackStateReporter",
                    "name": "playbackState",
                    "value": {
                        "state": "PLAYING"
                    },
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    }
}