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

Note: Sign in to the developer console to build or publish your skill.

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

視覚コンテキストについて

APL視覚コンテキストは、ユーザーがデバイス上で見るコンテンツに関してスキルに送信される情報です。コンテキストは、ユーザーに表示されるコンテンツに関する構造情報とセマンティック情報の両方を提供します。

構造情報：画面上の視覚コンポーネントの表示方法 - 例：左側に画像、右側にスクロールテキスト、テキストの下に2つのボタンがあります。
セマンティック情報：コンポーネントが表す内容 - 例：画像は特定のブランドのプロテインバーの箱の画像で、テキストにはこれらのプロテインバーの説明があり、左のボタンは「詳細情報」ボタン、右のボタンは「今すぐ購入」ボタンです。

APLランタイムは構造コンテキストを構築して報告します。このセマンティックコンテキストをわかりやすくするために、コンポーネントの意味を説明する情報をAPLドキュメントに記載します。コンポーネントのセマンティックデータは、次の2つの場所で定義できます。

コンポーネントのidプロパティ - 視覚コンテキストには、コンポーネントに指定したidが含まれます。
コンポーネントのentitiesプロパティ - 視覚コンテキストには、コンポーネントに指定したentitiesが含まれます。

上記の例では、プロテインバーの画像のentitiesに製品の識別子が含まれている場合があります。2つのボタンのコンポーネントのidは、ボタンを識別するためにbuttonTellMeMoreとbuttonBuyNowのように指定できます。

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

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

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

プロパティ	型	説明
`token`	文字列	デバイスに表示されるドキュメントを識別するトークンです。ドキュメントを表示するために返す`RenderDocument`ディレクティブで`token`を定義します。
`version`	文字列	視覚コンテキストを報告したAPLランタイムのバージョンです。
`componentsVisibleOnScreen`	配列	ユーザーがスキルへのリクエストをトリガーしたときに画面に表示されていた要素が含まれます。要素内のプロパティの詳細については、コンテキストのコアプロパティを参照してください。

次の例は、fadeHelloTextButtonというIDのタッチ可能な要素が画面に表示されていたときの視覚コンテキストを示しています。

{
  "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": {}
}

コンテキストのコアプロパティ

componentsVisibleOnScreen配列は、視覚要素を階層状に整理します。特定の要素には子要素を含めることができます。たとえば、画面のスクロール領域を表す要素には、スクロール領域内に表示されるリスト項目を表す子要素が1つ以上含まれている場合があります。

階層内の各要素は、APLドキュメント内の1つのコンポーネントに対応します。ただし、コンテキストにはAPLドキュメントで定義されているすべてのコンポーネントが含まれるわけではありません。詳細については、要素階層を生成するためのルールを参照してください。

以下の表は、コンテキストに含まれる要素のコアプロパティの定義です。

プロパティ	型	デフォルト	ソース	説明
`children`	配列	[]	計算	子要素の配列です。
`entities`	配列	[]	コンポーネントの`entity`プロパティ	コンポーネントからコピーされたエンティティデータの配列です。
`id`	文字列	""	コンポーネントの`id`プロパティ	コンポーネントのIDです。
`position`	文字列	必須	計算	ユーザーから見た要素のグローバル位置です。
`role`	文字列	""	コンポーネントの`role`プロパティ	コンポーネントの役割または目的です。
`tags`	マップ	必須	計算	任意の数の有効な要素タグです。
`transform`	変換	[]	コンポーネントの`transform`プロパティ	位置に対して適用される視覚的変換です。
`type`	`graphic`、`text`、`mixed`、`video`、`empty`のいずれか	必須	計算	要素の外観を表します。
`uid`	文字列	必須	ランタイムによって生成	ランタイムで生成されたコンポーネントの一意のIDです。
`visibility`	数値	1.0	計算	要素の相対的な可視性です。

スペースを節約するために、コンテキストではデフォルト値を含むプロパティが省略されます。たとえば、デバイスにTextコンポーネントを含む次のTouchWrapperコンポーネントが表示されているとします。

{
  "type": "TouchWrapper",
  "id": "idForTheTouchWrapper",
  "item": [
    {
      "type": "Text",
      "id": "idForTextWrappedInTouchWrapper",
      "text": "TouchWrapperでラップされたTextコンポーネント",
      "inheritParentState": true,
      "style": "touchableText"
    }
  ],
  "onPress": []
}

