Web API Smart-Motion Extension



Web API Smart-Motion Extension

Smart Motion機能を備えたAlexa搭載デバイスは、デバイスを使用する可能性があるユーザーのいる方向を向くよう画面を動かしてそのユーザーを追跡できます。Smart Motion extensionを使用すると、次の操作を実行できます。

  • ユーザーがスキルを利用するためにウェイクワードを発話すると起動するビルトインモーションの動作を指定します。
  • ビルトインモーション機能とデバイスの現在の状態に関する情報を取得します。
  • デバイスを動かします。
  • デバイスを揺らすなど、あらかじめ用意されている一定のモーションを再生します。
  • 画面の位置や角度の変化など、デバイスの状態の変化に対応します。

ビルトインSmart Motionの動作

モーション対応デバイスでは、ウェイクワードに反応して実行されるビルトインモーションが用意されています。次のいずれかの設定で、デバイスのデフォルトの自動モーションを上書きできます。

  • turnToWakeWord: Alexaがウェイクワードを認識すると、デバイスは話者の方向に向きを変え、動きを止めます。
  • followOnWakeWord: Alexaがウェイクワードを認識すると、デバイスは話者の方向に向きを変え、別のモーションメソッドによって動作が中断されるまで、同じユーザーを追跡し続けます。モーションはベストエフォートです。ユーザーが視野から離れると、デバイスは動きを止めます。デバイスがユーザーを再検出すると、すぐに追跡が再開されます。
  • doNotMoveOnWakeWord: Alexaがウェイクワードを認識しても、デバイスは動きません。

デバイスは次の状況で、ウェイクワード応答で定義されたモーションを使用します。

デバイスでSmart Motion extensionがサポートされていても、ウェイクワード応答がサポートされていない場合があります。environmentのwakeWordResponseSupportedプロパティは、デバイスがウェイクワード応答をサポートしている場合にtrueを返します。

スキルのデフォルトのウェイクワード応答は、スキルマニフェストで設定します。設定したデフォルトの応答は、setWakeWordResponseインターフェースで上書きすることもできます。詳細については、ウェイクワード応答を設定するを参照してください。

アプリでモーションを制御する

Smart Motionの各種インターフェースを使用すると、デバイスのモーションを直接制御できます。デバイスを中心位置に合わせたり、プライマリユーザーに向けたりすることができます。プライマリユーザーの追跡を開始したり、すべてのモーションを停止したりすることもできます。詳細については、Smart Motionの各種インターフェースを参照してください。プライマリユーザーは、デバイスとのエンゲージメントが最も高いユーザーを表します。

デバイスを揺らすなど、一定のモーションを再生することもできます。このようなモーションは、コレオ(choreos)と呼ばれます。視覚または音声表現を変更する他のメソッドとコレオを組み合わせると、モーションを使った魅力的な応答を作成できます。使用可能なコレオとその実行に必要な時間は、デバイスによって異なります。

モーションAPIを呼び出すと、新しいモーションコマンドにより、それ以前にゲームによって呼び出されていたモーションAPIのモーションや、ウェイクワードに応答して開始されたモーションがキャンセルされます。wakeWordResponseの動作は、ユーザーが次回ウェイクワードを使用した時点で再開されます。たとえば、スキルがfollowOnWakeWord設定を使用しており、デバイスがウェイクワードを発話したユーザーを追跡しているとします。このとき、アプリがgotToCenterを呼び出すと、wakeWordResponseモーションがキャンセルされ、画面が中央の位置まで回転します。別のAPIを使用するか、ユーザーがウェイクワードをもう一度発話してfollowOnWakeWordを再度アクティブにするまで、それ以上のモーションが発生することはありません。

スキルでSmart Motion extensionを有効にする

スキルでSmart Motion extensionを有効にするには、以下を行う必要があります。

  • スキルマニフェストのrequestedExtensionsプロパティにSmart Motion extensionを追加します。
  • (任意)スキルマニフェストのautoInitializedExtensionsプロパティに、extensionとデフォルトのウェイクワード応答を追加します。ウェブアプリで独自のウェイクワード応答が明示的に設定されていない場合は、このデフォルトの応答が使用されます。

スキルマニフェストにextensionを追加する方法には、ASKコマンドラインインターフェース(CLI)と開発者コンソールの2種類があります。スキルマニフェストにextensionsを追加する方法の詳細については、スキルにextensionsを追加するを参照してください。

CLIを使用してextensionを追加する

