Alexa Presentation Language（APL）の概要



Alexa Presentation Language（APL）の概要

Alexa Presentation Language（APL）を使用すると、スキルに追加する視覚エクスペリエンスを作成できます。Echo Show、Fire TV、一部のFireタブレットなどのサポートされているデバイスで視覚要素を表示し、ユーザーはその視覚要素を使って操作や対話ができます。視覚エクスペリエンスには、アニメーション、グラフィック、画像、スライドショー、ビデオを含めることができます。

APLとスキルフロー

すべてのカスタムスキルは、リクエストと応答のインターフェースを使用します。Alexaは、Lambda関数またはWebサービスにリクエストを送信します。スキルがこのリクエストを処理し、応答を返します。APLは、以下のフレームワークで動作します。

  • スキルは通常のLaunchRequestまたはIntentRequestを受け取って、ユーザーとの対話を開始します。
  • スキルの応答では、APLコンテンツの表示とコマンドの実行をデバイスに指示するディレクティブを返すことができます。これらのディレクティブは、Alexa.Presentation.APLインターフェースで定義されます。ディレクティブのペイロードには、viewportにコンテンツを表示する方法を定義する構造体であるAPLドキュメントと、表示するデータを提供するデータソースが含まれます。これらの概念については、後で詳しく説明します。

  • スキルは、ユーザーのアクション（ユーザーが画面上のボタンを選択したときなど）によってトリガーされるリクエストをリッスンできます。これらのリクエストも、Alexa.Presentation.APLインターフェースで定義されます。スキルコードでハンドラーを作成して、これらのリクエストを受け入れて処理します。これは、インテント用に作成したハンドラーと同様です。

    APLドキュメントは、スキルにイベントを送信せずに画面表示を変更するコマンドをトリガーすることもできます。たとえば、画面上のボタンをタッチすると、ビデオの再生またはアニメーションを直接トリガーできます。この場合、スキルにリクエストを送信して応答を待つ必要はありません。

  • 他のスキルと同様に、ユーザーは通常のIntentRequestリクエストとしてスキルに送信される音声リクエストを行うことができます。優れたユーザーエクスペリエンスを実現するには、ユーザーが音声とタッチの両方でスキルと対話できるようにし、1つの入力モードのみの利用をユーザーに強制しないようにします。

たとえば、ユーザーはAPLスキルと次のような対話を行うことができます。

ユーザーのデバイスはEcho Showです。
ユーザー： アレクサ、トリビアマスターを開いて

Alexaが話し始めると、Echo Showにウェルカムアニメーションが表示されます。
Alexa： トリビアマスターへようこそ。 再生しますか？

ユーザー： はい。

Echo Showに、トリビアカテゴリーのスクロールリストが表示されます。
Alexa： では、再生したいトリビアマスターのカテゴリーを選んでください。 カテゴリーを読み上げるか、画面で項目を選択できます。

ユーザー：…（ユーザーは画面で「動物」のカテゴリー項目をタッチします。または、「動物のカテゴリーを再生して」などの発話で応答することもできます）

関連する背景画像の上に質問が表示されます。
Alexa： では、動物について質問します。最初の質問です。トリビアの質問テキスト…（Alexaが質問テキストを読み上げ、各行を強調表示します）

質問が読み上げられたら画面が更新され、選択可能な回答のリストが表示されます。

ユーザーは発話するか、画面上のオプションにタッチすることで質問に回答できます。

APLのディレクティブとリクエストがこの対話でどのように使用されているかを以下に示します。

ユーザーとの対話 スキルのリクエスト／回答

ユーザーのデバイスはEcho Showです。
ユーザー： アレクサ、トリビアマスターを開いて

スキルは通常のLaunchRequestを取得して、2段階で応答を返します。

  • 通常の出力音声
  • Alexa.Presentation.APL.RenderDocumentディレクティブ。このディレクティブのペイロードには、ウェルカムアニメーションを定義するAPLドキュメントが含まれています。

Alexaが話し始めると、Echo Showにウェルカムアニメーションが表示されます。
Alexa： トリビアマスターへようこそ。 再生しますか？

応答で提供されたドキュメントをEcho Showがレンダリングします。これによってウェルカムアニメーションが表示されます。

Alexaが話し終わると、デバイスはユーザーの応答を聞くためにマイクを起動します。

ユーザー： はい。

スキルはAMAZON.YesIntentインテントの通常のIntentRequestを取得し、出力音声とRenderDocumentディレクティブの両方を含む応答を返します。この場合、APLドキュメントではカテゴリーのスクロールリストを定義します。

Echo Showに、トリビアカテゴリーのスクロールリストが表示されます。
Alexa： では、再生したいトリビアマスターのカテゴリーを選んでください。

応答で提供されたドキュメントをEcho Showがレンダリングします。これによってゲームカテゴリのリストが表示されます。