TouchWrapperは、ユーザーがスキルにリクエストを送信するインテントを呼び出すと、画面上に完全に表示されます。コンテキストは、次の例に示すように要素を報告します。

{
  "id": "idForTheTouchWrapper",
  "uid": ":1022",
  "position": "952x51+35+224:0",
  "type": "text",
  "tags": {
    "focused": false,
    "clickable": true
  },
  "entities": []
}

TouchWrapperは完全に表示されているため、visibilityプロパティにはデフォルト値である1が格納されます。したがって、Alexaはこのプロパティを省略します。また、TouchWrapperにはtransformプロパティの値が存在しないため、Alexaはこのプロパティも省略します。さらに、このTouchWrapperの子コンポーネントであるTextは、コンテキストに含めるための要件をいずれも満たしていないため、Alexaはchildrenプロパティも省略しています。

children

この要素に論理的に分類される要素を含む配列です。たとえば、スクロール可能なリストにはリスト内に複数の子要素が含まれる場合があります。この要素は、配列内の子の順序を定義します。

コンテキスト内の要素に報告される子要素がない場合、childrenプロパティは省略されます。

要素階層を生成すると、報告されないコンポーネントの子がコンポーネントの親にアタッチされます。コンポーネントが報告されない場合の詳細については、要素階層を生成するためのルールを参照してください。

たとえば、ドキュメントには次のようなコンポーネント階層が含まれる場合があります。

Container "A" - 報告される
  Container "B" - 報告されない
    Text "C" - 報告される
    Image "D" - 報告されない
    Container "F" - 報告されない
      Text "G" - 報告される
      Text "H" - 報告される

このコンポーネントセットは、コンテキスト内で次の要素階層を生成します。

Element "A", type "mixed"
  Element "C", type "text"
  Element "G", type "text"
  Element "H", type "text"

この階層では、コンテキストに「B」と「F」は含まれないため、「Container B」と「Container F」の子要素は「A」内に含まれます。

entities

コンポーネントからコピーされたエンティティデータの配列です。このデータは不透明です。コンポーネントのentitiesプロパティにデータを提供して、コンポーネントの意味を説明できます。

コンポーネントのentitiesプロパティを設定するときは、オブジェクトの配列を指定します。各オブジェクトには、id、type、valueの各プロパティを指定できます。その他のプロパティは視覚コンテキストに含められません。

id

APLドキュメントで指定されているコンポーネントのidプロパティです。対応するコンポーネントにidプロパティがない場合、コンテキスト内の要素はidプロパティを省略します。

uid

APLランタイムによって生成された識別子です。uidは各コンポーネントに割り当てられます。値は不透明な文字列で、ドキュメントのスコープ内で一意であり、割り当てられたid値と競合しないことが保証されます。コンテキスト内の各要素には常にuidプロパティが含まれます。

position

画面上の要素の位置を、width、height、x-position、y-position、layerの5要素のタプルの形式で指定します。これらの値はグローバル座標であり、親要素からの相対値ではありません。値は、変換を適用する前の項目のデフォルトまたは静止位置です。変換の詳細については、コンポーネントのtransformプロパティを参照してください。

簡潔にして解釈しやすくするために、位置は1つの文字列になっています。

"position": "<幅>x<高さ>[+-]<X位置>[+-]<Y位置>:<レイヤー>"

報告される数値は次元を持たない非負の整数です。X位置とY位置は、ビューポートの左上から測定されます。レイヤー値は次の要件を満たす必要があります。

同じレイヤーを持つ要素がほかに存在しない。
2つの要素が重なっている場合、レイヤー値の大きい要素が、レイヤー値の小さい要素の上に描画されている。

報告される位置は常にグローバル座標です。グローバル座標を使用すると、位置はユーザーの視点に基づいて決定されます。任意の2つの要素の相対位置を比較することもできます。

次の例は、position値が画面上のさまざまな位置をどのように表すかを示しています。

1280x800+0+0:0     // 1280x800dp画面上の最上位要素
620x780+10+10:1    // 上記の最上位要素の左側の列
620x780+650+10:2   // 上記の最上位要素の右側の列

コンテキスト内の各要素には常にpositionプロパティが含まれます。

role

