ウィジェットとAlexa Presentation Language（APL）の概要

ウィジェットとAlexa Presentation Language（APL）の概要

Alexaウィジェットは、スキルに関連する重要な情報をすばやく表示し、ユーザーが現在の画面コンテキストを離れたり、最新情報を確認することなく、アクションをすばやく実行できるようにします。ユーザーは、タッチまたは音声でウィジェットと対話します。スキルは、ユーザーを現在のタスクから移動させずに（「インライン」で）ウィジェットに表示されているコンテンツを更新するか、スキルを起動することで、これらの対話に応答します。

たとえば、天気スキルのウィジェットに現在の天候が表示されます。インラインの対話では、ウィジェットのボタンを押すことでウィジェットに表示されているデータが更新されます。スキルエクスペリエンスでは、ウィジェットのボタンを押すとスキルが開き、5日間の予報などの詳細を含む標準的なAPLドキュメントが表示されます。

ウィジェットをスキルに追加するには、Alexa Presentation Language（APL）を使用します。

ユーザーによるウィジェットの操作

ユーザーはウィジェットギャラリーにあるウィジェットを参照します。このギャラリーからウィジェットをインストールすると、ウィジェットパネルで使用できるようになります。パネルでのウィジェットの表示方法はデバイスによって異なります。Echo Show 15などの大型デバイスでは、ホーム画面にウィジェットパネルを常時表示できます。Echo Show 8などの小型デバイスの場合は、ユーザーが画面の端からスワイプするとウィジェットパネルが表示されます。

ユーザーがデバイスのウィジェットを操作する方法の詳細については、デジタルサービスとデバイスサポートの以下のトピックを参照してください。

ウィジェットの構成要素

ウィジェットは以下の要素で構成されています。

  • APLドキュメント – ウィジェットに表示するテンプレートを定義します。このウィジェットドキュメントでは標準的なAPL機能の一部を使用できます。レスポンシブ対応コンポーネントおよびテンプレートの一部がウィジェットに対応しています。
  • APLパッケージ – ウィジェットのメタデータとアセットを定義し、ウィジェットをスキルに関連付けます。このパッケージには、APLドキュメント、最初のデータソース、マニフェスト、その他のアセットが含まれます。
  • データストア – ウィジェットのAPLドキュメントがデータバインディングによりアクセスするデータが格納されたデバイス上の領域。スキルにリクエストを送信して応答を待つのではなく、データストアからデータをプルすることで、ウィジェットは遅延なくコンテンツを表示できます。スキルは定期的にデータストアREST APIを呼び出し、データストアを新しいデータで更新します。
  • Alexa.DataStore.PackageManagerインターフェース – AlexaがデバイスでAPLパッケージをインストール、削除、更新したときにスキルに通知するリクエストを利用できます。
  • Alexa.DataStoreインターフェース – データストアにプッシュされた更新が失敗したときにスキルに通知するためのリクエスト。
  • データストアREST API – デバイスのデータストアを更新するためのオペレーション。「スキルがスキルリクエストに応答するとき」および「スキルセッションの外から」という両方の状況で、このAPIを使用してスキルからデータストアに更新をプッシュできます。

ウィジェットのライフサイクル

ウィジェットのライフサイクルは、APLドキュメント全体のライフサイクルとは異なります。ユーザーがデバイスにウィジェットをインストールするという選択をする必要があります。ユーザーは、ウィジェットパネルが表示されていれば、インストールされたウィジェットをスキルセッションの内外で使用できます。ウィジェットは、ユーザーが削除することを選択するまでパネルに残ります。

ウィジェットのライフサイクルには以下の3つの主要なイベントがあります。

  1. ユーザーがウィジェットをインストールする
  2. 開発者がウィジェットの更新版を公開する
  3. ユーザーがウィジェットパネルからウィジェットを削除する

これらのライフサイクルイベントはすべてスキルセッション外で発生します。ユーザーはウィジェットギャラリーからインストールを開始し、ウィジェットパネルで削除を行います。開発者は、ウィジェットの最新版を公開するときに更新イベントを開始します。

ウィジェットのライフサイクルリクエストの詳細については、Alexa.DataStore.PackageManagerインターフェースのリファレンスを参照してください。APLパッケージの詳細については、APLパッケージリファレンスを参照してください。