Alexaが話し終わると、デバイスはユーザーの応答を聞くためにマイクを起動します。

ユーザー：…（ユーザーは画面で「動物」のカテゴリー項目をタッチします。または、「動物のカテゴリーを再生して」などの発話で応答することもできます）
  • スキルは、ユーザーがタッチした項目を示すAlexa.Presentation.APL.UserEventリクエストを取得します。
  • UserEventリクエストのハンドラーが、出力音声、 RenderDocumentディレクティブ、ExecuteCommandsディレクティブを含む応答を返します。
  • APLドキュメントで2つのページを定義します。質問を表示する詳細ページと、複数選択式の回答のリストを表示する回答ページです。
  • ExecuteCommandsディレクティブでコマンドを指定します。画面に表示される質問テキストを読み上げ、同期する行を強調表示するコマンド（SpeakItem）と、2番目のページに切り替えて選択可能な回答を表示するコマンド（SetPage）です。

関連する背景画像の上に質問が表示されます。
Alexa： では、動物について質問します。最初の質問です。トリビアの質問テキスト…（Alexaが質問テキストを読み上げ、各行を強調表示します）

Echo Showはドキュメントをレンダリングして質問テキストを表示し、SpeakItemコマンドを実行して、karaoke状態で強調表示されたテキストを読み上げます。

質問が読み上げられたら画面が更新され、選択可能な回答のリストが表示されます。

ユーザーは発話するか、画面上のオプションにタッチすることで質問に回答できます。

SpeakItemコマンドが終了すると、デバイスはSetPageコマンドを実行して画面を次のページに移動させます。これによって回答のリストが表示されます。

スキルでAPLを使用するために作成するもの

スキルでAPLを使用するには、APLドキュメント、データソース、コマンド、APLのディレクティブとリクエストを指定します。

以下のセクションでは、これらの主なAPLの概念と、スキルの作成プロセスで使用する方法について説明します。

ドキュメント

APLドキュメントとは、viewportに表示するテンプレートを定義するJSON構造のことです。視覚要素による応答の全体的な構造とレイアウトを制御します。APLドキュメントでは、次のような複数の要素を組み合わせることができます。

  • APLコンポーネントは、viewportに表示されるプリミティブなUI要素です。たとえば、シンプルなテキストボックスなどがあります。コンポーネントは、ドキュメントを構築する基本的な構成要素です。
  • レイアウトは、コンポーネントを組み合わせたものです。再利用可能なテンプレートに統合し、名前を付けることができます。その後、その名前を参照することでドキュメントにレイアウトを配置できます。これにより、管理しやすくモジュール化されたデザインを作成できます。
  • スタイルは、色やフォントサイズなど、視覚要素の一連の特性に名前を割り当てます。その後、スタイルをコンポーネントに割り当てることができます。スタイルを使用すると、一貫性のある視覚要素のデザインを作成できます。
  • リソースは、名前付きの定数です。値をハードコーディングすることなく使用できます。たとえば、赤の特定の色調を定義するmyRedというリソースを作成して、色を指定するときにそのリソース名を使用できます。
  • パッケージは、上記のすべての要素をまとめて複数のAPLドキュメントで使用できるようにしたものです。このパッケージをドキュメントに読み込みます。

APLドキュメントは、シンプルにも複雑にもできます。たとえば、シンプルなドキュメントでは、Textコンポーネントのみを使ってプレーンテキストを表示するように設定できます。次のJSONでは、viewportの中央に「ハローワールド」というテキストが表示されます。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "1.1",
  "description": "シンプルな「ハローワールド」のAPLドキュメント"
  "settings": {},
  "theme": "dark",
  "import": [],
  "resources": [],
  "styles": {},
  "onMount": [],
  "graphics": {},
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100vh",
        "textAlign": "center",
        "textAlignVertical": "center",
        "text": "ハローワールド"
      }
    ]
  }
}

APLは、モジュール化したドキュメントの作成とその再利用を推奨するように設計されています。APL向けAlexaデザインシステムには、一連のレスポンシブ対応コンポーネントとレスポンシブ対応テンプレートが用意されています。これらは、APLのコンポーネント、スタイル、リソースをモジュール化したレスポンシブ対応レイアウトに統合したものです。これを使用することで、ドキュメントをより迅速に作成し、さまざまなviewportで機能させることができます。また、独自の再利用可能なレイアウトを作成し、それらをパッケージにまとめて複数のドキュメントで使用することもできます。

これらの概念の詳細については、以下を参照してください。

データソース、データバインディング、データバインディングの構文

APLはデータバインディングをサポートしています。これにより、ドキュメントは、指定した別のデータソースからデータを取得できます。データバインディングを使用すると、ソースデータからプレゼンテーションロジック（APLドキュメント）を分離できます。