roleプロパティは、コンポーネントのroleプロパティの値です。コンポーネントにroleプロパティの値が設定されていない場合、roleプロパティは省略されます。

transform

この要素に適用された2D同次変換行列を含む6要素の配列です。変換座標系の中心はコンポーネントの中心です。変換配列は、[A,B,C,D,Tx,Ty]という順序になります。

変換が恒等変換でない場合、transformプロパティが報告されます。

type

ユーザーが要素をどのように認識するかを表す列挙値です。以下の表に、有効なtype値を示します。

型	説明
`empty`	コンテンツが表示されていない空のコンポーネントです。
`graphic`	ビットマップ画像またはベクターグラフィックです。
`mixed`	グラフィック、ビデオ、テキストの組み合わせです。
`text`	ユーザーが読める形式のテキストです。
`video`	ビデオプレーヤーです。

Alexaは、次の表に示すルールを使用して要素のtypeを生成します。

コンポーネント	ルール
`Container`	表示されるすべての子の組み合わせ。たとえば、表示されているすべての子コンポーネントが`text`にマップされている場合、`Container`のタイプは`text`になります。表示されている子が異なるタイプの要素にマップされている場合、`Container`のタイプは`mixed`になります。
`EditText`	`text`。
`Frame`	子のタイプ。
`FlexSequence`	表示されるすべての子の組み合わせ。
`GridSequence`	表示されるすべての子の組み合わせ。
`Image`	`graphic`。
`Pager`	現在のページの子のタイプ。
`ScrollView`	表示されるすべての子の組み合わせ。
`Text`	`text`。
`TouchWrapper`	子のタイプ。
`Sequence`	表示されるすべての子の組み合わせ。
`VectorGraphic`	`graphic`。
`Video`	`video`。

text、graphic、videoの任意の2つの組み合わせがmixedです。コンポーネントに有効なコンテンツがなく、子もない場合、typeプロパティはデフォルトでemptyになります。コンテキスト内の要素には常にtypeプロパティが含まれます。

visibility

visibilityプロパティは、ユーザーにオブジェクトがどの程度見えるかを概算したものです。visibilityは、親要素に表示されている要素のバウンディングボックスのパーセンテージに要素の不透明度を掛けたものとして定義されます。

たとえば、垂直方向にスクロールするリストで、リストの最後の項目が画面から50%はみ出しており、不透明度が80%になっているとします。この項目のvisibilityは40%となり、0.4と報告されます。

visibilityの計算では、適用されたコンポーネントのtransform値は考慮されません。また、この計算では、コンポーネントがその上にある子コンポーネントによって覆い隠される可能性も考慮されません。

displayプロパティがinvisibleまたはnoneのコンポーネントは、visibilityが0になります。

visibilityが0より大きい場合は、コンテキスト内の要素にvisibilityプロパティが含まれます。値が1（デフォルト、完全に表示）の場合、要素はvisibilityプロパティを省略します。特定の状況で値が0の場合、要素にはvisibilityプロパティが含まれます。visibilityが0の項目が報告されるタイミングの詳細については、要素階層を生成するためのルールを参照してください。

要素タグ

要素タグは、要素に関する追加情報を提供します。コンテキストに含まれるほとんどの要素には、少なくとも1つのタグが含まれています。要素には複数のタグを設定できます。

以下の表に、利用可能なタグを示します。

タグ	型	説明	作成元
`checked`	ブール値	2つの状態を持つコンポーネントのチェック状態です。	`checked`状態が`true`に設定された任意のコンポーネント
`clickable`	ブール値	ユーザーが押すことができるボタンまたは項目です。	タッチ可能なコンポーネント
`disabled`	ブール値	このコンポーネントが無効な場合はtrueになります。	`disabled`状態のコンポーネント
`focused`	ブール値	フォーカスを取得できるコンポーネントのフォーカス状態です。	以下のコンポーネント： `EditText` `GridSequence` `Pager` `ScrollView` `Sequence` `TouchWrapper` `VectorGraphic`
`list`	オブジェクト	項目の順序付きリストです。	`Sequence`、`GridSequence`
`listItem`	オブジェクト	`Sequence`の子に関する情報です。	`Sequence`または`GridSequence`の子コンポーネント
`media`	オブジェクト	メディアプレーヤーです。	`Video`
`ordinal`	整数	視覚的に番号が付けられた要素です。	`Sequence`、`GridSequence`、`Container`のいずれかの子コンポーネント
`pager`	オブジェクト	オブジェクトのコレクションが1つずつ表示されます。	`Pager`
`scrollable`	オブジェクト	スクロールできる画面の領域です。	`ScrollView`、`Sequence`、`GridSequence`
`spoken`	ブール値	音声合成で読み上げられる画面の領域です。	`speech`プロパティを持つコンポーネント
`viewport`	オブジェクト	ドキュメントがレンダリングされる画面全体です。	最上位コンポーネント

