Alexa.Presentation.APLインターフェースのリファレンス

Alexa.Presentation.APLインターフェースは、Echo Showなどの画面付きデバイスでコンテンツを表示するディレクティブとリクエストを提供します。このインターフェースのリクエストでディレクティブを使用して、画面付きデバイスに標準のAPL応答を表示したり、デバイスにインストールされているウィジェットと通信したりすることができます。

supportedInterfacesのAlexa.Presentation.APL

ユーザーのデバイスにAPL対応の画面がある場合は、context.System.device.supportedInterfacesオブジェクトに[Alexa.Presentation.APL]が含まれています。

APL対応デバイスのLaunchRequest  

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "2024.3"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewport": {
      "experiences": [
        {
          "canRotate": true,
          "canResize": true
        },
        {
          "canRotate": false,
          "canResize": false
        }
      ],
      "shape": "RECTANGLE",
      "pixelWidth": 1024,
      "pixelHeight": 600,
      "dpi": 160,
      "currentPixelWidth": 640,
      "currentPixelHeight": 500,
      "touch": [
        "SINGLE"
      ],
      "keyboard": [
        "DIRECTION"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    }
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "ja-JP",
    "shouldLinkResultBeReturned": false
  }
}

Alexa.Presentation.APLディレクティブを返す前に、必ずsupportedInterfacesを確認してください。ASK SDKでこの確認を行う例については、スキルコードにAPLサポートを追加するのユーザーのデバイスがAPLに対応していることを確認するを参照してください。

利用可能なExtensions

Extensionsは、追加のAPL機能を提供するオプションの拡張機能です。一部のExtensionsは、スキルマニフェストでextensionを宣言する必要があります。ユーザーのデバイスがこれらのExtensionsをサポートしている場合、contextオブジェクトにはExtensions.availableプロパティが含まれます。このプロパティにはマップが含まれ、各項目のキーは使用可能なextensionのURIを示します。

次の例は、Smart MotionとEntity Sensingをサポートするデバイスからのリクエストを示しています。

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {
      "playerActivity": "IDLE"
    },
    "Viewports": [
      {
        "type": "APL",
        "id": "<文字列>"
      }
    ],
    "Extensions": {
      "available": {
        "alexaext:smartmotion:10": {},
        "alexaext:entitysensing:10": {}
      }
    }
  }
}

context.Extensionsプロパティには、次の条件の両方を満たすextensionが含まれます。

• スキルマニフェストのrequestedExtensionsプロパティでリクエストされていること。

  マニフェストでextensionをリクエストする方法の詳細については、スキルマニフェストでextensionをリクエストするを参照してください。

• extensionがこのデバイスでサポートされていること。

マニフェストに含めることができるのは一部のextensionです。要件を確認するには、使用する各extensionのトピックを参照してください。

ディレクティブ

次の表は、Alexa.Presentation.APLインターフェースで使用できるディレクティブの一覧です。「ウィジェットのサポート」列は、ディレクティブを使用してデバイスにインストールされているウィジェットと通信できるかどうかを示しています。

RenderDocumentディレクティブ

指定されたdocumentに含まれているAPLコンテンツを表示するようデバイスに命令します。オプションで、1つまたは複数のdatasourcesを指定してコンテンツをドキュメントにバインドすることもできます。

次のRenderDocumentの例では、2つのTextコンポーネントとhelloworldDataというデータソースを含むドキュメントを送信します。

{
  "type": "Alexa.Presentation.APL.RenderDocument",
  "token": "helloworldToken",
  "document": {
    "type": "APL",
    "version": "2024.3",
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "items": [
            {
              "type": "Text",
              "id": "helloTextComponent",
              "text": "${payload.helloworldData.properties.helloText}",
              "textAlign": "center",
              "textAlignVertical": "center",
              "maxLines": 3,
              "grow": 1
            },
            {
              "type": "Text",
              "id": "newHelloTextComponent",
              "text": "${payload.helloworldData.properties.newHelloText}",
              "textAlign": "center",
              "textAlignVertical": "bottom",
              "maxLines": 3,
              "opacity": 0
            }
          ]
        }
      ]
    }
  },
  "datasources": {
    "helloworldData": {
      "type": "object",
      "objectId": "helloworld",
      "properties": {
        "helloText": "ハローワールド。 このAPLドキュメントは、helloworldDataというデータソースのテキストを表示します。",
        "newHelloText": "元のハローテキストを非表示にして、これを表示しました。"
      }
    }
  }
}

開発者コンソールでスキルと共にドキュメントを保存し、RenderDocumentディレクティブにリンクすることもできます。次の例は、「ハローワールド」ドキュメントが「helloworld-by-link」という名前で保存されていることを前提としています。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.RenderDocument",
      "token": "helloworldToken",
      "document": {
        "src": "doc://alexa/apl/documents/helloworld-by-link",
        "type": "Link"
      },
      "datasources": {
        "helloworldData": {
          "type": "object",
          "objectId": "helloworld",
          "properties": {
            "helloText": "ハローワールド。 このAPLドキュメントは、helloworldDataというデータソースのテキストを表示します。",
            "newHelloText": "元のハローテキストを非表示にして、これを表示しました。"
          }
        }
      }
    }
  ]
}