ユーザーがウィジェットをインストールする

以下のステップは、ユーザーがウィジェットを見つけてインストールする場合のプロセスを示しています。

  1. ユーザーがウィジェットギャラリーでウィジェットを見つけ、インストールすることを選択します。
  2. Alexaがユーザーのデバイスにウィジェットをインストールします。ウィジェットのAPLパッケージの設定に応じて、AlexaはスキルへのAlexa.DataStore.PackageManager.UsagesInstalledリクエストの送信も行います。
  3. スキルはUsagesInstalledリクエストのハンドラーでデータストアREST APIを呼び出し、データストアにデータをプッシュします。

ウィジェットパネルが表示されていれば、この時点でパネルにウィジェットが表示されます。

開発者がウィジェットの更新版を公開する

以下のステップは、開発者がウィジェットの更新版を公開する場合のプロセスを示しています。

  1. 開発者がウィジェットの更新版を作成して公開します。多くの場合、基盤となるAPLドキュメントに変更を加えます。
  2. ウィジェットが既にインストールされているデバイスでは、ウィジェットの最新版を利用可能であることをAlexaが検出し、ウィジェットを最新版に更新します。ウィジェットのAPLパッケージの設定に応じて、AlexaはスキルへのAlexa.DataStore.PackageManager.UpdateRequestリクエストの送信も行います。
  3. スキルはUpdateRequestリクエストのハンドラーでデータストアREST APIを呼び出し、データストアに更新済みのデータをプッシュします。

ウィジェットパネルが表示されていれば、この時点でパネルに更新済みのウィジェットが表示されます。

ユーザーがウィジェットパネルからウィジェットを削除する

以下のステップは、ユーザーがウィジェットパネルからウィジェットを削除する場合のプロセスを示しています。

  1. ユーザーが対象のウィジェットをウィジェットパネルに残す必要がないと判断し、ウィジェットを長押しして削除します。
  2. デバイスがウィジェットをアンインストールし、スキルにAlexa.DataStore.PackageManager.UsagesRemovedリクエストを送信します。
  3. スキルで任意のクリーンアップアクションを実行することもできます。たとえば、該当するウィジェット専用のユーザー設定を保存している場合、UsagesRemovedリクエストのハンドラーを使用してそのデータを消去できます。

ウィジェットのライフサイクルと標準的なAPLドキュメントのライフサイクルの相違点

標準的なAPLドキュメントはスキルセッションのコンテキスト内に存在します。ユーザーがスキルを呼び出すと新しいスキルセッションが開始され、スキルにLaunchRequestまたはIntentRequestが送信されます。スキルはAlexa.Presentation.APL.RenderDocumentディレクティブで応答し、画面にドキュメントを表示します。スキルが新しいRenderDocumentディレクティブを送信するかスキルセッションが終了するまで、ドキュメントは画面に表示されたままになります。

ウィジェットは新しいセッションを開始できますが、ウィジェットのAPLドキュメントはこのスキルセッション外で動作します。ウィジェットドキュメントでRenderDocumentを使用することはありません。ウィジェットパネルが表示されていれば、インストール済みのウィジェットがユーザーに表示されます。ウィジェットは、ユーザーが削除することを選択するまでパネルに残ります。

ウィジェットドキュメントがSendEventコマンドを使用してスキルにリクエストを送信すると、新しいスキルセッションが開始されます。この時点で、通常のスキルセッションが適用されます。

スキルとウィジェットの間の対話

ウィジェットには、ボタンやタッチ可能な領域など、対話用コンポーネントを含めることができます。これらの対話用コンポーネントは、APLのSendEventコマンドを使用してスキルにリクエストを送信できます。このコマンドは、スキルにAlexa.Presentation.APL.UserEventを送信します。

UserEventのリクエストハンドラーは、スキルエクスペリエンス全体を開始するか、ユーザーとの対話をそれ以上行わずにウィジェットを「インライン」で更新できます。たとえば、天気スキルのウィジェットをタップすると、スキル全体を開始しなくても新しい天気データが取得され、ウィジェットに表示されます。