各タグは、基本データ型（Boolean、String、Integer）か、より詳細な情報を含むオブジェクトデータ型のいずれかです。

checked

コンポーネントのchecked状態がtrueであることを示すブール値のタグです。すべてのコンポーネントがチェック状態になる可能性があるため、どのタイプのコンポーネントでもcheckedタグが報告される可能性があります。

{
  "id": "XXXX",
  "uid": ":1234",
  "position": "10x10+0+0:0",
  "type": "graphic",
  "tags": {
    "checked": true
  }
}

inheritParentStateプロパティがtrueに設定されているコンポーネントは、checkedタグを報告しません。スペースを節約するために、コンテキスト内の要素は値がtrueの場合にcheckedタグを報告します。

clickable

このコンポーネントを「クリック」できることを示すブール値のタグです。つまり、ユーザーはタッチ、キーボード、リモコンを使用してコンポーネントをアクティブ化できます。すべてのタッチ可能なコンポーネントはクリック可能です。

{
  "id": "XXXX",
  "uid": ":1234",
  "position": "10x10+0+0:0",
  "type": "mixed",
  "tags": {
    "clickable": true,
    "focused": false
  }
}

タッチ可能なコンポーネントの場合、コンテキスト内の要素にはclickableタグが含まれます。タッチ可能なコンポーネントがdisabled状態である場合、このタグはtrueを返します。

disabled

ユーザーがこのコンポーネントを操作できないことを示すブール値のタグです。クリックやフォーカスを受け付けないコンポーネントを含め、すべてのコンポーネントはdisabled状態に設定できます。次の例は、checked状態で無効になっているTextコンポーネントについて報告された要素を示しています。

{
  "id": "XYZZY",
  "uid": ":1235",
  "position": "100x50+10+10:5",
  "type": "text",
  "tags": {
    "disabled": true,
    "checked": true
  }
}

checked状態とは異なり、disabled状態はinheritParentStateプロパティが設定されているコンポーネントについて報告されます。スペースを節約するために、disabledタグはtrueの場合に報告されます。

focused

コンポーネントがキーボードフォーカスを取得できることを示すブール値のタグです。タグの値は、コントロールの現在の状態を示します。たとえば、フォーカスのないタッチ可能な項目では、focusedタグがfalseとして報告されます。

{
  "id": "XXXX",
  "uid": ":1236",
  "position": "10x10+0+0:0",
  "type": "text",
  "tags": {
    "focused": false,
    "clickable": true
  }
}

コンポーネントがフォーカスを取得できる場合、コンテキストにはfocusedタグが含まれます。次のコンポーネントはフォーカスを取得できます。

focusedタグは、コンポーネントにフォーカスがある場合はtrue、コンポーネントにフォーカスがない場合はfalseを報告します。

list

Sequence、FlexSequence、GridSequenceについて報告されたプロパティのコレクションを含むオブジェクトです。listタグオブジェクトには、次の表に示すプロパティがあります。

プロパティ	型	説明
`itemCount`	整数	リストの項目の合計数です。
`highestIndexSeen`	整数	表示された項目のうち最も上位にある項目のインデックスです。
`highestOrdinalSeen`	整数	表示された項目のうち最大の序数を持つ項目の序数です。
`lowestIndexSeen`	整数	表示された項目のうち最も下位にある項目のインデックスです。
`lowestOrdinalSeen`	整数	表示された項目のうち最小の序数を持つ項目の序数です。

リストでは表示された最下位と最上位のインデックス／序数が追跡されるため、ユーザーが画面上で何を表示したかを情報に基づいて推測できます。たとえば、新しいリストに10～20の序数があり、画面には10～12が表示されている場合、ユーザーには項目18に何が含まれているかがわからないため、ユーザーが「番号18を選択」と発話するのを許可しないことが妥当です。