RenderDocumentのプロパティ

documentプロパティには、ドキュメントのURLが設定されたsrcプロパティか、ドキュメント全体のJSONが常に含まれている必要があります。

ASK SDK v2でRenderDocumentを送信する方法の例については、スキルコードにAPLサポートを追加するのリクエストハンドラーの応答でRenderDocumentを返すを参照してください。

開発者コンソールに保存されたAPLドキュメントへのリンク

開発者コンソールでAPLドキュメントを保存すると、RenderDocumentディレクティブでそのドキュメントをリンクすることができます。つまり、APLドキュメントのJSONをエクスポートしてコードにコピーする必要はありません。

開発者コンソールのドキュメントにリンクするには、次の構文を記述します。

doc://alexa/apl/documents/<ドキュメント名>

<ドキュメント名>は、開発者コンソールでドキュメントを保存するときに使用した名前です。

開発者コンソールでドキュメントを作成して保存する方法の詳細については、開発者コンソールでドキュメントを作成するを参照してください。

開発者コンソールでスキルと統合オプションを使用すると、ドキュメントへのリンクを含むコードスニペットを必要な形式でコピーできます。

1. 開発者コンソールでスキルを開きます。
2. 左側のナビゲーションでマルチモーダルをクリックします。
3. 統合するドキュメントを探し、スキルと統合をクリックします。
4. サンプルコードを確認し、必要に応じてスキルコードにコピーします。

RenderDocumentとその他のスキルディレクティブ

• 応答では、RenderDocumentと、Dialog.Delegateを除く任意のDialogディレクティブを組み合わせることができます。たとえば、Dialog.ElicitSlotを使用して、ユーザーにスロット値の入力を求め、同時にRenderDocumentでそのスロットに関連する情報を画面に表示できます。
• 応答では、RenderDocumentと次のインターフェースのディレクティブを組み合わせることはできません。
  • AudioPlayer
  • Display
  • VideoApp

ExecuteCommandsディレクティブ

指定されたcommandsを以下のいずれかで実行するようデバイスに命令します。

• 標準のドキュメント - 現在レンダリングされているドキュメントです。tokenで識別されます。
• ウィジェット - インストール済みのウィジェットです。presentationUriで識別されます。

次の例では、helloworldTokenトークンで識別されたドキュメントに対して動作するExecuteCommandsディレクティブを送信します。このディレクティブには、次の2つのコマンドがあります。

• 1番目のAnimateItemコマンドは、helloTextComponentコンポーネントの不透明度を3秒間で0に変更して、ビューからフェードアウトさせます。
• 2番目のAnimateItemコマンドは、newHelloTextComponentコンポーネントの不透明度を3秒間で0から1に変更して、ビューにフェードインさせます。

{
  "type": "Alexa.Presentation.APL.ExecuteCommands",
  "token": "helloworldToken",
  "commands": [
    {
      "type": "AnimateItem",
      "componentId": "helloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "0.0"
        }
      ]
    },
    {
      "type": "AnimateItem",
      "componentId": "newHelloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "1.0"
        }
      ]
    }
  ]
}

以下は、ウィジェットをターゲットとするExecuteCommandsディレクティブを含む応答のdirectives配列の例です。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.ExecuteCommands",
      "presentationUri": "widget://amzn1.ask.skill.1/MyWidgetSandbox/f1cf2427-1-1-1-1",
      "commands": [
        {
          "type": "AnimateItem",
          "duration": 1000,
          "componentId": "itemDescription",
          "value": {
            "property": "opacity",
            "to": 0
          }
        },
        {
          "type": "SetValue",
          "componentId": "successMessage",
          "property": "text",
          "value": "項目が保存されました。"
        }
      ]
    }
  ]
}

ウィジェットは、ほとんどの標準APLコマンドをサポートしています。ExecuteCommandsを使用して送信できるコマンドのリストについては、標準コマンドを参照してください。

ExecuteCommandsプロパティ

ExecuteCommandsディレクティブは、tokenまたはpresentationUriで識別された特定のドキュメントに対して、コマンドを実行します。

• 標準のドキュメントをターゲットにするには、指定するtokenが、対象となるドキュメントを送信したRenderDocumentディレクティブで指定したtokenと一致する必要があります。
• ウィジェットをターゲットにするには、presentationUriが、デバイスにインストールされているウィジェットの識別子と一致する必要があります。

RenderDocumentディレクティブとExecuteCommandsディレクティブは、同じスキルの応答で送信することも、別の応答で送信することもできます。

• 1つの応答に両方のディレクティブが含まれている場合、両方のディレクティブでtokenが一致すれば、デバイスは指定されたドキュメントを表示した後に、コマンドを実行します。

• ExecuteCommandsを別の応答で返すと、デバイスは現在Viewportに表示されているドキュメントに対して、コマンドを実行します。tokenは、これより前にRenderDocumentディレクティブで使用したtokenと一致する必要があります。

  このシナリオでExecuteCommandsを送信する前に、リクエストの視覚的なコンテキストを確認して、ドキュメントが現在表示されていることを確認します。リクエストのcontext.["Alexa.Presentation.APL"].tokenプロパティから、現在表示されているドキュメントのtokenを取得できます。