ウィジェットでSendEventコマンドを使用する場合は、interactionModeフラグを設定してスキルの応答方法を指定する必要があります。SendEventの詳細については、SendEventを参照してください。UserEventリクエストの詳細については、UserEventを参照してください。

ウィジェットとデータストア

データストアは、ウィジェットのAPLドキュメントがデータバインディングによりアクセスするデータが格納されたデバイス上の領域です。スキルはデータストアREST APIを使用して、定期的にこのデータストアを新しいデータで更新します。ウィジェットは、スキルにリクエストを送信して応答を待つことなく、このコンテンツを表示できます。

データストアを使用するには、APLドキュメントでデータストアExtensionを有効にして設定します。その後、データソースではなくデータストアにプロパティをバインドします。

ウィジェットのAPLドキュメントを定義するときに、ウィジェットのライフサイクルの中で変化する可能性があるデータについてはデータストアを使用します。このアプローチは、スキル呼び出し間で変化するデータにデータソースを使用する標準的なAPLドキュメントとは異なります。ウィジェットの場合、静的なウィジェットパッケージの一部として、最初のデータソースを一度だけ指定します。つまり、このデータソースはウィジェットに対して静的です。

データストアExtensionの詳細については、APLデータストアExtensionを参照してください。データストアを更新するためのデータストアREST APIの詳細については、データストアREST APIリファレンスを参照してください。データストアの更新に関連するリクエストの詳細については、Alexa.DataStoreインターフェースのリファレンスを参照してください。

デザインガイダンス

ウィジェットを開発する際のデザインガイダンスについては、Alexaデザインガイドのウィジェットの基本を参照してください。

スキルのウィジェットを開発する手順の概要

  1. 必要なインターフェースを有効にして、APLパッケージを設定します。

    詳細については、ウィジェットを作成して管理するを参照してください。

  2. ウィジェットとして表示するAPLドキュメントを作成します。このドキュメントでは、レスポンシブ対応コンポーネントやテンプレートなど、APL機能の一部を使用できます。

    時間の経過に伴って変化する可能性があるデータを表示する場合は、ドキュメントをデータソースではなくデータストアにバインドします。

  3. リクエストハンドラーをスキルコードに実装して、ウィジェットのライフサイクルイベントを管理します。

    詳細については、Alexa.DataStore.PackageManagerインターフェースのリファレンスを参照してください。

  4. ボタンやその他のタッチ可能な領域など、ユーザーとの対話がウィジェットに含まれる場合は、リクエストハンドラーをスキルコードに実装してこれらのイベントを処理します。

    詳細については、Alexa.Presentation.APLインターフェースのリファレンスを参照してください。

  5. 時間の経過に伴って変化するデータがウィジェットに表示される場合、データストアREST APIを使用して定期的に新しいデータでデータストアを更新します。

    詳細については、データストアREST APIリファレンスとAlexa.DataStoreインターフェースのリファレンスを参照してください。

  6. デバイスでウィジェットをテストします。

    詳細については、ウィジェットをテストするを参照してください。

  7. スキルの認定を受けて公開し、ウィジェットギャラリーでウィジェットを使用できるようにします。

スキルを使用せずにウィジェットの開発を開始する

ウィジェットの開発を開始する際に、スキルから開始せずにオーサリングツールを直接開くことができます。ただし、作業内容を保存するにはウィジェットをスキルに関連付ける必要があります。

スキルを使用せずにウィジェットを開発するには、こちらのリンクhttps://developer.amazon.com/alexa/console/ask/displays/widget/にアクセスしてオーサリングツールを開きます。

以下の制限事項が適用されます。

  • ドキュメントで定義されているトランスフォーマーは動作しません。
  • テスト用にウィジェットをデバイスにインストールする場合、インストールオプションを使用できませんが、プレビューオプションは使用できます。完全なテストを実行するには、ウィジェットをスキルに関連付けてください。
  • 作業内容を保存するには、ウィジェットをスキルに関連付ける必要があります。
    1. 保存アイコンをクリックします。
    2. ウィジェット名を入力します。
    3. スキルドロップダウンから既存のスキルを選択します。

詳細については、ウィジェットを作成して管理するを参照してください。

このページは役に立ちましたか？

最終更新日: 2023 年 09 月 11 日