APL Entity Sensing Extension

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 APL Extensionを使用すると、次の操作を実行できます。

  • プロパティを取得して、デバイスがユーザーを検出したかどうかを判断し、デバイスからの相対的なユーザーの位置を特定する。
  • イベントハンドラーを使用して、デバイスの状態が変更されたときやユーザーが検出されたときに応答する。たとえば、エンゲージメントが最も高いユーザーが変更されたとデバイスが判断したときに応答できます。

Entity Sensing Extensionでは、プライマリユーザーに関する情報が提供されます。プライマリユーザーとは、デバイスとのエンゲージメントが最も高いと見なされているユーザーです。プライマリユーザーを確認するアルゴリズムはデバイスごとに異なり、さまざまな要因に依存します。

プライマリユーザーに関する情報を取得するには、ライブデータプロパティを使用します。

Entity Sensing Extensionを有効にする

Entity Sensing Extensionのプロパティとイベントハンドラーを使用するには、次の手順を完了する必要があります。

  1. スキルマニフェストのrequestedExtensionsプロパティにExtensionを追加します。
  2. APLドキュメントのextensionsプロパティにExtensionを追加して、ドキュメントで明示的にリクエストします。
  3. ドキュメントのsettingsプロパティで、Extensionのドキュメントレベルの設定を行います。

スキルマニフェストでのEntity Sensing Extension

ALEXA_EXTENSIONインターフェースには、autoInitializedExtensionsとrequestedExtensionsという2つのプロパティがあります。requestedExtensionsプロパティにEntity Sensing Extensionを追加します。この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を使用するようにスキルを設定するには

  1. 開発者コンソールを開き、設定するスキルを探して編集をクリックします。
  2. ビルド > インターフェースページに移動します。
  3. Alexa Presentation Languageインターフェースを有効にします。

  4. Extensionsの一覧からEntity Sensing v.10を選択します。

    このオプションを選択すると、スキルマニフェストのrequestedExtensionsプロパティが更新されます。

  5. インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。

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": "2024.3",
  "extensions": [
    {
      "name": "EntitySensing",
      "uri": "alexaext:entitysensing:10"
    }
  ]
}

APLドキュメントでAPL Extensionをリクエストする方法の詳細については、APLドキュメントでExtensionをリクエストするを参照してください。

デバイスでEntity Sensing Extensionがサポートされるかどうかを確認する

Entity Sensing Extensionは、すべてのデバイスでサポートされるとは限りません。ユーザーのデバイスでExtensionがサポートされるかどうかを、ドキュメントやコードで確認する必要があります。

ドキュメントでは、environment.extension変数を使用して、デバイスでEntity Sensing Extensionがサポートされるかどうかを確認します。たとえば、extensionsプロパティでnameにEntitySensingを指定したとすると、デバイスでEntity Sensingがサポートされていれば、次のデータバインディング式からtrueが返されます。

${environment.extension.EntitySensing}

データバインディング式は、条件文とwhenプロパティで使用できます。

コードでは、スキルに送信されるリクエストのcontext.Extensions.availableプロパティに、サポートされるExtensionが指定されています。このプロパティにはマップが含まれ、各項目のキーは使用可能なExtensionのURIを示します。

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

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [],
    "Viewport": {},
    "Extensions": {
      "available": {
        "alexaext:entitysensing:10": {}
      }
    },
    "System": {}
  },
  "request": {}
}

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

  • スキルマニフェストの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": "2024.3",
  "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": "2024.3",
  "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は${EntitySensingState.errorCode == 0 ? 'アクティブです' : '失敗しました'}"
          },
          {
            "type": "Text",
            "id": "MyTextBox",
            "text": "エラーコード：${MyEntitySensingState.errorCode}"
          },
          {
            "type": "Text",
            "text": "エラー：${MyEntitySensingState.error}"
          }
        ]
      }
    ]
  }
}

primaryUserName

primaryUserNameプロパティには、グローバルのデータバインディングコンテキストでPrimaryUserプロパティにアクセスするために使用する名前を設定します。primaryUserNameがない場合、または空の文字列に設定されている場合は、PrimaryUserプロパティにアクセスできません。

次の例は、primaryUserNameをMyPrimaryUserに設定してから、PrimaryUserプロパティにアクセスする方法を示しています。

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

{
  "type": "APL",
  "version": "2024.3",
  "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 ? 'ユーザーは${MyPrimaryUser.poise.absoluteAngle}度の位置にいます' : 'だれもいません'}"
        },
        {
          "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によってデータバインディングコンテキストのenvironment.extensionプロパティに追加される静的プロパティを示しています。

名前 型 説明
horizontalFOV 絶対数（度） デバイスの水平方向の視野範囲です。
version 文字列 Entity Sensingサービスのバージョンです。
verticalFOV 絶対数（度） デバイスの垂直方向の視野範囲です。

Entity Sensing環境オブジェクトの構造の例を次に示します。

{
  "version": "1.0",
  "horizontalFOV": 60,
  "verticalFOV": 34
}

APLドキュメントでこれらのプロパティにアクセスするには、environment.extensions.AssignedNameを使用します。AssignedNameは、extensionsプロパティでEntity Sensing Extensionに割り当てた名前です。たとえば、extensionsプロパティでnameにEntitySensingを指定したとすると、次のデータバインディング式からhorizontalFOVプロパティが返されます。

${environment.extension.EntitySensing.horizontalFOV}

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の設定で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の設定でprimaryUserNameプロパティを設定する必要があります。primaryUserNameがない場合、または空の文字列が含まれている場合は、PrimaryUserオブジェクトを使用できません。

次の表は、PrimaryUserのプロパティの一覧です。

名前 型 説明
id 文字列 デバイスによって割り当てらえたエンティティ識別子です。ユーザーが検出されていない場合は空の文字列になります。
isActive ブール値 ユーザーがウェイクワードを発話した場合はtrueを返します。それ以外の場合はfalseを返します。
isSeen ブール値 デバイスがユーザーを検出した場合はtrueを返します。それ以外の場合はfalseを返します。
poise オブジェクト ユーザーの位置を表します。

以下は、アクティブなユーザーを表すサンプルの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が割り当てられます。

isActive

ユーザーがウェイクワードを発話した場合はtrue、それ以外の場合はfalseを返します。

デバイスで検出されたユーザーがウェイクワードを発話していない場合、そのユーザーはアクティブではなく、エンゲージされていると見なされます。

isSeen

デバイスがユーザーを検出し、そのユーザーがデバイスの観測可能範囲内にいる場合はtrueを返します。エンティティが検出されなくなった場合、またはエンティティidが割り当てられていない場合はfalseを返します。

PrimaryUser.isSeenプロパティは、EntitySensingState.errorCodeが0でない場合も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ハンドラーでイベントコンテキストに追加されるプロパティの一覧です。

名前 型 説明
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ハンドラーでイベントコンテキストに追加されるプロパティの一覧です。

名前 型 説明
changed オブジェクト PrimaryUserの変更されたプロパティのサブセットです。
current オブジェクト PrimaryUserのすべてのプロパティコレクションです。プロパティ値はイベント時のプライマリユーザーを表し、イベントの影響を受ける値も含まれます。

次の例は、生成されるイベントの形式を示しています。

{
  "event": {
    "changed": {
        // 変更されたプロパティのみ
    },
    "current": {
        // 現在のすべてのプロパティ
    },
    "source": {
      "type": "Document",
      "handler": "OnPrimaryUserChanged",
      "id": null,
      "uid": null,
      "value": null
    }
  }
}

画像フィルター

Entity Sensing Extensionによって追加される新しい画像フィルターはありません。

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

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