いずれの場合も、tokenの値がディレクティブ間で一致しなければ、コマンドは実行されません。

以下のリクエストの例では、ViewportがhelloworldWithButtonTokenトークンを持つドキュメントを表示していることを示しています（説明を簡潔にするために、このリクエストの一部は省略されています）。

{
  "version": "1.0",
  "session": {},
  "context": {
    "Alexa.Presentation.APL": {
      "token": "helloworldWithButtonToken",
      "version": "APL_WEB_RENDERER_GANDALF",
      "componentsVisibleOnScreen": [
        {
          "uid": ":1000",
          "position": "1024x600+0+0:0",
          "type": "text",
          "tags": {
            "viewport": {}
          },
          "children": [
            {
              "id": "fadeHelloTextButton",
              "uid": ":1002",
              "position": "270x70+377+450:0",
              "type": "text",
              "tags": {
                "focused": false,
                "clickable": true
              },
              "entities": []
            }
          ],
          "entities": []
        }
      ]
    },
    "System": {},
    "Viewport": {},
    "Viewports": []
  },
  "request": {}
}

このプロパティを確認してASK SDKでExecuteCommandsを返す方法の例については、スキルコードにAPLサポートを追加するのリクエストハンドラーの応答でExecuteCommandsを返すを参照してください。

ExecuteCommandsとその他のスキルディレクティブ

応答では、ExecuteCommandsと次のインターフェースのディレクティブを組み合わせることはできません。

• AudioPlayer
• Dialog
• Display
• VideoApp

SendIndexListDataディレクティブ

LoadIndexListDataリクエストに応答して、表示する一連の新しいリスト項目を送信します。次に表示する項目セットを含むdynamicIndexListデータソースを含めます。応答にはoutputSpeechまたはshouldEndSessionを含めないでください。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendIndexListData",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "startIndex": 11,
      "minimumInclusiveIndex": 11,
      "maximumExclusiveIndex": 21,
      "items": [
        {"primaryText":"項目11"},
        {"primaryText":"項目12"},
        {"primaryText":"項目13"},
        {"primaryText":"項目14"},
        {"primaryText":"項目15"},
        {"primaryText":"項目16"},
        {"primaryText":"項目17"},
        {"primaryText":"項目18"},
        {"primaryText":"項目19"},
        {"primaryText":"項目20"}
      ]
    }
  ]
}

プロアクティブな読み込み

スキルがLoadIndexListDataリクエストに応答する場合は、correlationTokenを指定する必要があります。想定されるcorrelationTokenがSendIndexListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

LoadIndexListDataリクエストへの応答以外で、一連のリスト項目を送信する場合は、correlationTokenを省略します。

SendTokenListDataディレクティブ

LoadTokenListDataリクエストに応答して、表示するリスト項目の新しいページを送信します。次に表示するページの項目を含むdynamicTokenListデータソースを含めます。応答にはoutputSpeechまたはshouldEndSessionを含めないでください。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendTokenListData",
      "token": "developer-provided-token",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "pageToken": "myListPage2",
      "nextPageToken" "myListPage3"
      "items": [
        {"primaryText":"項目11"},
        {"primaryText":"項目12"},
        {"primaryText":"項目13"},
        {"primaryText":"項目14"},
        {"primaryText":"項目15"},
        {"primaryText":"項目16"},
        {"primaryText":"項目17"},
        {"primaryText":"項目18"},
        {"primaryText":"項目19"},
        {"primaryText":"項目20"}
      ]
    }
  ]
}

プロアクティブな読み込み

スキルがLoadTokenListDataリクエストに応答する場合は、correlationTokenを指定する必要があります。想定されるcorrelationTokenがSendTokenListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

LoadTokenListDataリクエストへの応答以外で、一連のリスト項目を送信する場合は、correlationTokenを省略します。

UpdateIndexListDataディレクティブ

RenderDocumentディレクティブで、デバイスに既に送信されたデータソースにリスト項目を挿入、設定、削除するには、一連のデータの操作をAlexaに送信します。1つのディレクティブに複数の変更を含めることができます。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.UpdateIndexListData",
      "token": "developer-provided-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "operations": [
        {
          "type": "InsertItem",
          "index": 10,
          "item": {
            "primaryText": "項目10の前に挿入された、新しい項目9.5"
          }
        },
        {
          "type": "InsertMultipleItems",
          "index": 12,
          "items": [
            {"primaryText":"項目12の前に挿入された、3つの新しい項目の1番目"},
            {"primaryText":"3つの項目の2番目"},
            {"primaryText":"3つの項目の3番目"}
          ]
        },
        {
          "type": "SetItem",
          "index": 14,
          "item": {"primaryText":"項目14の置換テキスト"}
        },
        {
          "type": "DeleteItem",
          "index": 16
        },
        {
          "type": "DeleteMultipleItems",
          "index": 17,
          "count": 2
        }
      ]
    }
  ]
}

listVersion

