Alexa Presentation Language(APL)の概要
Alexa Presentation Language(APL)を使用すると、スキルに追加する視覚エクスペリエンスを作成できます。Echo Show、Fire TV、一部のFireタブレットなどのサポートされているデバイスで視覚要素を表示し、ユーザーはその視覚要素を使って操作や対話ができます。視覚エクスペリエンスには、アニメーション、グラフィック、画像、スライドショー、ビデオを含めることができます。
- APLとスキルフロー
- 異なる種類のデバイスでのAPLサポート
- スキルでAPLを使用するために作成するもの
- 条件付きロジックとレスポンシブ対応ドキュメント
- スキルにAPLを実装する手順の概要
- 関連トピック
APLとスキルフロー
すべてのカスタムスキルは、リクエストと応答のインターフェースを使用します。Alexaは、Lambda関数またはWebサービスにリクエストを送信します。スキルがこのリクエストを処理し、応答を返します。APLは、以下のフレームワークで動作します。
- スキルは通常の
LaunchRequest
またはIntentRequest
を受け取って、ユーザーとの対話を開始します。 - スキルの応答では、APLコンテンツの表示とコマンドの実行をデバイスに指示するディレクティブを返すことができます。これらのディレクティブは、
Alexa.Presentation.APL
インターフェースで定義されます。ディレクティブのペイロードには、viewportにコンテンツを表示する方法を定義する構造体であるAPLドキュメントが含まれます。ペイロードには、表示する特定のデータを提供するデータソースも含まれます。これらの両方の概念の詳細については、スキルでAPLを使用するために作成するものを参照してください。 -
スキルは、ユーザーのアクション(ユーザーが画面上のボタンを選択したときなど)によってトリガーされるリクエストをリッスンできます。これらのリクエストも、
Alexa.Presentation.APL
インターフェースで定義されます。スキルコードでハンドラーを作成して、これらのリクエストを受け入れて処理します。これは、インテント用に作成したハンドラーと同様です。注: APLドキュメントは、スキルにリクエストを送信せずに画面表示を変更するコマンドをトリガーすることもできます。たとえば、ビデオ再生やアニメーションを直接トリガーするボタンを、画面上に定義できます。この場合、Alexaはスキルにリクエストを送信して応答を待つ必要はありません。 - 他のスキルと同様に、ユーザーは通常の
IntentRequest
リクエストとしてスキルに送信される音声リクエストを行うことができます。優れたユーザーエクスペリエンスを実現するには、ユーザーが音声とタッチの両方でスキルと対話できるようにし、1つの入力モードのみの利用をユーザーに強制しないようにします。
たとえば、ユーザーはAPLスキルと次のような対話を行うことができます。
ユーザーのデバイスはEcho Showです。
ユーザー: アレクサ、トリビアマスターを開いて
Alexaが話し始めると、Echo Showにウェルカムアニメーションが表示されます。
Alexa: トリビアマスターへようこそ。 再生しますか?
ユーザー: はい。
Echo Showに、トリビアカテゴリーのスクロールリストが表示されます。
Alexa: では、再生したいトリビアマスターのカテゴリーを選んでください。 カテゴリーを読み上げるか、画面で項目を選択できます。
ユーザー: (ユーザーは画面で「動物」のカテゴリー項目をタッチするか、「動物のカテゴリーを再生して」などの発話で応答することができます)
関連する背景画像の上に質問が表示されます。
Alexa: では、動物について質問します。最初の質問です。トリビアの質問テキスト…(Alexaが質問テキストを読み上げ、各行を強調表示します)
質問が読み上げられたら画面が更新され、選択可能な回答のリストが表示されます。
ユーザーは発話するか、画面上のオプションにタッチすることで質問に回答できます。
APLのディレクティブとリクエストがこの対話でどのように使用されているかを以下に示します。
ユーザーとの対話 | スキルのリクエスト/回答 |
---|---|
ユーザーのデバイスはEcho Showです。 |
スキルは通常の
|
Alexaが話し始めると、Echo Showにウェルカムアニメーションが表示されます。 |
応答で提供されたドキュメントをEcho Showがレンダリングします。これによってウェルカムアニメーションが表示されます。 Alexaが話し終わると、デバイスはユーザーの応答を聞くためにマイクを起動します。 |
ユーザー: はい。 |
スキルは |
Echo Showに、トリビアカテゴリーのスクロールリストが表示されます。 |
応答で提供されたドキュメントをEcho Showがレンダリングします。これによってゲームカテゴリのリストが表示されます。 Alexaが話し終わると、デバイスはユーザーの応答を聞くためにマイクを起動します。 |
ユーザー:…(ユーザーは画面で「動物」のカテゴリー項目をタッチします。) |
|
関連する背景画像の上に質問が表示されます。 |
Echo Showはドキュメントをレンダリングして質問テキストを表示し、 |
質問が読み上げられたら画面が更新され、選択可能な回答のリストが表示されます。 ユーザーは発話するか、画面上のオプションにタッチすることで質問に回答できます。 |
|
異なる種類のデバイスでのAPLサポート
APLを使用すると、画面付きのデバイス(Echo Show、Fireタブレットなど)と、英数字の時計付きデバイス(Echo Dot with clockなど)の両方にコンテンツを表示できます。
- すべてのAPL機能を使用して、画面付きのデバイスにコンテンツを表示できます。APLは、ユーザーインタラクションと、画像、ビデオ、アニメーションなどのリッチコンテンツを完全にサポートします。
- 少ないAPLの構成で、Echo Dot with clockなどのキャラクターディスプレイ付きデバイスにコンテンツを表示できます。APLは、これらのディスプレイへの英数字データの表示をサポートしています。また、テキストのスクロールや、タイマーやカウントダウンの表示などのユニークな機能をサポートしています。Alexa Presentation Languageとキャラクターディスプレイの概要を参照してください。
APLの概念は、異なるデバイスでも共通しています。Amazonはこれらのデバイスカテゴリの両方をサポートすることをお勧めします。両方をサポートすることで、より多くのユーザーにリーチできます。
Fireタブレットでは、Showモードとタブレットモードの両方でAPLコンテンツが表示されます。
- Showモードでは、タブレットはEcho Showのように動作します。タブレットは横向きモードでロックされます。ユーザーはスキルを呼び出し、APLコンテンツを表示できます。
- タブレットモードでは、通常のタブレット機能を引き続き使用できます。ユーザーがスキルを呼び出すと、APLコンテンツはタブレットのビューポートに縮小され、縦向きに表示されます。
スキルでAPLを使用するために作成するもの
スキルでAPLを使用するには、APLドキュメント、データソース、コマンド、APLのディレクティブとリクエストを指定します。
以下のセクションでは、これらの主なAPLの概念と、スキルの作成プロセスで使用する方法について説明します。
ドキュメント
APLドキュメントとは、viewportに表示するテンプレートを定義するJSON構造のことです。視覚要素による応答の全体的な構造とレイアウトを制御します。APLドキュメントでは、次のような複数の要素を組み合わせることができます。
- APLコンポーネントは、viewportに表示されるプリミティブなUI要素です。たとえば、シンプルなテキストボックスなどがあります。コンポーネントは、ドキュメントを構築する基本的な構成要素です。
- レイアウトは、コンポーネントを組み合わせたものです。再利用可能なテンプレートに統合し、名前を付けることができます。その後、その名前を参照することでドキュメントにレイアウトを配置できます。これにより、管理しやすくモジュール化されたデザインを作成できます。
- スタイルは、色やフォントサイズなど、視覚要素の一連の特性に名前を割り当てます。その後、スタイルをコンポーネントに割り当てることができます。スタイルを使用すると、一貫性のある視覚要素のデザインを作成できます。
- リソースは、名前付きの定数です。値をハードコーディングすることなく使用できます。たとえば、赤の特定の色調を定義する
myRed
というリソースを作成して、コンポーネントの色を指定するときにそのリソース名を使用できます。 - パッケージは、上記のすべての要素をまとめて複数のAPLドキュメントで使用できるようにしたものです。このパッケージをドキュメントに読み込みます。
APLドキュメントは、シンプルにも複雑にもできます。たとえば、シンプルなドキュメントでは、Text
コンポーネントのみを使ってプレーンテキストを表示するように設定できます。次のJSONでは、viewportの中央に「ハローワールド」というテキストが表示されます。
{
"type": "APL",
"version": "1.4",
"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ドキュメントを作成する
- APL向けAlexaデザインシステム
- APLレイアウト
- APLスタイルの定義と評価
- APL Resources
- APLパッケージ
- コンポーネント
データソース、データバインディング、データバインディングの構文
APLはデータバインディングをサポートしています。これにより、ドキュメントは、指定した別のデータソースからデータを取得できます。データバインディングを使用すると、ソースデータからプレゼンテーションロジック(APLドキュメント)を分離できます。
先ほどの「ハローワールド」ドキュメントの例では、表示するテキストはドキュメントでハードコーディングされています。シンプルな例であれば、ハードコードされたテキストでも問題ありません。しかし、データを別のデータソースに配置し、ドキュメントからそのデータソースをポイントすることでメンテナンスを容易にできます。この場合、ドキュメントは次のようになります。
{
"type": "APL",
"version": "1.4",
"description": "データソースを含むシンプルな「ハローワールド」のAPLドキュメント",
"theme": "dark",
"mainTemplate": {
"parameters": [
"helloworldData"
],
"items": [
{
"type": "Text",
"height": "100vh",
"textAlign": "center",
"textAlignVertical": "center",
"text": "${helloworldData.properties.helloText}"
}
]
}
}
Text
コンポーネントのtext
プロパティの値には、ドル記号($
)と波括弧({ }
)で始まる式が含まれています。この構文は、データバインディングの式です。この例の${helloworldData.properties.helloText}
の式は、表示するテキストをhelloworldData
というデータソースから取得するようドキュメントに指示しています。そして表示するテキストはhelloworldData
のproperties.helloText
プロパティにあります。
{
"helloworldData": {
"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
コマンドをトリガーできます。
コマンドの詳細については、以下のトピックを参照してください。
スキルのディレクティブとリクエスト
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
をリッスンするハンドラーがあり、そのカテゴリーを選択してゲームを開始することで応答します。
ディレクティブとリクエストの詳細については、次を参照してください。
- ASK SDK v2でのAlexa Presentation Languageの使用
- Alexa.Presentation.APLインターフェース
- カスタムスキルのJSONインターフェースのリファレンス
条件付きロジックとレスポンシブ対応ドキュメント
APLは、条件付きロジックに基づいて構築されています。viewportの特性やその他の要因に応じて、さまざまな方法でコンテンツを表示するAPLドキュメントを作成できます。たとえば、大きな画面では垂直方向の連続したスクロールリストを表示し、小さな画面では1つのページに各リスト項目を表示するリストを作成できます。
すべてのAPLコンポーネントとコマンドには、ブール値(true
/ false
)を取るオプションのwhen
プロパティがあります。この値は、デバイスがコンポーネントを表示するのか、それともコマンドを実行するのかを決定します。値を指定しない場合、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を実装する手順の概要
次の手順は、カスタムスキルの作成方法を理解していることを前提としています。カスタムスキル全般については、カスタムスキルとはとカスタムスキルのビルド手順を参照してください。
- 視覚要素のデザインを検討します。アイデアやガイダンスについては、AlexaデザインガイドのAPLセクションを参照してください。
- APLドキュメントと付随するデータソースを作成します。
- スキルフローの段階に応じて異なるコンテンツを表示できるように、複数のドキュメントを作成することもできます。前述のトリビアの対話例では、トリビアのスキルに3つのAPLドキュメントがありました。1つ目はウェルカムアニメーション、2つ目はトリビアのカテゴリーのリスト、3つ目は質問テキストを表示します。
- 作成中のドキュメントをプレビューするには、開発者コンソールのAPLオーサリングツールを使用してください。
- ユーザーが所有するさまざまなデバイスでコンテンツが適切に表示されるようにするには、ベストプラクティスを参考にしてください。
Alexa.Presentation.APL
インターフェースに対応するようスキルを設定します。詳細については、APLをサポートするようスキルを設定するを参照してください。- スキルコードには、必要に応じてドキュメントを表示できるように
RenderDocument
ディレクティブとExecuteCommands
ディレクティブを送信するコードを追加します。ディレクティブの詳細については、以下のトピックを参照してください。 - スキルコードで、
UserEvent
リクエストのハンドラーを作成します。リクエストの詳細については、以下のトピックを参照してください。 -
シミュレーターと実際のデバイスでスキルをテストします。スキルがサポートする一連のviewportプロファイルを更新し、スキルをテストしてさまざまな種類のデバイスでコンテンツが適切に表示されることを確認します。
シミュレーターを使用して、画面付きのデバイス(Echo Showなど)を含むさまざまなviewportでコンテンツがどのように表示されるかを確認できます。シミュレータには、Echo Dot with clockのようなキャラクターディスプレイ用のviewportは含まれていないため、キャラクターディスプレイでコンテンツをテストするには実際のデバイスを使用する必要があります。
- スキルをテストして認定を申請します。