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の各種インターフェースを参照してください。プライマリユーザーは、デバイスとのエンゲージメントが最も高いユーザーを表します。

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

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

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

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

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

Alexa Skills Kit（ASK）コマンドラインインターフェース（CLI）か開発者コンソールを使って、スキルマニフェストにextensionを追加できます。スキルマニフェストにextensionsを追加する方法の詳細については、スキルにextensionsを追加するを参照してください。

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

Smart Motion extensionを有効にするには、スキルマニフェストのJSONファイルにALEXA_EXTENSIONインターフェースを追加します。ALEXA_EXTENSIONインターフェースには、autoInitializedExtensionsとrequestedExtensionsという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.

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

MotionLimit

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

MotionLimitオブジェクトの詳細

プロパティ 説明 型
minAngle モーション範囲の下限（度単位）です。 数値
maxAngle モーション範囲の上限（度単位）です。 数値

Poise

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

Poiseオブジェクトの詳細

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

環境

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

Environmentオブジェクトの詳細

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

Choreos

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

Choreosの詳細

プロパティ 説明 型
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.goToRestPosition();

静止位置は、デバイスごとに異なります。このアクションは、前のモーションコマンドを呼び出した結果生じた現在のモーションをすべてキャンセルします。これには、ウェイクワードによって開始されたモーションも含まれます。

コレオを再生する

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

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

    smartMotion.playNamedChoreo(playNamedChoreoOptions);
    const playNamedChoreoOptions = {
        name: "ScreenImpactCenter"
    }

PlayNamedChoreoOptionsオブジェクトによりコレオを定義します。

プロパティ 説明 型
name コレオの名前です。
有効な名前については、利用可能なコレオを参照してください。		 文字列

すべてのコレオは、デバイスの現在位置を基準にモーションを開始します。このコマンド実行時にデバイスがモーション範囲制限の近くにある場合、デバイスはまずその制限から離れます。これにより、デバイスはコレオのモーションを全範囲で実行できるようになります。コレオが終了すると、デバイスは元の開始位置に戻ります。

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

利用可能なコレオ

Smart Motion extensionでは、次の名前付きコレオをサポートします。

名前 説明
ClockwiseMediumSweep 時計回りに流れる滑らかなモーションです。
CounterClockwiseSlowSweep 反時計回りに流れるゆっくりとした滑らかなモーションです。
MixedExpressiveShakes デバイスの現在の向きをすばやく連続で左右に揺らします。
ScreenImpactCenter デバイスをすばやく左右に揺らすモーションです。

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

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

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

    smartMotion.setWakeWordResponse({wakeWordResponseOptions});
    const wakeWordResponseOptions = {
        wakeWordResponse: "turnToWakeWord"
    }

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

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

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

モーションを停止する

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

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

    smartMotion.stopMotion();

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

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

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

    smartMotion.turnToPrimaryUser();

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

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

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

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

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