Smart Motion extensionを有効にするには、スキルマニフェストのJSONファイルにALEXA_EXTENSIONインターフェースを追加します。ALEXA_EXTENSIONインターフェースには、autoInitializedExtensionsrequestedExtensionsという2つのプロパティがあります。requestedExtensionsプロパティにSmart Motion extensionを追加し、autoInitializedExtensionsプロパティにデフォルトのウェイクワード応答を追加します。

Smart Motion extensionのURIはalexaext:smartmotion:10です。

次の例は、Smart Motion extensionのコンフィギュレーションが行われたスキルマニフェストを示しています。この例では、デフォルトのウェイクワード応答をfollowOnWakeWordに設定しています。ウェイクワード応答を明示的に設定していないウェブアプリでは、このデフォルトを使用します。マニフェストにはrequestedExtensionsにSmart Motionがあるため、setWakeWordResponseを使ってアプリのfollowOnWakeWord応答を上書きできます。詳細については、ウェイクワード応答を設定するを参照してください。

{
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "ALEXA_EXTENSION",
          "requestedExtensions": [
            {
              "uri": "alexaext:smartmotion:10"
            }
          ],
          "autoInitializedExtensions": [
            {
              "uri": "alexaext:smartmotion:10",
              "settings": {
                "wakeWordResponse": "followOnWakeWord"
              }
            }
          ]
        }
      ]
    }
  }
}

マニフェストファイルを保存したら、Alexa Skills Kitコマンドラインインターフェースを使用して、変更後のマニフェストをデプロイします。

開発者コンソールでextensionを追加する

開発者コンソールでスキルマニフェストのコンフィギュレーションを行うこともできます。

Smart Motion extensionのスキルのコンフィギュレーションを行うには

  1. 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
  2. ビルド>インターフェースページに移動します。
  3. Alexa Web API for Gamesインターフェースを有効にします。
  4. デフォルトのウェイクワード応答のコンフィギュレーションを行うには、Smart Motion Policyの下にあるWake Word Responseリストから必要なオプションを選択します。
    オプションを選択すると、スキルマニフェストのautoInitializedExtensionsプロパティが更新されます。
  5. Alexa Extensionsリストから、Smart Motion v.10を選択します。
    このオプションを選択すると、ALEXA_EXTENSIONインターフェースとrequestedExtensionsプロパティがスキルマニフェストに追加されます。
  6. インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。

ウェブアプリにextensionを追加する

Alexa JavaScript extensionライブラリをロードするには、次の例のように、HTMLページのscriptタグにURLを含める必要があります。

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

<head>
      <script src="https://cdn.html.games.alexa.a2z.com/extensions/smart-motion/v10/smart-motion.js"></script>
</head>

次のコードを使用してSmart Motion extensionクライアントを初期化し、アプリがデバイスと通信できるようにします。すべてのデバイスでモーションを使用できるとは限りません。次の例に示したようにalexa.capabilitiesオブジェクトを確認すると、デバイスでこのextensionを使用できるかどうかがわかります。

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

Alexa.create({version: "1.1"})
    .then(async ({alexa, message, createExtensionsMessageProvider}) => {
        if(alexa.capabilities.extensions['alexaext:smartmotion:10']) {
            smartMotion = await SmartMotion.create(createExtensionsMessageProvider);
        }
    }); 

Smart Motionの各種オブジェクト

deviceState

deviceStateオブジェクトを使用すると、モーションの範囲や現在のデバイスの位置、速度、角度の詳細など、デバイスに関する最新情報を取得できます。ゲームのライフサイクル中は、デバイスの動きに合わせてデータが変化します。更新の取得には、deviceStateインターフェースを使用します。詳細については、デバイスの最新の状態を取得するを参照してください。

deviceStateオブジェクトは、角度(度単位)と速度(度/秒)を参照します。正方向の回転は、回転軸の中心を0度とした反時計回りの回転です。

deviceStateオブジェクトの詳細

プロパティ 説明
motionLimit デバイスのモーションの機能範囲。 motionLimitオブジェクト
poise デバイスの現在の位置と速度。 poiseオブジェクト
screenAngle 画面の垂直方向の向き(度単位)。
値が0度の場合、画面が直立している(地面に対して垂直である)ことを表します。正の値は、画面が上に向いていることを表します。
数値
error エラーが発生している場合に、errorCodeプロパティで検出されたエラー値について説明するテキスト文字列。
デバイスが想定どおりに動作しているときは、この値は空の文字列になります。
文字列
errorCode デバイスのモーション機能の状態。
この値は、デバイスが想定どおりに動作している場合は0、デバイスにモーションのエラーが発生している場合は0以外になります。errorCodeの値はデバイスによって異なります。
数値