更新後のリストの新しいバージョンです。スキルとAlexaの間でリストの一貫性を維持するために使用されます。Alexaは、すべてのリストがバージョン0から始まると想定しているため、特定のリストに対して発行された最初のUpdateIndexListDataディレクティブはlistIndexを1に設定します。Alexaは、指定されていないディレクティブまたは中間ディレクティブが受信されて処理されるまで、順不同のlistVersionを指定するUpdateIndexListDataディレクティブをすべてバッファーします。

このフィールドはUpdateIndexListDataでは必須ですが、SendIndexListDataでは任意となる場合があります。

• リストの更新情報を挿入、設定、削除しない場合、この値を入力する必要はありません。
• リストに対して挿入、設定、削除操作を実行するときは、すべてのSendIndexListDataディレクティブに対してこの値を入力する必要があります。

したがって、特定のリストについては、Alexaは以下を破棄します。

• listVersionを指定していないSendIndexListDataディレクティブの後に受信された、すべてのUpdateIndexListDataディレクティブ
• UpdateIndexListDataディレクティブを受信した後の、listVersionを指定しないすべてのSendIndexListDataディレクティブ

operations

考えられる更新操作の列挙値です。

InsertItem

指定されたindexのデータソースに1つのitemを挿入します。

リストの範囲内に項目を挿入したり、リストの末尾に項目を追加したりできます。隣接していないインデックスに項目を挿入しようとすると、エラーが発生します。たとえば、現在のインデックスの範囲がM～Nの場合、M～N＋1の範囲に項目を挿入できます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたInsertItem操作では、次の処理が実行されます。

• 位置5に新しいitemを挿入します。
• 既存の項目5～9のindexを6～10に更新します。元の項目5は6に、元の項目6は7になり、以降も同様になります。
• データソースのmaximumExclusiveIndexプロパティを10から11に更新します。

InsertMultipleItems

指定されたindexにitemsの配列を挿入します。

リストの範囲内に項目を挿入したり、リストの末尾に項目を追加したりできます。隣接していないインデックスに項目を挿入しようとすると、エラーが発生します。たとえば、現在のインデックスの範囲がM～Nの場合、M～N＋1の範囲に項目を挿入できます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定され、itemsで2つの新しい項目が指定されているInsertMultipleItem操作では、次の処理が実行されます。

• 位置5と6に2つの新しい項目を挿入します。
• 元の項目5～9のindexに2を加算します。元の項目5は7に、元の項目6は8になり、以降も同様になります。
• データソースのmaximumExclusiveIndexプロパティを10から12に更新します。

SetItem

指定されたindexの項目を指定されたitemに置き換えます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたSetItem操作では、次の処理が実行されます。

• 位置5の既存の項目を新しいitemに置き換えます。

DeleteItem

指定されたindexの項目を削除します。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたDeleteItem操作では、次の処理が実行されます。

• 位置5の既存の項目を削除します。
• 既存の項目6～9のindexを5～8に更新します。元の項目6は5に、元の項目7は6になり、以降も同様になります。
• データソースのmaximumExclusiveIndexプロパティを10から9に更新します。

DeleteMultipleItems

指定されたindexを開始点として、データソースから指定されたcount数の項目を削除します。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定され、countが2に設定されたDeleteMultipleItems操作では、次の処理が実行されます。

• 位置5と6の元の項目を削除します。
• 元の項目7～9のindexから2を引きます。元の項目7の新しいインデックスは5になり、元の項目8は6に、元の項目9は7になります。
• データソースのmaximumExclusiveIndexプロパティを10から8に更新します。

リクエスト

次の表は、Alexa.Presentation.APLインターフェースで使用できるリクエストの一覧です。「ウィジェットのサポート」列は、デバイスにインストールされているウィジェットからスキルにAlexaがリクエストを送信できるかどうかを示しています。

LoadIndexListDataリクエスト

AlexaはスキルにLoadIndexListDataリクエストを送信して、dynamicIndexListデータソースのリスト項目をさらにリクエストします。たとえば、以前に読み込まれた項目の最後の方までユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadIndexListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2020-03-12T19:47:02Z",
    "locale": "ja-JP",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "startIndex": 20,
    "count": 10
  }
}

有効な応答

LoadIndexListDataリクエストには、SendIndexListDataディレクティブを使用して応答できます。

LoadTokenListDataリクエスト

AlexaはスキルにLoadTokenListDataリクエストを送信して、dynamicTokenListデータソースの次のページ項目をリクエストします。たとえば、以前に読み込まれた項目の最後近くまでユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadTokenListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2021-03-12T19:47:02Z",
    "locale": "ja-JP",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "pageToken": "myListPage2"
  }
}

有効な応答

LoadTokenListDataリクエストには、SendTokenListDataディレクティブを使用して応答できます。

RuntimeErrorリクエスト

APL処理中に発生したエラーをスキルに通知するために送信されます。このリクエストは通知専用です。スキルはRuntimeErrorリクエストに応答を返すことができません。

{
  "type": "Alexa.Presentation.APL.RuntimeError",
  "token": "developer-provided-token",
  "errors": [
    {
      "type": "LIST_ERROR",
      "reason": "LIST_INDEX_OUT_OF_RANGE",
      "listId": "my-list-id",
      "listVersion": 3,
      "operationIndex": 3,
      "message": ""
    }
  ]
}