以下は、listタグの例です。

{
  "id": "myListOfDogs",
  "uid": ":138",
  "position": "1280x800+0+0:0",
  "type": "mixed",
  "tags": {
    "list": {
      "itemCount": 190,
      "lowestIndexSeen": 0,
      "highestIndexSeen": 3,
      "lowestOrdinalSeen": 1,
      "highestOrdinalSeen": 4
    },
    "scrollable": {
      "direction": "vertical",
      "allowForward": true,
      "allowBackwards": true
    },
    "focused": false
  },
  "children": [
    {
      "position": "800x600+20+33:0",
      "uid": ":2352",
      "type": "mixed",
      "tags": {
        "clickable": true,
        "ordinal": 2,
        "listitem": {
          "index": 2
        }
      }
    },
    {
      "position": "800x600+20+633:0",
      "uid": ":23112",
      "visibility": 0.16,
      "type": "mixed",
      "tags": {
        "clickable": true,
        "ordinal": 3,
        "listItem": {
          "index": 3
        }
      }
    }
  ]
}

listタグは、空のSequenceまたはGridSequenceについては報告されません。

itemCount

リストの項目の合計数です。リストの長さが不明な場合、itemCountは-1になります。

highestIndexSeen

このリストで表示された子の中で最も上位のインデックスです。項目の一部が画面に表示されていれば、たとえそれが少数のピクセルであっても、項目は「表示された」ことになります。

highestIndexSeenの値は0から始まります。たとえば、リストに3つの項目が含まれ、すべてが画面に表示されている場合、highestIndexSeenは2です。

highestOrdinalSeen

このリストで表示された子の中で最も大きい序数値です。項目の一部が画面に表示されていれば、たとえそれが少数のピクセルであっても、項目は「表示された」ことになります。このタグは、ordinal値を持つリスト項目に適用されます。項目のコンポーネントにordinalプロパティが設定されている場合、リスト項目にはordinal値が含まれます。

highestOrdinalSeenの値は、現在または過去に、序数値を持つ子が1つ以上表示された場合に報告されます。

lowestIndexSeen

このリストで表示された子の中で最も下位のインデックスです。項目の一部が画面に表示されていれば、たとえそれが少数のピクセルであっても、項目は「表示された」ことになります。

lowestIndexSeenの値は0から始まります。APLリストは通常、リスト内の最も下にある項目が画面に表示される状態で最初に表示されます。したがって、lowestIndexSeenは通常0を返します。

lowestOrdinalSeen

このリストで表示された子の中で最も小さい序数値です。項目の一部が画面に表示されていれば、たとえそれがわずか数ピクセルであっても、項目は「表示された」ことになります。このタグは、ordinal値を持つリスト項目に適用されます。項目のコンポーネントにordinalプロパティが設定されている場合、リスト項目にはordinal値が含まれます。

lowestOrdinalSeenの値は、現在または過去に、序数値を持つ子が1つ以上表示された場合に報告されます。

listItem

SequenceまたはGridSequenceの子に関する情報です。listItemプロパティには、次の表に示すプロパティがあります。

プロパティ	型	説明
`index`	整数	親要素におけるこの要素の0から始まるインデックスです。

listItemは、グリッドに表示されるリスト項目の行と列を報告するスペースを確保するためのオブジェクトとして報告されます。

index

親要素におけるこのリスト項目のインデックスです。インデックスは0から始まります。このインデックスを、listタグ内のlowestIndexSeenやhighestIndexSeenの値と比較できます。

media

ビデオプレーヤーなどのメディアプレーヤーについて報告されたプロパティのコレクションを含むオブジェクトです。mediaタグは、メディアプレーヤーの現在の状態と、メディアプレーヤーで実行できる操作を示します。mediaタグオブジェクトには、次の表に示すプロパティがあります。