先ほどの「ハローワールド」ドキュメントの例では、表示するテキストはドキュメントでハードコーディングされています。シンプルな例ではこれで問題ありませんが、データを別のデータソースに配置して、ドキュメントからそのデータソースを指すほうがより良いアプローチといえます。この場合、ドキュメントは次のようになります。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "1.1",
  "description": "データソースを含むシンプルな「ハローワールド」のAPLドキュメント",
  "settings": {},
  "theme": "dark",
  "import": [],
  "resources": [],
  "styles": {},
  "onMount": [],
  "graphics": {},
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100vh",
        "textAlign": "center",
        "textAlignVertical": "center",
        "text": "${payload.helloworldData.properties.helloText}"
      }
    ]
  }
}

Textコンポーネントのtextプロパティの値には、ドル記号（$）と波括弧（{ }）で始まる式が含まれています。これは、データバインディングの式です。この例の${payload.helloworldData.properties.helloText}の式は、表示するテキストをhelloworldDataというデータソースから取得するようドキュメントに指示しています。そして表示するテキストはhelloworldDataのproperties.helloTextプロパティにあります。

クリップボードにコピーされました。

{
  "helloworldData": {
    "type": "object",
    "objectId": "helloworld",
    "properties": {
      "helloText": "ハローワールド"
    }
  }
}

データソースとデータバインディングの詳細については、以下を参照してください。

コマンド

次の両方を行うAPLコマンドを使用します。

  • ランタイムで視覚エクスペリエンスを変更します。たとえばSetValueコマンドでは、コンポーネントのプロパティの値を変更できます。これにより、コンポーネントの外観や動作が変更されます。
  • 対話中にスキルのLambda関数やウェブサービスと通信します。これを行うには、ドキュメントで SendEventコマンドを使用します。このコマンドは、スキルにUserEventリクエストを送信するようAlexaに指示します。コードは、IntentRequestなど他のタイプのリクエストを処理する場合と同様に、このリクエストを処理できます。APLに関連するスキルのリクエストと応答については、スキルのディレクティブとリクエストで詳しく説明します。

次の例は、buttonDescriptionTextというIDを持つコンポーネントのtextプロパティを変更するように設定されたSetValueコマンドを示しています。

クリップボードにコピーされました。

{
  "type": "SetValue",
  "componentId": "buttonDescriptionText",
  "property": "text",
  "value": "「クリックして」ボタンを押しました"
}

APLコマンドを実行するには複数の方法があります。

  • 一部のコンポーネントには、コマンドをトリガーできるイベントハンドラープロパティがあります。たとえばTouchWrapperコンポーネントには、ユーザーが画面上のコンポーネントを選択したときに実行するコマンドを指定するonPressプロパティがあります。同様に、AlexaButtonレスポンシブ対応コンポーネントには、ユーザーがボタンを選択したときに使用するコマンドを指定するprimaryActionプロパティがあります。
  • APLドキュメント自体には、ドキュメントの読み込み時にコマンドを実行するonMountプロパティがあります。このプロパティは、ユーザーがスキルを起動したときに再生されるウェルカムアニメーションを作成するときに役立ちます。
  • スキルディレクティブを使用してスキルコードからAPLコマンドを送信できます。これについては、スキルのディレクティブとリクエストで詳しく説明します。

たとえば、次のようにAlexaButtonでprimaryActionプロパティを使用して、前述のSetValueコマンドをトリガーできます。

クリップボードにコピーされました。

{
  "type": "AlexaButton",
  "id": "clickMeButton",
  "primaryAction": {
    "type": "SetValue",
    "componentId": "buttonDescriptionText",
    "property": "text",
    "value": "「クリックして」ボタンを押しました"
  }
}

コマンドの詳細については、以下を参照してください。

スキルのディレクティブとリクエスト

Lambda関数やウェブサービスでは、Alexa.Presentation.APLインターフェースで定義されたディレクティブとリクエストを使ってAPL関連の情報をやり取りします。

  • Alexa.Presentation.APL.RenderDocumentディレクティブを送信して、APLコンテンツを表示するようにデバイスに指示します。ドキュメントと関連データソース（該当する場合）の両方をディレクティブの一部として含めます。
  • Alexa.Presentation.APL.ExecuteCommandsディレクティブを送信して、デバイスにコマンドを送信します。通常、これらのコマンドは、ドキュメントの特定の部分を参照します。たとえばSpeakItemコマンドでは、特定のコンポーネント（Textコンポーネントなど）で定義されたテキストを読み上げるようにデバイスに指示します。
  • ドキュメントでSendEventコマンドを使用してAlexa.Presentation.APL.UserEventリクエストを送信すると、デバイス上で発生するユーザーのアクション（ユーザーがボタンにタッチしたときなど）をスキルに伝えることができます。コードには、これらのタイプのイベントを受け入れて処理するハンドラーを含める必要があります。