errors

type

ポリモーフィズムなエラータイプのインジケーターです。各エラータイプにはタイプ固有のパラメーターを指定できます。

reason

エラータイプ別の失敗の理由です。すべてのタイプで使用できる汎用的な値は次のとおりです。

• INTERNAL_ERROR - Alexaサービスの予期しない問題です。

LIST_ERROR

考えられる理由については、 エラーの例を参照してください。

UserEventリクエスト

デバイス上のイベントがSendEventコマンドをトリガーすると、AlexaはスキルにAlexa.Presentation.APL.UserEventリクエストを送信します。これにより、デバイスでのユーザーの操作への応答として、スキルサービスがメッセージを受信します。ドキュメント内のコンポーネントでイベントハンドラーを使用すると、SendEventをトリガーできます。たとえば、TouchWrapperコンポーネントにonPressイベントハンドラーが含まれている場合、このハンドラーをSendEventコマンドに設定すると、ユーザーがViewport上のコンポーネントをタッチしたときにUserEventリクエストを取得できます。

UserEventリクエストには、SendEventコマンドをトリガーしたコンポーネントとイベントに関する情報が含まれています。コンポーネントのイベントハンドラーでSendEventを定義する場合、対応するUserEventリクエストで取得する情報を指定できます。これは、コード内のイベントハンドラーで使用します。

UserEventプロパティ

標準APLドキュメントのUserEventリクエストの例

次の例は、ユーザーがSequenceコンポーネントによってレンダリングされたTouchWrapperコンポーネントのいずれかをタッチするか、リモコンのDパッドで押したときに、スキルにイベントを送信するAPLドキュメントの一部を示しています。

{
  "type": "Sequence",
  "id": "myCustomSequence",
  "height": "100vh",
  "data": "${payload.templateData.properties.animalList}",
  "numbered": true,
  "item": {
    "type": "TouchWrapper",
    "id": "animalListTouchWrapper",
    "item": {
      "type": "Text",
      "text": "${data.textToShow}"
    },
    "onPress": [
      {
        "type": "SendEvent",
        "arguments": [
          "listItemPressed",
          "${ordinal}",
          "${data.dataToSend}"
        ]
      }
    ]
  }
}

Sequenceは、templateDataというデータソースを使用して、Sequence内の一連の項目を表示し、UserEventに含めるデータを定義します。次の例は、このデータソースの説明を示しています。

{
  "templateData": {
    "properties": {
      "animalList": [
        {
          "textToShow": "ツチブタ",
          "dataToSend": "animalKey123"
        },
        {
          "textToShow": "アードウルフ",
          "dataToSend": "animalKey124"
        },
        {
          "textToShow": "ヒヒ",
          "dataToSend": "animalKey202"
        }
      ]
    }
  }
}

上記の例では、SendEventコマンドのarguments配列で3つの項目が指定されています。

• 静的テキストの「listItemPressed」。
• データバインディングコンテキストのordinalプロパティ。TouchWrapperがSequenceの子コンポーネントであるため、このプロパティを使用できます。
• データソース内の、項目のdataToSendプロパティの値。

したがって、ユーザーが2番目の項目（「アードウルフ」）を選択すると、スキルは次のようなUserEventリクエストを受け取ります。

{
  "version": "1.0",
  "session": {},
  "context": {},
  "request": {
    "type": "Alexa.Presentation.APL.UserEvent",
    "requestId": "amzn1.echo-api.request.1",
    "token": "token-provided-with-RenderDocument",
    "timestamp": "2020-01-17T16:48:11Z",
    "locale": "ja-JP",
    "arguments": [
      "listItemPressed",
      2,
      "animalKey124"
    ],
    "components": {},
    "source": {
      "type": "TouchWrapper",
      "handler": "Press",
      "id": "animalListTouchWrapper"
    },
  }
}

ウィジェットのUserEventリクエストの例

次の例は、ウィジェットから送信されるUserEventリクエストを示しています。リクエストには、生成されたtokenとpresentationUriが含まれます。

{
  "request": {
    "type": "Alexa.Presentation.APL.UserEvent",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2022-04-07T21:51:19Z",
    "locale": "ja-JP",
    "arguments": [
      {
        "itemId": "ItemIDForSmokedWildSalmon"
      }
    ],
    "components": {},
    "source": {
      "type": "TouchWrapper",
      "handler": "Press",
      "id": "saveItemButton",
      "value": false
    },
    "token": "f1cf2427-1-1-1-1",
    "presentationUri": "widget://amzn1.ask.skill.1_development/MyWidgetSandbox/f1cf2427-1-1-1-1"
  }
}

UserEventのコンポーネントデータを取得する

sourceプロパティとargumentsプロパティで指定されたデータに加えて、Viewportに表示されるほかのコンポーネントに関する情報を取得することもできます。情報を取得するには、各コンポーネントにidプロパティを持つ識別子を割り当てます。次に、SendEventコマンドでcomponents配列に含める各コンポーネントのidを指定します。

たとえば、各コンポーネントにtrueまたはfalseのchecked状態が含まれている場合、SetValueコマンドを使用すると、ユーザー操作への応答としてchecked状態を変更できます。次のAlexaButtonの例では、ユーザーがボタンを選択したときにchecked状態を切り替え、ボタンのテキストを変更します。

{
  "type": "AlexaButton",
  "id": "idForTheToggleButton",
  "buttonText": "切り替えボタン：false",
  "primaryAction": [
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "checked",
      "value": "${!event.source.value}"
    },
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "buttonText",
      "value": "切り替えボタン：${!event.source.value}"
    }
  ],
  "spacing": "@spacingSmall",
  "alignSelf": "center"
}

次に、ドキュメント内の別のTouchWrapperがSendEventをトリガーして、次の例に示すように、ボタンIDidForTheToggleButtonをcomponents配列に含めます。

{
  "type": "TouchWrapper",
  "id": "idForTheTouchWrapper",
  "spacing": "@spacingSmall",
  "alignSelf": "center",
  "onPress": [
    {
      "type": "SendEvent",
      "arguments": [
        "textWasPressed",
        "このデータをスキルに送信する"
      ],
      "components": [
        "idForTheToggleButton",
        "idForTheTextComponent"
      ]
    }
  ],
  "item": {
    "type": "Text",
    "id": "idForTheTextComponent",
    "color": "@colorAccent",
    "text": "クリックすると、スキルにUserEventが送信されます。"
  }
}

ユーザーは切り替えボタンを繰り返し選択して、その状態をtrueとfalseのいずれかに切り替えられます。ユーザーが「クリックすると...」テキストを選択すると、スキルは次のUserEventを受信します。componentsには、現在のchecked状態を持つidForTheToggleButtonが含まれています。

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2020-01-20T22:46:04Z",
  "locale": "ja-JP",
  "arguments": [
    "textWasPressed",
    "このデータをスキルに送信する"
  ],
  "components": {
    "idForTheTextComponent": "クリックすると、スキルにUserEventが送信されます。",
    "idForTheToggleButton": true
  },
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "idForTheTouchWrapper"
  },
  "token": "token-provided-with-RenderDocument"
}

サンプルドキュメント： UserEventのコンポーネントを取得する  

{
    "type": "APL",
    "version": "2024.3",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "2024.3"
        }
    ],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "paddingTop": "@spacing2XLarge",
                "paddingLeft": "@marginHorizontal",
                "paddingRight": "@marginHorizontal",
                "width": "100vw",
                "height": "100vh",
                "items": [
                    {
                        "type": "AlexaButton",
                        "id": "idForTheToggleButton",
                        "buttonText": "切り替えボタン：false",
                        "primaryAction": [
                            {
                                "type": "SetValue",
                                "componentId": "idForTheToggleButton",
                                "property": "checked",
                                "value": "${!event.source.value}"
                            },
                            {
                                "type": "SetValue",
                                "componentId": "idForTheToggleButton",
                                "property": "buttonText",
                                "value": "切り替えボタン：${!event.source.value}"
                            }
                        ],
                        "spacing": "@spacingSmall",
                        "alignSelf": "center"
                    },
                    {
                        "type": "TouchWrapper",
                        "id": "idForTheTouchWrapper",
                        "spacing": "@spacingSmall",
                        "alignSelf": "center",
                        "onPress": [
                            {
                                "type": "SendEvent",
                                "arguments": [
                                    "textWasPressed",
                                    "このデータをスキルに送信する"
                                ],
                                "components": [
                                    "idForTheToggleButton",
                                    "idForTheTextComponent"
                                ]
                            }
                        ],
                        "item": {
                            "type": "Text",
                            "id": "idForTheTextComponent",
                            "color": "@colorAccent",
                            "text": "クリックすると、スキルにUserEventが送信されます。"
                        }
                    }
                ]
            }
        ]
    }
}

ASK SDKでUserEventのハンドラーを作成する方法の例については、スキルコードにAPLサポートを追加するのUserEventリクエストを処理するを参照してください。

ウィジェットの対話モード

ユーザーイベントの対話モードは、そのイベントへの応答に使用できる機能を定義します。このモードは、SendEventコマンドのflagsプロパティで、interactionModeフラグを使用して設定します。

interactionModeフラグには、次の2つのうちいずれかの値を指定できます。

• STANDARD - ウィジェットはスキルエクスペリエンス全体を開始できます。たとえば、スキルを起動してスキルセッションを続行するボタンを含めることができます。標準の対話モードでは、LaunchRequestやIntentRequestの場合と同様に、スキルはリクエストに対して標準的な任意の応答を返すことができます。
• INLINE - ウィジェットはイベントに基づいてアクションを実行できますが、スキルエクスペリエンス全体を開始したり、出力音声を返したりすることはできません。たとえば、後で使用できるようにデータを保存したり、ウィジェットに表示されているデータをサイレントに更新したりするボタンでは、インラインモードを使用します。インラインの対話モードが設定されたイベントでは、送信できる応答のタイプが制限されます。

有効な応答タイプ

標準のAPLドキュメントの場合、スキルはUserEventリクエストに対して、標準的な応答で応答できます。Dialog.Delegateを除き、すべてのカスタムスキルディレクティブを含めることができます。