プロパティ	型	説明
`allowAdjustSeekPositionForward`	ブール値	現在位置からの相対位置を使用して早送りできます。
`allowAdjustSeekPositionBackwards`	ブール値	現在位置からの相対位置を使用して早戻しできます。
`allowNext`	ブール値	次のトラックに進むことができます。
`allowPrevious`	ブール値	前のトラックに戻ることができます。
`audioTrack`	`foreground`、`background`、`none`のいずれか	メディアが再生されるオーディオトラックです。
`entities`	配列（デフォルト：[]）	現在のトラックのエンティティデータです。
`muted`	ブール値	オーディオ再生が現在ミュートされているかどうかを示します。
`positionInMilliseconds`	整数	トラックの先頭からの再生ヘッドの現在位置です。
`state`	`idle`、`playing`、`paused`のいずれか	現在の動作状態です。
`url`	文字列	現在のトラックのソースURLです。

mediaタグは、再生可能なメディアトラックが1つ以上ある場合に報告されます。

次の例は、mediaタグを示しています。

{
  "id": "myVideoPreview",
  "uid": ":1138",
  "position": "1024x600+0+0:0",
  "type": "video",
  "tags": {
    "media": {
      "allowAdjustSeekPositionForward": true,
      "allowAdjustSeekPositionBackwards": true,
      "allowNext": true,
      "allowPrevious": false,
      "audioTrack": "foreground",
      "muted": false,
      "entities": [
        "MY_ENTITY_DATA"
      ],
      "positionInMilliseconds": 34214,
      "state": "playing",
      "url": "https://myvideolocationhere"
    }
  }
}

allowAdjustSeekPositionForwards

trueの場合、このメディアトラックは時間を進めて新しい位置にシークすることができます。ライブメディアストリームは通常、このプロパティに対してfalseを報告します。

allowAdjustSeekPositionBackwards

trueの場合、このメディアトラックは時間を戻して新しい位置にシークすることができます。ライブメディアストリームは通常、このプロパティに対してfalseを報告します。

allowNext

trueの場合、メディアプレーヤーは次のメディアトラックに進むことができます。メディアプレーヤーが最終トラックにある場合、allowNextプロパティはfalseになります。

allowPrevious

trueの場合、メディアプレーヤーは前のメディアトラックに戻ることができます。メディアプレーヤーが最初のトラックにある場合、allowPreviousプロパティはfalseになります。

audioTrack

メディアプレーヤーが再生時に使用するオーディオトラックです。

entities

現在のメディアトラックに関連付けられているエンティティデータです（video_source_property_entityを参照）。メディアトラックにエンティティデータが関連付けられていない場合、mediaオブジェクトはentitiesプロパティを省略します。

muted

trueの場合、メディアのオーディオ再生は現在ミュートされています。

positionInMilliseconds

現在のメディアトラック内のメディアプレーヤーのヘッド位置（ミリ秒）です。

state

メディアトラックの現在の再生状態です。再生状態は次のいずれかの値になります。

名前	説明
`idle`	メディアプレーヤーはコンテンツを再生していません。
`paused`	メディアプレーヤーは一部のコンテンツを再生しましたが、一時停止しています。
`playing`	メディアプレイヤーはコンテンツをアクティブに再生中です。

url

現在のメディアトラックのURLです。

ordinal

要素に序数値が定義されている場合に報告されます。序数は自然数（正の整数）です。ordinalタグは、numberedプロパティがtrueに設定された複数子コンポーネントの子に割り当てられます。

{
  "id": "myListItem8",
  "uid": ":1231",
  "position": "200x100+23+26:1",
  "type": "text",
  "tags": {
    "ordinal": 6     // 序数は必ずしもインデックス-1の値になるとは限りません。
    "clickable": true,
    "focused": false
  }
}

listItemを持つ要素は、そのordinal値を親であるlistタグのhighestOrdinalSeenやlowestOrdinalSeenの値と比較することもできます。

ページが2ページ以上ある場合、Pagerコンポーネントについて報告されるプロパティのコレクションを含むオブジェクトです。pagerタグオブジェクトには、次の表に示すプロパティがあります。

プロパティ	型	説明
`index`	整数	現在のページのインデックスです。`Pager`のインデックスは0から始まります。したがって、最初のページの`index`は`0`です。
`pageCount`	整数	ページの合計数です。
`allowForward`	ブール値	`true`の場合、ユーザーはページャーを前方に移動できます。
`allowBackwards`	ブール値	trueの場合、ユーザーはページャーを後方に移動できます。

allowForwardプロパティとallowBackwardsプロパティは、Pagerのnavigationプロパティと現在のページに基づいて、ユーザーが実行できる操作を示します。これらのプロパティでは、SetPageコマンドを使用してプログラムで実行できる操作は考慮されません。

たとえば、navigationがnormalで、ユーザーがPager内を自由に移動できるとします。

Pagerが最初のページにある場合、allowForwardはtrueを報告し、allowBackwardsはfalseを報告します。
Pagerが最初のページでも最後のページでもないページにある場合、どちらのプロパティもtrueを報告します。
Pagerが最後のページにある場合、allowForwardはfalseを報告し、allowBackwardsはtrueを報告します。

navigationがnoneの場合、ユーザーはPagerを一切操作できません。このシナリオでは、表示されているページに関係なく、両方のプロパティがfalseを報告します。

navigationがwrapの場合、ユーザーはいつでも前後に移動できます。ユーザーが最後のページを表示している場合、前方に移動すると最初のページに戻ります。このシナリオでは、表示されているページに関係なく、両方のプロパティがtrueを報告します。

次の例は、pagerタグを示しています。

{
  "id": "weatherPager",
  "uid": ":111",
  "position": "1024x600+0+0:0",
  "type": "mixed",
  "tags": {
    "pager": {
      "index": 0,
      "pageCount": 4,
      "allowForward": true,
      "allowBackwards": false
    },
    "focused": false
  }
}

scrollable

領域が前後にスクロールできることを示すオブジェクトです。次のコンポーネントはコンテンツをスクロールできます。

これらのコンポーネントは、スクロールを必要とするコンテンツがコンポーネントに含まれている場合にscrollableタグを報告します。コンポーネント内のすべてのコンテンツが完全に表示されている場合、視覚コンテキストにはscrollableタグは含まれません。

scrollableタグオブジェクトには、次の表に示すプロパティがあります。

プロパティ	型	説明
`direction`	`horizontal`、`vertical`のいずれか	スクロールの方向です。
`allowFoward`	ブール値	trueの場合、スクロール領域のコンテンツは順方向にスクロールできます。
`allowBackwards`	ブール値	trueの場合、スクロール領域のコンテンツは逆方向にスクロールできます。

たとえば、Sequenceに10個の項目が含まれており、一度に5個の項目を表示できる大きさであるとします。

コンポーネントがインデックス0～4の項目を表示すると、allowForwardはtrue、allowBackwardはfalseになります。
ユーザーが下へスクロールしてインデックス2～6の項目が表示されると、allowForwardとallowBackwardの両方がtrueになります。
ユーザーがリストの最後までスクロールすると、allowForwardはfalse、allowBackwardはtrueになります。

scrollableタグは、allowForwardとallowBackwardのいずれかがtrueである場合に報告されます。両方のプロパティがfalseの場合、タグは含まれません。

以下は、scrollableタグの例です。

{
  "id": "todoList",
  "uid": ":211",
  "position": "1024x550+0:50:0",
  "type": "mixed",
  "tags": {
    "scrollable": {
      "direction": "horizontal",
      "allowForward": true,
      "allowBackwards": false
    },
    "focused": false
  }
}

spoken

この要素にAlexaが読み上げることができるコンテンツが含まれていることを示すブール値のタグです。speechプロパティを設定するコンポーネントはすべてspokenタグを返します。

以下は、spokenタグの例です。

{
  "id": "myListItem",
  "uid": ":444",
  "position": "800x80+72+437:0",
  "type": "text",
  "tags": {
    "clickable": true,
    "focused": true,
    "spoken": true
  }
}

viewport

viewportタグは、画面上の最上位要素にのみ使用されます。viewportタグは、その画面上のアクションに関するメタデータを保持します。viewportタグでは、次のプロパティが報告されます。

プロパティ	型	説明
`utcTime`	数値	UTC時間（ミリ秒）です。詳細については、データバインディングコンテキストの`utcTime`プロパティを参照してください。
`elapsedTime`	数値	このドキュメントの実行時間（ミリ秒）です。詳細については、データバインディングコンテキストの`elapsedTime`プロパティを参照してください。
`trackedChanges`	変更の配列	リクエストされたコンポーネントの状態の一時的な変更です。

例：

{
  "id": "top",
  "uid": ":101",
  "position": "480x480+0+0:0",
  "type": "mixed",
  "tags": {
    "viewport": {
      "utcTime": 1728414842835,
      "elapsedTime": 500,
      "trackedChanges": [
        { "uid": ":1001", "name": "playingState", "from": "idle", "to": "playing", "utcTime": 1728414842430 },
        { "uid": ":1002", "name": "playingState", "from": "idle", "to": "playing", "utcTime": 1728414842630 },
        { "uid": ":1001", "name": "playingState", "from": "playing", "to": "paused", "utcTime": 1728414842830 }
      ]
    }
  }
  ...
}

trackedChanges

trackChangesコンポーネントプロパティで設定された、特定のコンポーネントに対して発生した変更の配列です。

配列内の各変更には、次の表に示すプロパティがあります。

プロパティ	型	説明
`uid`	文字列	コンポーネントの一意のIDです。
`name`	文字列	変更されたプロパティです。
`from`	オブジェクト	プロパティの以前の値です。
`to`	オブジェクト	プロパティの新しい値です。
`utcTime`	数値	UTC時間による変更のタイムスタンプです。

システムでは、追跡対象のすべてのプロパティの最終変更記録を保持することが保証されます。trackedChanges配列に（ランタイムによって設定された）空き容量が残っている限り、より多くの履歴データを使用できる可能性があります。システムは、最も古いレコードを最初に削除します。

要素階層を生成するためのルール

視覚コンテキストの要素階層を生成する際には、次のルールが適用されます。

最上位コンポーネントは常にviewportタグ付きの要素を生成します。
コンポーネントが画面に表示されていて、以下のアトリビュートのうち少なくとも1つが含まれている場合、コンポーネントは要素として報告されます。
- 空でないentitiesプロパティ
- trueのclickableタグ
- mediaタグ
- pagerタグ
- scrollableタグ
- spokenタグ
次の条件の両方に当てはまる場合、表示されていないコンポーネントが要素として報告されることがあります。
- コンポーネントに空でないentitiesプロパティがある。
- コンポーネントが過去のある時点で画面に表示されていた。

表示されていないコンポーネントを報告する目的は、画面に表示されていたものの、スクロールで表示範囲から外れた可能性がある項目をユーザーが参照できるようにすることです。コンテキストのレポートシステムでは、以前に表示されていたすべての項目が報告されることは保証されません。システムは最近表示された項目のウィンドウを保持し、直近に表示された要素を報告します。

ネストされた要素の例

次の例は、通常のレポートでコンポーネントがどのようにネストされるかを示しています。この例では、背景画像、記事のタイトルに対応するテキスト要素、コンテンツを保持するスクロール要素を表示するAPLドキュメントを示しています。コンテンツはさらに、ラベル付きの画像要素とテキスト要素に分かれています。

最上位のContainerには単一のentityがあり、テキストコンテンツにはspeechプロパティが設定されています。

このドキュメントでは、階層を生成するルールによって、次のような結果になります。

最上位のContainerにはエンティティデータが割り当てられているため、報告されます。
背景画像にはエンティティデータがなく、ほかのタグも適用されないため、報告されません。
タイトルにはエンティティデータがなく、ほかのタグも適用されないため、報告されません。
スクロール領域には有効なscrollableタグがあるため、報告されます。
小さい画像にはエンティティデータがなく、ほかのタグも適用されないため、報告されません。
大きいテキストにはspokenタグがあるため、報告されます。

結果の要素階層は、次のようになります。

{
  "id": "top-level",
  "uid": ":9549",
  "position": "960x480+0+0:0",
  "type": "mixed",
  "tags": {
    "viewport": {}
  },
  "children": [
    {
      "id": "scrollingRegion",
      "uid": ":9552",
      "position": "960x349+0+131:1",
      "type": "mixed",
      "tags": {
        "focused": false,
        "scrollable": {
          "direction": "vertical",
          "allowForward": false,
          "allowBackwards": true
        }
      },
      "children": [
        {
          "id": "articleId",
          "uid": ":9555",
          "position": "832x1410+64-1002:1",
          "type": "text",
          "tags": {
            "spoken": true
          },
          "visibility": 0.20000000298023224,
          "entities": []
        }
      ],
      "entities": []
    }
  ],
  "entities": [
    {
      "id": "mainPage"
    }
  ]
}

この例では、ユーザーがコンテンツの一番下までスクロールしてから、スキルにリクエストを送信する発話を行ったため、allowForwardがfalseになっています。

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

フィードバックを送信

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