errorプロパティとerrorCodeプロパティは、モーション関連のデバイスエラーに関する情報を提供するものです。エラーが発生すると、errorCodeでは0以外の値、errorではエラーに関する説明が、それぞれ報告されます。エラーは、意図したモーションとは反対方向に強い力が外側からデバイスに加わっているときや、機械的な故障が起こっている場合に多く発生します。エラーの一般的な原因は、物理的な障害物がある、またはデバイスが転倒していることです。errorCodeが0でない場合は、デバイスの機能が制限されます。デバイスはエラーを検出すると、エラー状態が解消したかどうかを定期的に確認します。エラー状態が解消していると、通常のモーション操作が再開されます。

Alexaデバイスでは、次のようなerrorCodeと、それに対応するerrorの値を確認できます。errorの説明とerrorCode値はデバイスによって異なるため、デバイスによっては他の値が報告されることがあります。エラーの文字列はローカライズされていません。

errorCode error
0
1 Motion is blocked due to user interaction.
2 Commands are disabled due to wake word acknowledgment.

たとえば、このエラーは、ユーザーがウェイクワードを発話すると同時にアプリがモーションコマンドを呼び出したときに発生します。この場合は、ウェイクワード応答がコマンドより優先されます。
3 Commands are disabled due to system-initiated motion.
4 Smart motion is disabled by the user.

errorerrorCodeの値は、ゲームロジックの作成やデバッグを目的として使用します。ウェブアプリでは、errorerrorCodeの値をユーザーに表示しないでください。

motionLimit

motionLimitオブジェクトでは、デバイスのモーションの範囲を記述します。物理環境によっては、デバイスの動作が制限され、最大範囲まで動作しない場合があります。たとえば、ユーザーが壁の隣にデバイスを配置すると、壁によってデバイスのモーションの範囲が制限されることがあります。

motionLimitオブジェクトの詳細

プロパティ 説明
minAngle モーション範囲の下限(度単位) 数値
maxAngle モーション範囲の上限(度単位) 数値

poise

poiseオブジェクトは、デバイス画面の現在の角度位置と速度を表します。poiseオブジェクトは、角度(度単位)と速度(度/秒)を参照します。

poiseオブジェクトの詳細

プロパティ 説明
absoluteAngle デバイス画面の現在の角度位置 数値
angularVelocity デバイス画面の現在のモーション速度(度/秒) 数値

environment

environmentオブジェクトでは、デバイスの静的プロパティを定義します。

environmentオブジェクトの詳細

プロパティ 説明
version Smart Motion extensionのバージョン。 文字列
defaultWakeWordResponse スキルマニフェストで設定されているデフォルトのウェイクワード応答。
デバイスがウェイクワードに応答するモーションをサポートしていない場合、このプロパティは設定されません。
文字列
wakeWordResponseSupported デバイスがウェイクワード応答をサポートしている場合はTrue。
デバイスがウェイクワード応答をサポートしていない場合はFalse。スキルマニフェストでコンフィギュレーションを行い、setWakeWordResponseを使用してアプリに設定したウェイクワード応答が、デバイスにより無視されます。
ブール値
availableChoreos このデバイスで利用可能な名前付きコレオ。 choreosオブジェクト

choreos

choreosオブジェクトは、デバイスで使用可能な名前付きコレオのマップです。コレオの再生には、playNamedChoreoを使用します。詳細は、コレオを再生するを参照してください。

ScreenImpactCenterコレオの詳細

ScreenImpactCenterコレオは、デバイスをすばやく左右に揺らすモーションを呼び出します。デバイスの現在の位置を基準にモーションが開始されます。

プロパティ 説明
approximateDuration(数値) コレオが再生されるおよその時間(ミリ秒単位)。
数字は静的なものではなく、デバイスの位置によって変わる可能性があります。この値を使用して、画面上の視覚要素とコレオのモーションを大まかに同期します。
数値

Smart Motionの各種インターフェース

デバイスのプロパティを取得する

environmentオブジェクトを確認すると、デバイスの静的プロパティを取得できます。次の例は、デバイスのプロパティを読み取り、コレオがサポートされているかどうかを確認するものです。

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

    let environment = smartMotion.environment;
    // ScreenImpactCenterコレオのサポートを確認する
    let availableChoreos = environment.availableChoreos;
    if (availableChoreos.ScreenImpactCenter) {
        duration = availableChoreos.ScreenImpactCenter.approximateDuration;
    }     