ウィジェットから送信されるUserEventへの有効な応答は、イベントの対話モードによって異なります。

• STANDARD
  • 応答は、音声とディレクティブを含む標準的な応答にすることができます。
  • Dialog.Delegateを除き、すべてのカスタムスキルディレクティブを含めることができます。
• INLINE（デフォルト）
  • shouldEndSessionフラグはtrueにする必要があります。スキルセッションは応答で終了します。
  • 応答に出力音声を含めることはできません。
  • 応答には、Alexa.Presentation.APL.ExecuteCommandsディレクティブ以外のスキルディレクティブを含めることはできません

どちらのモードでも、UserEventのハンドラーでデータストアREST APIを使用すると、ウィジェットのデータストアを更新できます。詳細については、データストアREST APIリファレンスを参照してください。

エラーの例

エラーが発生すると、スキルはRuntimeErrorリクエストを受信します。

以下の表に、起こりうるエラーの例をまとめます。

スキルリクエストのViewportオブジェクト

スキルに送信されるリクエストには必ず、ユーザーのデバイスでサポートされているViewportに関する情報が含まれています。この情報をコードで使用して、適切な応答を作成できます。

画面付きデバイスの場合、Viewport情報はcontext.Viewportオブジェクトに格納されています。

また、Viewport情報は、viewportプロパティのデータバインディングコンテキストでも使用できます。データバインディングコンテキストで使用可能な具体的な情報は、スキルリクエストで使用可能な情報とは異なります。詳細については、データバインディングコンテキストのViewportオブジェクトを参照してください。

• スキルコードにViewport情報が必要な場合は、スキルリクエストでcontext.Viewportオブジェクトを使用します。
• APLドキュメントにViewport情報が必要な場合は、データバインディングコンテキストでviewportプロパティを使用します。たとえば、特定のViewportでのみ特定のコンポーネントを表示するためのwhen条件を作成します。データバインディングコンテキストのViewportオブジェクトを参照してください。

次の例では、context.Viewportオブジェクトを使用したスキルリクエストを示しています。説明を簡潔にするために、一部の詳細は省略されています。

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [
      {
        "type": "APL",
        "id": "main",
        "shape": "RECTANGLE",
        "dpi": 213,
        "presentationType": "STANDARD",
        "canRotate": false,
        "configuration": {
          "current": {
            "mode": "HUB",
            "video": {
              "codecs": [
                "H_264_42",
                "H_264_41"
              ]
            },
            "size": {
              "type": "DISCRETE",
              "pixelWidth": 1280,
              "pixelHeight": 800
            }
          }
        }
      }
    ],
    "Viewport": {
      "experiences": [
        {
          "arcMinuteWidth": 346,
          "arcMinuteHeight": 216,
          "canRotate": false,
          "canResize": false
        }
      ],
      "mode": "HUB",
      "shape": "RECTANGLE",
      "pixelWidth": 1280,
      "pixelHeight": 800,
      "dpi": 213,
      "currentPixelWidth": 1280,
      "currentPixelHeight": 800,
      "touch": [
        "SINGLE"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    },
    "Extensions": {
      "available": {
        "aplext:backstack:10": {}
      }
    },
    "System": {}
  },
  "request": {}
}

viewportプロパティ

viewportオブジェクトでは、次のプロパティが定義されています。

experiences

experiencesプロパティには、デバイスがサポートしているエクスペリエンスのタイプのリストが含まれています。エクスペリエンスのタイプは、Viewportがサポートするモードによって異なります。この情報を使用して、特定のエクスペリエンスでのスキルの動作を最適化できます。たとえば、タブレットデバイスには2つの異なるエクスペリエンスがあります。1つはタブレットがドックに装着されている場合、もう1つはユーザーがタブレットを手に持っている場合です。これらの場合、デバイスの所有者が自由にエクスペリエンスを切り替えられるように、スキルの視覚応答は両方のエクスペリエンスに合わせて最適化される必要があります。

experienceプロパティ

experiencesプロパティは、廃止されたarcMinuteWidthプロパティとarcMinuteHeightプロパティについても報告します。これらのプロパティは利用可能ですが、現在は廃止されています。デバイスの視聴距離と利用可能なモダリティを確認するには、代わりにmodeプロパティを使用してください。

mode

デバイスのタイプを表します。

pixelHeightおよびpixelWidth

pixelHeightおよびpixelWidthプロパティは、高さと幅が上限の場合にViewportで表示されるピクセル数を表します。これらの値は静的なデバイスの向きとみなされ、Viewportの領域が現在ほかのアプリケーションで使用されているかどうかにかかわらず、Viewport全体のサイズを表します。

currentPixelWidthおよびcurrentPixelHeight

currentPixelWidthおよびcurrentPixelHeightプロパティは、Alexaがエクスペリエンスをレンダリングできる縦横のピクセル数を表します。これらの値も静的なデバイスの向きとみなされます。

shape

画面のshapeは、ROUND、RECTANGLEのどちらかに設定されます。

dpi

