Web API Entity-Sensing Extension
Entity Sensing機能を備えたAlexa搭載デバイスでは、ユーザーの存在を検出できます。Entity Sensing extensionを使用すると、次の操作を実行できます。
- デバイスによってユーザーが検出されたかどうかを判断するための情報を取得し、検出された場合は、デバイスを基準としたユーザーの位置を取得します。
- ユーザーの検出に関する変化に対応します。たとえば、ユーザーの位置が変わった場合や、別のユーザーのエンゲージメントが最も高くなった場合などです。
Entity Sensing extensionでは、プライマリユーザーに関する情報を得ることができます。プライマリユーザーとは、デバイスを使用する可能性が最も高いユーザーのことです。プライマリユーザーを決定するアルゴリズムは、目的のデバイスの実装によって異なります。具体的には、ユーザーからデバイスまでの距離、デバイスに対するユーザーの角度、マイクとカメラの検出機能などの要素が関与します。プライマリユーザーの最新の位置を取得するには、Entity Sensingインターフェースを使用します。
スキルでEntity Sensing extensionを有効にする
スキルでEntity Sensing extensionを有効にするには、Alexa Skills Kit(ASK)コマンドラインインターフェース(CLI)または開発者コンソールを使用して、スキルマニフェストにextensionを追加します。スキルマニフェストにextensionsを追加する方法の詳細については、スキルにextensionsを追加するを参照してください。
CLIを使用してextensionを追加する
Entity Sensing extensionを有効にするには、スキルマニフェストのJSONファイルにALEXA_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"
}
]
}
]
}
}
}
マニフェストファイルを保存したら、Alexa Skills Kitコマンドラインインターフェースを使用して、変更後のマニフェストをデプロイします。
開発者コンソールでextensionを追加する
開発者コンソールでスキルマニフェストのコンフィギュレーションを行うこともできます。
Entity Sensing extensionのスキルのコンフィギュレーションを行うには
- 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
- ビルド>インターフェースページに移動します。
- Alexa Web API for Gamesインターフェースを有効にします。
- Alexa Extensionsリストから、Entity Sensing v.10を選択します。
このオプションを選択すると、ALEXA_EXTENSION
インターフェースとrequestedExtensions
プロパティがスキルマニフェストに追加されます。 - インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。
ウェブアプリにextensionを追加する
Alexa JavaScript extensionライブラリをロードするには、次の例のように、HTMLページのscriptタグにURLを含める必要があります。
<head>
<script src="https://cdn.html.games.alexa.a2z.com/extensions/entity-sensing/v10/entity-sensing.js"></script>
</head>
次のコードを使用してEntity Sensingクライアントを初期化し、アプリがデバイスと通信できるようにします。
すべてのデバイスでEntity Sensingを使用できるとは限りません。次の例に示したようにalexa.capabilities
インターフェースを確認すると、デバイスでこのextensionを使用できるかどうかがわかります。
Alexa.create({version: "1.1"})
.then(async ({alexa, message, createExtensionsMessageProvider}) => {
if(alexa.capabilities.extensions['alexaext:entitysensing:10']) {
entitySensing = await EntitySensing.create(createExtensionsMessageProvider);
}
});
Entity Sensingの各種オブジェクト
EntitySensing
EntitySensing
オブジェクトを使用すると、デバイスによって検出されたユーザーに関する情報を取得できます。
EntitySensingオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
primaryUser |
最もエンゲージメントの高いユーザーに関する情報を取得するインターフェースを提供します。 詳細については、 プライマリユーザーの情報を取得する を参照してください。 |
PrimaryUser オブジェクト |
PrimaryUser
PrimaryUser
オブジェクトは、デバイスとのエンゲージメントが最も高いユーザーを表します(ただし、そのようなユーザーが存在する場合に限ります)。検出では、ウェイクワードを発話したことがあるエンティティがアクティブなユーザーであると判断され、ウェイクワードを発話したことがないエンティティは、エンゲージメントを持っていてもアクティブではないと判断されます。
プライマリユーザーには、デバイスによってエンティティid
が割り当てられます。エンティティがいったん視野から離れ、もう一度視野に戻ると、デバイスはベストエフォートでユーザーを既知のエンティティとして認識しようとします。既知のエンティティが視野に戻った場合は、そのid
は以前と変わりません。デバイスによって、ユーザーが既知のエンティティとして認識されなかった場合は、新しいid
が割り当てられます。割り当てられたid
は、デバイスがユーザーを認識できなくなってから一定期間持続します。この期間は、デバイスによって異なります。あるエンティティに以前割り当てられたid
が使用されなくなった場合でも、デバイスでそのid
が再利用されることはありません。
PrimaryUserオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
id |
デバイスによって割り当てられたプライマリユーザーのIDです。形式はデバイスによって異なります。ユーザーが検出されない場合、文字列は空です。 | 文字列 |
isActive |
プライマリユーザーがウェイクワードを発話した場合はtrue に設定します。それ以外の場合はfalse に設定します。 |
ブール値 |
isSeen |
デバイスがプライマリユーザーを検出し、そのユーザーがデバイスの観測可能範囲内にいる場合はtrue に設定します。エンティティが検出されなくなった場合、またはエンティティid が割り当てられていない場合はfalse に設定します。
|
ブール値 |
poise |
プライマリユーザーの位置です。 | EntityPoise オブジェクト |
EntityPoise
EntityPoise
オブジェクトは、プライマリユーザーの現在の角度位置を表します。EntityPoise
オブジェクトは角度を度単位で参照します。中心の軸を0度として反時計回りに移動すると、水平方向の正の値が増加します。デバイスの画面が回転しない場合は、同じ角度と相対位置になります。
EntityPoiseオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
absoluteAngle |
デバイスの中心を基準としたエンティティの現在の角度位置です。 | 数値 |
relativeAngle |
画面を基準としたエンティティの現在の角度位置です。 | 数値 |
EntitySensingState
EntitySensingState
オブジェクトは、Entity Sensingの機能の状態を識別します。エラーが発生するのは、さまざまな条件のためにデバイスが検出を行えない場合や、デバイスで機械的な障害が発生した場合です。エラーの一般的な原因は次のとおりです。
- 物理的な障害物がある
- 光が少ない
- デバイスが「おやすみモード」になっている
- ユーザーがカメラのシャッターを閉じた
errorCode
が0でない場合は、デバイスの機能が制限されます。デバイスはエラーを検出すると、エラー状態が解消したかどうかを定期的に確認します。エラー状態が解消していると、Entity Sensingの通常の動作が再開されます。
EntitySensingStateオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
error |
デバイスでEntity Sensingに関するエラーが発生していると、このプロパティにより、エラーの説明が示されます。 デバイスが正常に動作しているときは、 error の値は空の文字列になります。 |
数値 |
errorCode |
Entity Sensingの機能の状態を識別します。 エラーが発生すると、このプロパティによって0以外のエラーコードが報告されます。 デバイスが正常に動作している場合、 errorCode 値は0です。 |
数値 |
Alexaデバイスでは、次のようなerrorCode
と、それに対応するerror
の値を確認できます。error
の説明とerrorCode
の値は、デバイスごとに異なります。デバイスによっては、別の値が示される場合があります。エラーの文字列はローカライズされていません。
errorCode | 説明 | エラーテキストの例 |
---|---|---|
0 | – | The camera is working properly. |
1 | カメラに問題があるため、デバイスがユーザーを見つけることができません。 | Camera is disabled. Camera shutter is closed. |
error
とerrorCode
の値は、ゲームロジックの作成やデバッグを目的として使用します。ウェブアプリでは、error
やerrorCode
の値をユーザーに表示しないでください。
環境
Environment
オブジェクトでは、デバイスの静的プロパティを定義します。
Environmentオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
version |
Entity Sensing extensionのバージョンです。 | 文字列 |
verticalFOV |
Entity Sensingの垂直方向の視野範囲をデバイスごとに度単位で定義します。 | 数値 |
horizontalFOV |
Entity Sensingの水平方向の視野範囲をデバイスごとに度単位で定義します。 | 数値 |
Entity Sensingの各種インターフェース
ここに挙げたインターフェースを使用することで、ゲームのライフサイクル全体にわたってウェブアプリはEntity Sensingに関する更新を随時取得できます。
デバイスのプロパティを取得する
次の例に示したようにEnvironment
オブジェクトのプロパティを確認することで、デバイスの静的プロパティを取得できます。
let environment = entitySensing.environment;
プライマリユーザーの情報を取得する
デバイスからプライマリユーザーの状態を取得します。次の例のように、PrimaryUser
オブジェクトが返されます。
entitySensing.primaryUser;
次の表に、プライマリユーザーの想定される状態を示します。
isActive | isSeen | 意味 |
---|---|---|
true | true | ユーザーがウェイクワードを発話し、デバイスがユーザーを検出しました。poise は、ユーザーの現在位置を表します。 |
false | true | デバイスがユーザーを検出しましたが、そのユーザーがウェイクワードを発話しませんでした。poise は、ユーザーの現在位置を表します。 |
trueまたはfalse | false | デバイスがユーザーを検出できなくなった場合、poise は最後にユーザーを検出した位置を表します。 |
Entity Sensingの状態を取得する
デバイスのEntity Sensingの状態を取得します。次の例のように、EntitySensingState
オブジェクトが返されます。
entitySensing.entitySensingState;
関連トピック
- Alexa Web API for Gamesとは
- Web API for Gamesを使用したウェブアプリの開発
- ゲーム向けWeb API Extensionsの概要
- Alexa JavaScript API
最終更新日: 2021 年 04 月 15 日