デバイスでモーションがサポートされていても、ビルトインウェイクワード応答モーションがサポートされていない場合があります。wakeWordResponseSupportedプロパティを使用すると、デバイスがウェイクワード応答をサポートしているかどうかを確認できます。次の例は、モーションをサポートするデバイスでウェイクワード応答モーションがサポートされているかどうかを確認するものです。

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

    let environment = smartMotion.environment;
    //ビルトインウェイクワード応答モーションのサポートを確認する
    if (environment.wakeWordResponseSupported) {
        defaultResponse = environment.defaultWakeWordResponse;
    }     

デバイスの最新の状態を取得する

モーションの範囲、現在のデバイスの位置、速度、角度などの詳細についての最新情報を取得します。次の例のように、このインターフェースはdeviceStateを返します。

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

    let deviceState = smartMotion.deviceState; 

プライマリユーザーを追跡する

デバイスとのエンゲージメントが最も高いユーザーを追跡させるには、次の例のようにします。

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

    smartMotion.followPrimaryUser(); 

エンゲージメントが最も高いユーザーが、プライマリユーザーです。

followPrimaryUserが呼び出された後にデバイスが新しいプライマリユーザーを割り当てた場合、デバイスはその新しいプライマリユーザーを追跡します。ユーザーが検出されなかったり、視野から離れたりしたときは、デバイスは別のモーションコマンドまたはwakeWordResponseでモーションがキャンセルされるまで、ユーザーを探し続けます。

このアクションは、ウェイクワードによって開始されたモーションなど、現在進行中のモーションをキャンセルします。

中心に移動する

デバイスを中心位置に移動するには、次の例のようにします。

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

    smartMotion.goToCenter(); 

中央の位置は、デバイスごとに異なります。このアクションは、ウェイクワードによって開始されたモーションなど、現在進行中のモーションをキャンセルします。

コレオを再生する

指定したコレオをデバイスに再生させるには、次の例のようにします。

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

    smartMotion.playNamedChoreo({name}); 

playNamedChoreoOptionsオブジェクトは、コレオを定義するものです。

プロパティ 説明
name コレオの名前。
有効な値は、choreosオブジェクトによって定義されます。たとえば、"ScreenImpactCenter"です。
文字列

コレオを実行すると、進行中のモーションがキャンセルされます。複数のコレオを同時に実行することはできません。playNamedChoreoを複数回呼び出した場合、最後のインスタンスにより、以前に実行したコレオがキャンセルされます。

ウェイクワード応答を設定する

ウェイクワードに対するデバイスのビルトインモーション応答を設定するには、次の例のようにします。このアクションは、現在の設定を上書きします。

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

    smartMotion.setWakeWordResponse({wakeWordResponse}); 

wakeWordResponseOptionsオブジェクトでは、ウェイクワードが聞こえたときのデバイスの応答を定義します。

プロパティ 説明
wakeWordResponse デバイスに対して設定された応答オプション。
有効な値はdoNotMoveOnWakeWordfollowOnWakeWordturnToWakeWordです。
文字列

wakeWordResponsefollowOnWakeWordに設定すると、デバイスは最後にウェイクワードを発話したユーザーを追跡しようとします。wakeWordResponseturnToWakeWordに設定すると、デバイスは次のウェイクワード発話を待ち受けます。wakeWordResponseの詳細については、ビルトインSmart Motionの動作を参照してください。

モーションを停止する

ウェイクワードによって開始されたモーションなど、現在進行中のモーションをキャンセルするには、次の例のようにします。

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

    smartMotion.stopMotion(); 

プライマリユーザーに切り替える

エンゲージメントが最も高いユーザーの方向にデバイスを回転させるには、次の例のようにします。

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

    smartMotion.turnToPrimaryUser(); 

エンゲージメントが最も高いユーザーが、プライマリユーザーです。

デバイスは、プライマリユーザーの方に向きを変え、デバイスのディスプレイがユーザーのpoise(角度と速度)に一致すると停止します。ユーザーが移動している場合、デバイスがユーザーの角度と速度に一致するまでモーションが継続します。一致の精度はデバイスによって異なります。ユーザーが視野から離れたとき、またはデバイスによってユーザーが検出されなかったときは、モーションが停止します。

このアクションは、ウェイクワードによって開始されたモーションなど、現在進行中のモーションをキャンセルします。