Web API Entity-Sensing Extension

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のスキルのコンフィギュレーションを行うには

  1. 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
  2. ビルド＞インターフェースページに移動します。
  3. Alexa Web API for Gamesインターフェースを有効にします。
  4. Alexa Extensionsリストから、Entity Sensing v.10を選択します。
    このオプションを選択すると、ALEXA_EXTENSIONインターフェースとrequestedExtensionsプロパティがスキルマニフェストに追加されます。
  5. インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。

ウェブアプリに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;
このページは役に立ちましたか？

最終更新日: 2021 年 04 月 15 日