ディレクティブとリクエストを使用して、音声とタッチの両方で機能するユーザーインターフェースを作成します。たとえば前述のトリビアの対話例では、ユーザーが画面にタッチするか、カテゴリーを読み上げることでトリビアのカテゴリーを選択できるしくみを説明しました。これを実現できるよう、画面に表示される各カテゴリーは、UserEventリクエストを送信するSendEventコマンドで設定されています。スキルの対話モデルには、「{category}カテゴリーを再生して」などの発話が指定されたChooseCategoryIntentインテントもあります。スキルコードにはAlexa.Presentation.APL.UserEventリクエストまたはChooseCategoryIntentのIntentRequestをリッスンするハンドラーがあり、そのカテゴリーを選択してゲームを開始することで応答します。

ディレクティブとリクエストの詳細については、次を参照してください。

条件付きロジックとレスポンシブ対応ドキュメント

APLは、条件付きロジックに基づいて構築されています。viewportの特性やその他の要因に応じて、さまざまな方法でコンテンツを表示するAPLドキュメントを作成できます。たとえば、大きな画面では垂直方向の連続したスクロールリストを表示し、非常に小さな画面では1つのページに各リスト項目を表示するリストを作成できます。

すべてのAPLコンポーネントとコマンドには、ブール値（true / false）を取るオプションのwhenプロパティがあります。これは、デバイスがコンポーネントを表示するのか、それともコマンドを実行するのかを決定します。指定しない場合、このプロパティはデフォルトでtrueになります。

whenプロパティを使用するには、評価結果がtrueまたはfalseになるデータバインディングの式を記述します。たとえば次のステートメントでは、デバイスが小さく横長である場合に評価結果がtrueになります。

"when": "${@viewportProfile == @hubLandscapeSmall}"

前述のように、データバインディング式は常に${expression}の形式を取ります。上記の例のviewportProfileとhubLandscapeSmallの定数は、alexa-viewport-profilesパッケージの一部として提供されるリソースです。アットマーク（@）は、リソースを参照する標準的な構文です。

データバインディングの式を使用して、コンポーネントやコマンドにプロパティ値を条件付きで割り当てることもできます。たとえば、次の式では、小さい円形のデバイスの場合は文字列「center」を、その他の場合には文字列「left」を返します。

${@viewportProfile == @hubRoundSmall ? 'center' : 'left'}

これを使用すると、whenを使用してコンポーネント全体の表示や非表示を切り替える代わりに、コンポーネントのプロパティ値を条件付きで設定できます。

条件付きロジックは、レスポンシブ対応のAPLドキュメントを作成する際の重要な要素です。レスポンシブ対応のAPLドキュメントは、viewportの特性に合わせて調整できます。ユーザーはさまざまな画面サイズ、形状、アスペクト比のデバイスでスキルを呼び出すことができるため、優れたユーザーエクスペリエンスを作り出すにはレスポンシブ対応のAPLドキュメントが不可欠です。詳細と推奨事項については、レスポンシブ対応のAPLドキュメントを作成するを参照してください。

APLの条件付きロジックの詳細については、以下を参照してください。

スキルにAPLを実装する手順の概要

次の手順は、カスタムスキルの作成方法を理解していることを前提としています。カスタムスキル全般については、カスタムスキルとはとカスタムスキルのビルド手順を参照してください。

  1. 視覚要素のデザインを検討します。アイデアやガイダンスについては、AlexaデザインガイドのAPLセクションを参照してください。
  2. APLドキュメントと付随するデータソースを作成します。
    • 多くのスキルでは、スキルフローの段階に応じて異なるコンテンツを表示できるように、複数のドキュメントを使用します。前述のトリビアの対話例では、トリビアのスキルに3つのAPLドキュメントがありました。1つ目はウェルカムアニメーション、2つ目はトリビアのカテゴリーのリスト、3つ目は質問テキストを表示します。
    • 開発者コンソールのAPLオーサリングツールを使用して、作成時にドキュメントをプレビューします。
    • ベストプラクティスに沿って、ユーザーが所有するさまざまなデバイスでコンテンツが適切に表示されるようにします。
  3. Alexa.Presentation.APLインターフェースに対応するようにスキルを設定します。
  4. スキルコードには、必要に応じてドキュメントを表示できるようにRenderDocumentディレクティブとExecuteCommandsディレクティブを送信するコードを追加します。
  5. スキルコードで、UserEventリクエストのハンドラーを作成します。
  6. シミュレーターと実際のデバイスでスキルをテストします。スキルがサポートする一連のviewportプロファイルを更新し、スキルをテストしてさまざまな種類のデバイスでコンテンツが適切に表示されることを確認します。
  7. スキルをテストして認定を申請します。
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment