APL Entity Sensing Extension
Entity Sensing機能を備えたデバイスでは、ユーザーの存在を検出できます。APL応答でEntity Sensing extensionを使用すると、検出されたユーザーに関する情報、たとえばデバイスを基準としたユーザーの位置を取得できます。スキルでは変化に対応することもできます。たとえば、エンゲージメントが最も高いユーザーが変化したときに対応できます。
Extensionの概要
| サポートされるAPLの最小バージョン | APL 1.4 |
| Extension URI | alexaext:entitysensing:10 |
| 設定 | |
| 環境プロパティ | |
| ライブデータプロパティ | |
| コマンド | なし |
| イベントハンドラー | |
| スキルマニフェストで必要か |
はい。このextensionを使用するには、requestedExtensionsに追加します。スキルマニフェストでのEntity-sensing extensionを参照してください。
|
| 設定は自動的に初期化されるか | いいえ。 |
Entity Sensing extensionについて
Entity Sensing APL extensionは、ユーザーの存在を検出できるデバイスで動作します。次のことを行うことができます。
- デバイスがユーザーを検出したかどうかを判断するためのプロパティを取得し、デバイスを基準としたユーザーの位置を把握します。
- イベントハンドラーを使用して、デバイス状態が変化したときやユーザーが検出されたときに対応します。たとえば、エンゲージメントが最も高いユーザーが変化したとデバイスが判断したときに対応できます。
Entity Sensing extensionでは、プライマリユーザーに関する情報を得ることができます。プライマリユーザーとは、デバイスを使用する可能性が最も高いユーザーのことです。プライマリユーザーを確認するアルゴリズムはデバイスごとに異なり、さまざまな要因によって変化します。
プライマリユーザーに関する情報を取得するには、ライブデータプロパティを使用します。
Entity Sensing extensionを有効にする
Entity Sensing extensionのプロパティとイベントハンドラーを使用するには、以下を実行する必要があります。
- extensionをスキルマニフェストの
requestedExtensionsプロパティに追加します。 - extensionをAPLドキュメントの
extensionsプロパティに追加して、ドキュメントで明示的にリクエストします。 - ドキュメントの
settingsプロパティで、extension設定のドキュメントレベルのコンフィギュレーションを行います。
スキルマニフェストでのEntity Sensing extension
ALEXA_EXTENSIONインターフェースには、autoInitializedExtensionsとrequestedExtensionsという2つのプロパティがあります。Entity Sensing extensionをrequestedExtensionsプロパティに追加します。このextensionには、autoInitializedExtensionsでコンフィギュレーションを行う必要がある設定値はありません。
Entity Sensing extensionのURIは "alexaext:entitysensing:10" です。
次の例は、Entity Sensing extensionのコンフィギュレーションが行われたスキルマニフェストを示しています。
{
"apis": {
"custom": {
"interfaces": [
{
"type": "ALEXA_EXTENSION",
"requestedExtensions": [
{
"uri": "alexaext:entitysensing:10"
}
]
}
]
}
}
}
スキルマニフェストのAPL extension設定の詳細については、スキルマニフェストでextensionをリクエストするを参照してください。
開発者コンソールでスキルマニフェストのコンフィギュレーションを行うこともできます。
Entity Sensing extensionのスキルのコンフィギュレーションを行うには
- 開発者コンソールを開き、設定するスキルの編集をクリックします。
- ビルド＞インターフェースページに移動します。
- Alexa Presentation Languageインターフェースを有効にします。
-
ExtensionsリストからEntity Sensing v.10を選択します。
このオプションを選択すると、スキルマニフェストの
requestedExtensionsプロパティが更新されます。 - インターフェースを保存、モデルをビルドの順にクリックして、対話モデルを再ビルドします。
APLドキュメントのEntity Sensing extension
APLドキュメントでEntity Sensingイベントハンドラーおよびプロパティを使用するには、ドキュメントのextensionsプロパティでextensionをリクエストする必要があります。スキルマニフェストでrequestedExtensionsにextensionを追加した場合も、このリクエストが必要です。
Entity Sensing extensionのURIは "alexaext:entitysensing:10" です。
次の例では、Entity Sensing extensionをリクエストし、その名前をEntitySensingに設定します。次に、ドキュメントで"EntitySensing"の名前を使用して、設定、プロパティ、イベントハンドラーを参照します。
{
"type": "APL",
"version": "1.4",
"extensions": [
{
"name": "EntitySensing",
"uri": "alexaext:entitysensing:10"
}
]
}
APLドキュメントでAPL extensionをリクエストする方法の詳細については、APLドキュメントでextensionをリクエストするを参照してください。
Entity Sensing extensionがデバイスでサポートされるかを確認する
Entity Sensing extensionは、すべてのデバイスでサポートされるわけではありません。ユーザーのデバイスでextensionがサポートされるかどうかは、ドキュメントおよびコードで確認します。
デバイスでEntity Sensing extensionがサポートされるかどうかを確認するには、ドキュメントでenvironment.extension変数を使用します。たとえば、extensionsプロパティでnameにEntitySensingを使用したとします。この場合、デバイスでEntity Sensingがサポートされていれば、次のデータバインディング式でtrueが返されます。
${environment.extension.EntitySensing}
データバインディング式は、条件ステートメントとwhenプロパティで使用できます。
コードでは、スキルに送信されるリクエストのcontext.Extensions.availableプロパティに、サポートされるextensionsが指定されています。このプロパティには、使用可能なextensionのURIが各項目のキーに指定されたマップが含まれます。
次の例は、Entity Sensing extensionをサポートするデバイスからのリクエストを示しています。
{
"version": "1.0",
"session": {},
"context": {
"Viewports": [],
"Viewport": {},
"Extensions": {
"available": {
"alexaext:entitysensing:10": {}
}
},
"System": {}
},
"request": {}
}
context.Extensionsプロパティには、次の条件の両方を満たすextensionsが含まれます。
- スキルマニフェストの
requestedExtensionsプロパティでリクエストされていること。 - デバイスでサポートされていること。
extensionの設定
Entity Sensing extensionには、次の設定があります。
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
entitySensingStateName |
文字列 | "" | EntitySensingStateデータバインディングに使用する名前。 |
primaryUserName |
文字列 | "" | PrimaryUserデータバインディングに使用する名前。 |
APLドキュメントでこれらのコンフィギュレーションを行うには、settings.AssignedNameを使用します。AssignedNameは、extensionsプロパティでEntity Sensing extensionに割り当てた名前です。設定はすべて必須です。
次の例では、extensionにEntitySensingという名前を割り当てた後、settings.EntitySensingでプロパティentitySensingStateNameおよびprimaryUserNameを設定しています。
{
"type": "APL",
"version": "1.4",
"extensions": [
{
"name": "EntitySensing",
"uri": "alexaext:entitySensing:10"
}
],
"settings": {
"EntitySensing": {
"entitySensingStateName": "EntitySensingState",
"primaryUserName": "User"
}
},
"mainTemplate": {}
}
entitySensingStateName
entitySensingStateNameプロパティを、グローバルのデータバインディングコンテキストでEntitySensingStateにアクセスするために使用する名前に設定します。entitySensingStateNameがない場合、または空の文字列に設定されている場合は、EntitySensingStateプロパティにアクセスできません。
たとえば、次の例は、entitySensingStateNameをMyEntitySensingStateに設定してから、EntitySensingStateプロパティにアクセスする方法を示しています。
{
"type": "APL",
"version": "1.4",
"extensions": [
{
"name": "EntitySensing",
"uri": "alexaext:entitysensing:10"
}
],
"settings": {
"EntitySensing": {
"entitySensingStateName": "MyEntitySensingState",
"primaryUserName": "MyPrimaryUser"
}
},
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "Container",
"items": [
{
"type": "Text",
"id": "MyTextBox",
"text": "Entity sensing is ${EntitySensingState.errorCode == 0 ? 'Active' : 'Faulted'}"
},
{
"type": "Text",
"id": "MyTextBox",
"text": "Error code: ${MyEntitySensingState.errorCode}"
},
{
"type": "Text",
"text": "Error: ${MyEntitySensingState.error}"
}
]
}
]
}
}
primaryUserName
primaryUserNameプロパティを、グローバルのデータバインディングコンテキストでPrimaryUserプロパティにアクセスするために使用する名前に設定します。primaryUserNameがない場合、または空の文字列に設定されている場合は、PrimaryUserプロパティにアクセスできません。
たとえば、次の例は、primaryUserNameをMyPrimaryUserに設定してから、PrimaryUserプロパティにアクセスする方法を示しています。
{
"type": "APL",
"version": "1.4",
"extensions": [
{
"name": "EntitySensing",
"uri": "alexaext:entitysensing:10"
}
],
"settings": {
"EntitySensing": {
"primaryUserName": "MyPrimaryUser",
"entitySensingStateName": "MyEntitySensingState"
}
},
"mainTemplate": {
"item": {
"type": "Container",
"items": [
{
"type": "Text",
"id": "MyTextBox",
"text": "${MyPrimaryUser.isSeen ? 'User located at ${MyPrimaryUser.poise.absoluteAngle} degrees.' : 'Nobody here'}"
},
{
"type": "Text",
"id": "textUserId",
"text": "id: ${MyPrimaryUser.id}"
},
{
"type": "Text",
"id": "textUserActive",
"text": "isActive: ${MyPrimaryUser.isActive}"
},
{
"type": "Text",
"id": "textUserSeen",
"text": "isSeen: ${MyPrimaryUser.isSeen}"
}
]
}
}
}
環境プロパティ（静的）
Entity Sensing extensionでは、次の静的環境プロパティが追加されます。
| 名前 | 型 | 説明 |
|---|---|---|
horizontalFOV |
絶対数（度） | デバイスの水平方向の視界の範囲。 |
version |
文字列 | Entity Sensingサービスのバージョン。 |
verticalFOV |
絶対数（度） | デバイスの垂直方向の視界の範囲。 |
Entity Sensing環境オブジェクトの構造の例を次に示します。
{
"version": "1.0",
"horizontalFOV": 60,
"verticalFOV": 34
}
horizontalFOV
horizontalFOVでは、Entity Sensingの水平方向の視界の範囲を定義します。このプロパティは、デバイスごとに異なります。
version
version環境プロパティは、Entity Sensingサービスのバージョンを表します。versionは、インストール済みのextensionのビルドとリリースの詳細を報告する場合に便利です。
verticalFOV
verticalFOVは、Entity Sensingの垂直方向の視界の範囲を定義します。このプロパティは、デバイスごとに異なります。
ライブデータプロパティ
Entity Sensing extensionにより、データバインディングコンテキストにライブデータプロパティが追加されます。ライブデータプロパティは、APLドキュメントのライフサイクル中に変更できるデータオブジェクトです。
Entity Sensing extensionにより、データバインディングコンテキストに次のライブデータオブジェクトが追加されます。
| 名前 | 型 | 説明 |
EntitySensingState |
オブジェクト | デバイスの現在のEntity Sensing機能を表します。 |
PrimaryUser |
オブジェクト | 検出されたユーザーのうち、デバイスとのエンゲージメントが最も高いユーザーについて報告します。 |
ライブデータの詳細については、Extensionのライブデータを参照してください。
EntitySensingState
EntitySensingStateライブデータオブジェクトは、デバイスの現在のEntity Sensingの機能を表します。
EntitySensingStateにアクセスするには、extension settingsでentitySensingStateNameプロパティを設定する必要があります。entitySensingStateNameがない場合、または空の文字列が含まれている場合、EntitySensingStateは使用できません。
EntitySensingStateには、次のプロパティがあります。
| 名前 | 型 | 説明 |
|---|---|---|
| error | 文字列 | 読み取り可能なエラーメッセージ。エラーがない場合は""。 |
| errorCode | 数値 | エラーコード。エラーがない場合は0。 |
完全なEntitySensingStateデータバインディングコンテキストの構造の例を次に示します。
{
"error": "",
"errorCode": 0
}
error、errorCode
EntitySensingState.errorプロパティとEntitySensingState.errorCodeプロパティは、Entity Sensingのデバイスエラーに関する情報を提供します。
エラーが発生すると、errorCodeは0以外のコード、errorはエラーに関する説明を報告します。デバイスの動作中にエラーが発生していない場合、errorCodeは0を返し、errorは空の文字列を返します。errorの説明は、デバイスごとに異なります。
エラーが発生するのは、さまざまな条件のためにデバイスが検出を行えない場合や、デバイスで機械的な障害が発生した場合です。エラーの一般的な原因は次のとおりです。
- 物理的な障害物がある
- 光が少ない
- デバイスが「おやすみモード」になっている
- ユーザーがデバイスのカメラのシャッターを閉じた
errorCodeが0でない場合は、デバイスの機能が制限されます。エラーを検出すると、デバイスは、errorCode条件がクリアされたかどうかを定期的に確認します。errorCode条件がクリアされると、Entity Sensingの通常の動作が再開されます。
errorCodeの値が変化すると、OnEntitySensingStateChangedイベントがトリガーされます。
Alexaデバイスでは、次のerrorCodeとそれに対応するerrorプロパティを使用できます。errorの説明とerrorCodeの値は、デバイスごとに異なります。このため、デバイスによっては、別の値が示される場合があります。
| errorCode | 説明 | エラーテキストの例 |
|---|---|---|
| 0 | カメラは正常に動作しています。 | - |
| 1 | カメラに問題があるため、デバイスがユーザーを見つけることができません。 | Camera is disabled Camera shutter is closed |
これらのエラー値は、デバッグ目的で使用してください。errorの文字列は、ローカライズされません。このため、errorやerrorCodeの値は、ユーザーに表示しないでください。
PrimaryUser
PrimaryUserライブデータオブジェクトは、デバイスとのエンゲージメントが最も高いユーザーを表します。エンゲージメントアルゴリズムは、デバイスごとに異なります。
PrimaryUserにアクセスするには、extension settingsでprimaryUserNameプロパティを設定する必要があります。primaryUserNameがない、または空の文字列が含まれている場合は、PrimaryUserオブジェクトを使用できません。
PrimaryUserには、次のプロパティがあります。
| 名前 | 型 | 説明 |
|---|---|---|
id |
文字列 | デバイス割り当てのエンティティID。ユーザーが検出されない場合、文字列は空です。 |
isActive |
ブール値 | ユーザーがウェイクワードを発話したことを示します。 |
isSeen |
ブール値 | デバイスがユーザーを検出したことを示します。 |
poise |
オブジェクト | ユーザーの位置。 |
activeユーザーを表すPrimaryUserデータバインディングコンテキストの構造の例を次に示します。
{
"id": "Entity1",
"isActive": true,
"isSeen": true,
"poise": {
"absoluteAngle": 30,
"relativeAngle": 20
}
}
デバイスがユーザーを検出しなかった場合のPrimaryUserデータバインディングコンテキストの例を次に示します。
{
"id": "",
"isActive": false,
"isSeen": false,
"poise": {
"absoluteAngle": 0,
"relativeAngle": 0
}
}
id
PrimaryUser.idプロパティは、デバイスにより割り当てられた、最後にウェイクワードを発話したユーザーのIDを返します。デバイスがユーザーを検出できない場合、プロパティは空の文字列を返します。
割り当てられたidは、デバイスがユーザーを認識できなくなってから一定期間持続します。この期間は、デバイスによって異なります。ユーザーが視界から消えてから再度視界に入ると、デバイスはそのエンティティを既知のエンティティとして認識することを試み、同じid値を割り当てます。デバイスがそのユーザーを認識できない場合は、新しいエンティティIDが割り当てられます。
isActive
ユーザーがウェイクワードを発話した場合はtrue、それ以外の場合はfalseを返します。
デバイスで検出されたユーザーがウェイクワードを発話しなかった場合、そのユーザーは、アクティブではなく、エンゲージされていると見なされます。
isSeen
デバイスがユーザーを検出し、そのユーザーがデバイスの観測可能範囲内にいる場合は、trueを返します。エンティティが検出されなくなった場合、またはエンティティidが割り当てられていない場合は、falseを返します。
また、EntitySensingState.errorCodeが0でない場合、PrimaryUser.isSeenプロパティはfalseを返します。
ユーザーのisSeen値が変化すると、onPrimaryUserChangedイベントがトリガーされます。
poise
ユーザーの位置が記述されたオブジェクトを返します。poiseオブジェクトには、次のプロパティがあります。
| 名前 | 型 | 説明 |
|---|---|---|
absoluteAngle |
数値（度） | 中心位置からの角度位置。 |
relativeAngle |
数値（度/秒） | 表示位置からの角度位置。 |
poise.absoluteAngleは、デバイスの中心位置を基準にしたエンティティの角度位置を表します。poise.relativeAngleは、画面を基準にした角度位置を表します。デバイスの画面が回転しない場合は、同じ角度と相対位置が返されます。
デバイスがユーザーを感知できない場合、isSeen値はfalseを返し、poise.absoluteAngle値とpoise.relativeAngle値は、最後に認識されたユーザーの位置を表します。エンティティが割り当てられていない場合、これらの値は未定義です。
PrimaryUser.poise値が変更されると、onPrimaryUserChangedイベントがトリガーされます。
コマンド
Entity Sensing extensionでは、新しいextensionコマンドは追加されません。
イベントハンドラー
Entity Sensing extensionでは、新しいextensionイベントハンドラーが追加されます。Entity Sensing extensionで生成されるイベントに対応するには、APLドキュメントの最上位のプロパティにハンドラーを追加します。ハンドラー名には、AssignedName:EventHandlerNameを使用します。AssignedNameは、extensionsプロパティでEntity Sensing extensionに割り当てた名前、EventHandlerNameはハンドラーの名前です。
たとえば、extensionの名前をEntitySensingにした場合、OnEntitySensingStateChangedハンドラーからイベントに対応するには、EntitySensing:OnEntitySensingStateChangedを使用します。
OnEntitySensingStateChanged
EntitySensingStateのプロパティが変更されたときに呼び出されます。EntitySensingStateプロパティが変更されると、OnEntitySensingStateChangedイベントがトリガーされます。
OnEntitySensingStateChangedハンドラーでは、イベントコンテキストに次の2つのプロパティが追加されます。
| 名前 | 型 | 説明 |
|---|---|---|
changed |
オブジェクト | 変更されたEntitySensingStateプロパティのサブセット。 |
current |
オブジェクト | EntitySensingStateプロパティの完全なコレクション。プロパティ値は、イベント時のEntity Sensingの状態を表します。これには、イベントの影響を受ける値も含まれます。 |
EntitySensingStateプロパティのリストについては、EntitySensingStateを参照してください。
生成されるイベントの形式は次のようになります。
{
"event": {
"changed": {
//変更されたすべての状態プロパティ
},
"current": {
//現在のすべての状態プロパティ
},
"source": {
"type": "Document",
"handler": "OnEntitySensingStateChanged",
"id": null,
"uid": null,
"value": null
}
}
}
このイベントハンドラーのコマンドは、常に高速モードで実行されます。
OnPrimaryUserChanged
次のようなPrimaryUserの変更が発生すると、呼び出されます。
Poiseを除くすべてのPrimaryUserプロパティが変更されたとき。- デバイスが新しい
PrimaryUserを検出し割り当てたとき。 - デバイスが既存の
PrimaryUserを検出しなくなったとき。
OnPrimaryUserChangedハンドラーでは、イベントコンテキストに次の2つのプロパティが追加されます。
| 名前 | 型 | 説明 |
|---|---|---|
changed |
オブジェクト | 変更されたPrimaryUserプロパティのサブセット。 |
current |
オブジェクト | PrimaryUserプロパティの完全なコレクション。このプロパティ値は、イベント時のプライマリユーザーを表します。これには、イベントの影響を受ける値も含まれます。 |
OnPrimaryUserChangedハンドラーでは、イベントコンテキストに次の2つのプロパティが追加されます。
生成されるイベントの形式は次のようになります。
{
"event": {
"changed": {
//変更されたプロパティのみ
},
"current": {
//現在のすべてのプロパティ
},
"source": {
"type": "Document",
"handler": "OnPrimaryUserChanged",
"id": null,
"uid": null,
"value": null
}
}
}
関連トピック
最終更新日: 2020 年 10 月 26 日