画面非依存ピクセル（dp）は、携帯電話を見るときの距離で画面を持ち、画面のピクセル密度が1インチ（3cm）あたり約160ピクセルであると仮定した場合の画面のビジュアルサイズを表す測定単位です。物理的な大きさが同じ2つの画面を同じ距離から見た場合、画面の実際のピクセル密度にかかわらず、2つの画面のdpディメンションはほぼ同じになります。

Viewportのdpi（インチあたりのドット数）とは、人が見たとおりのポイントまたはピクセルのサイズを表した値であり、画面の実際のインチあたりのピクセル数とは異なります。dpiを求める公式は次のとおりです。

dpi = 160 * (pixelSize / dpSize)

簡略化のため、dpiの値は120、160、240、320などのバケットにまとめられています。

touch

touchプロパティは、デバイスがサポートするタッチ入力の種類を表します。touch配列には、次の値を含めることができます。

• SINGLE - デバイスがシングルタッチ入力をサポートしていることを示します。

keyboard

keyboardプロパティは、Viewportの操作に使用できる物理ボタン入力メカニズムを表します。keyboard配列には、次の値を含めることができます。

• DIRECTION - 上下左右の方向の入力のほか、現在の位置にあるものを選択できるボタンがあります。

video

videoプロパティは、デバイスでのビデオ再生に使用できる技術を詳細に指定します。videoプロパティを使用して、APL応答に送信するビデオリソースの種類を決定します。たとえば、スキルのAPL応答が、デバイスがサポートするビデオコーデックのレベルに応じて、異なるエンコードのビデオリソースを返す場合があります。

画面付きのデバイスでも、ビデオ再生をサポートしていないものもあることに注意してください。この場合、videoプロパティはありません。スキルにビデオが含まれる場合、このプロパティを確認して、ビデオをサポートしていないデバイス向けに適切なエクスペリエンスを提供するようにしてください。ビデオをサポートしていないデバイスにVideoを送信する場合は、そのコンポーネントは画面上に表示されますが、コンテンツは表示されないため、ユーザーには画面に空白の領域が見えることになります。

videoプロパティ

コードのViewport情報にアクセスする

Alexa Skills Kit SDKには、スキルリクエストコンテキストのデータを使用してデバイスのViewportプロファイルを計算する関数が含まれています。これらの関数は廃止になっており、推奨されません。さまざまなデバイスに対応するAPLドキュメントを作成するには、代わりにViewportプロファイルパッケージの@viewportProfileリソースを使用してください。

@viewportProfileリソースおよびレスポンシブ対応ドキュメントの詳細については、以下を参照してください。

• Viewportプロファイル
• レスポンシブ対応のAPLドキュメントを作成する

以下の関数は廃止になっており、推奨されません。

• Node - getViewportProfile
• Python - get_viewport_profile
• Java - ViewportUtils.getViewportProfile

Alexa Skills Kitで廃止になった機能の一覧については、廃止された機能を参照してください。

スキルリクエストのAPL視覚コンテキスト

Alexa Presentation Language（APL）の視覚コンテキストは、ユーザーがインテントを呼び出したりユーザーイベントをトリガーしたりした場合に、画面に表示されるコンテンツに関する情報をスキルに提供します。スキルはコンテキストを使用して、リストのどの部分を画面に表示するかなど、画面上の要素の状態を確認できます。

ユーザーのデバイスが画面付きで、スキルが画面にRenderDocumentディレクティブで送信したAPLドキュメントを表示している場合、スキルに送信されるリクエストには視覚コンテキストが含まれます。

視覚コンテキストは、リクエストの最上位にあるcontextプロパティ内のAlexa.Presentation.APLプロパティにあります。

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [],
    "Alexa.DataStore.PackageManager": {
      "installedPackages": []
    },
    "Viewport": {},
    "Extensions": {},
    "System": {},
    "Alexa.Presentation.APL": {
      "token": "helloworldWithButtonToken",
      "version": "AriaRuntimeLibrary-2023.2.449.0",
      "componentsVisibleOnScreen": [
        {
          "uid": ":1000",
          "position": "960x480+0+0:0",
          "type": "text",
          "tags": {
            "viewport": {}
          },
          "children": [
            {
              "id": "fadeHelloTextButton",
              "uid": ":1002",
              "position": "273x76+344+360:0",
              "type": "text",
              "tags": {
                "focused": false,
                "clickable": true
              },
              "entities": []
            }
          ],
          "entities": []
        }
      ]
    }
  },
  "request": {}
}

視覚コンテキストで提供されるオブジェクトの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。

サービスインターフェースのリファレンス（JSON）

リクエストの形式と標準のリクエストタイプ：

• カスタムスキルのJSONインターフェースのリファレンス
• 標準のリクエストタイプのリファレンス

インターフェース：

• Alexa.Presentation.APLインターフェース（このドキュメント）
• Alexa.Presentation.APLTインターフェース
• Alexa.Presentation.HTMLインターフェース
• AudioPlayerインターフェース
• Connectionsインターフェース
• Dialogインターフェース
• Messagingインターフェース
• PlaybackControllerインターフェース
• VideoAppインターフェース

関連トピック

• ASK SDK v2でのAlexa Presentation Languageの使用
• APLドキュメント
• SendEventコマンド
• スキルに視覚要素とオーディオを追加する

最終更新日: 2025 年 11 月 11 日