APL Smart Motion extension

APL応答でSmart Motion extensionを使用すると、Echo Show 10などのモーション対応デバイスを制御できます。

Extensionの概要

Smart Motion extensionについて

Smart Motion APL extensionは、ディスプレイを回転させてユーザーを追跡し追尾できるデバイスで使用します。Smart Motion extensionを使用すると、次のようなことができます。

• ユーザーがウェイクワードを発話してスキルと対話するときに使用するビルトインモーションの動作を指定します。
• コマンドを実行してデバイスを移動します。
• デバイスを揺らすなど、あらかじめ用意されている一定のモーションを再生します。
• デバイスのモーション機能と現在の状態に関する情報を含むプロパティを取得します。
• イベントハンドラーを使用して、デバイスの状態の変化（画面の位置や角度の変化など）に対応します。

Smart Motion extensionは、すべての角度（度単位）と速度（度/秒）を参照します。正方向の回転は、回転軸の中心を0度とした反時計回りの回転です。

ビルトインSmart Motionの動作（ウェイクワード応答）

ユーザーがウェイクワードを発話してスキルと対話するときに使用されるビルトインデバイスモーションは、ウェイクワード応答によって決定されます。次の3つのオプションから選択できます。

• turnToWakeWord： Alexaがウェイクワードを認識すると、デバイスは話者の方向に向きを変え、動きを止めます。
• followOnWakeWord： Alexaがウェイクワードを認識すると、デバイスは話者の方向に向きを変え、移動を続けながら同じユーザーを追尾します。このデバイスは、コマンドでモーションが中断または変更されるまで、ユーザーの追尾を続けます。モーションはベストエフォートです。ユーザーを検出できない場合、デバイスはユーザーを検出できるまで移動しません。
• doNotMoveOnWakeWord： Alexaがウェイクワードを認識しても、デバイスは移動しません。

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

• ユーザーがスキルを呼び出すためのウェイクワードを発話したとき。

• ユーザーがスキルのセッション中にウェイクワードを発話してインテントを呼び出したとき。

  ユーザーはウェイクワードを発話する必要があります。ウェイクワードを発話せずにインテントを呼び出しても、ビルトインのウェイクワード応答モーションはトリガーされません。

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

スキルのウェイクワード応答は、複数の方法で設定できます。

• スキルマニフェストでウェイクワード応答のコンフィギュレーションを行います。スキルでAPLドキュメントをレンダリングする際には、デバイスでこのデフォルト設定が使用されます。マニフェストでSmart Motion extensionを設定する方法の詳細については、スキルマニフェストでのSmart Motion extensionを参照してください。
• APLドキュメントのextension settingsで、ウェイクワード応答を設定します。このデフォルト設定は、スキルマニフェストで指定された設定よりも優先されます。APLドキュメントのextension設定の詳細については、extensionの設定を参照してください。
• SetWakeWordResponseを実行します。このコマンドは、ドキュメントのextensionの設定やスキルマニフェストに指定された値よりも優先されます。

コマンドでモーションを制御する

コマンドを使用すると、デバイスのモーションを直接制御できます。デバイスを静止位置に移動したり、プライマリユーザーに向けたりすることができます。また、プライマリユーザーの追跡を開始したり、すべてのモーションを停止したりすることもできます。詳細については、コマンドを参照してください。

また、PlayNamedChoreoコマンドを使用すると、あらかじめ用意されている一定のモーション（デバイスを揺らすモーションなど）を実行できます。これらのあらかじめ用意されたモーションを、コレオと呼びます。PlayNamedChoreoコマンドを、視覚表現や音声表現を変更する他のコマンドと組み合わせると、モーションを使った魅力的な応答を作成できます。使用可能なコレオとその実行に必要な時間は、デバイスによって異なります。この情報を取得するには、availableChoreos環境変数を使用します。

モーションコマンドを実行すると、この新しいコマンドによって、ウェイクワード応答または前のコマンドからの既存のモーションがキャンセルされます。たとえば、スキルでfollowOnWakeWordを使用するとします。デバイスは移動して、ウェイクワードを発話したユーザーを追尾します。スキルでGoToRestPositionコマンドを実行します。このコマンドにより、ウェイクワード応答モーションがキャンセルされ、画面がデバイスの静止位置まで回転します。画面が移動を終えると、別のコマンドを実行するか、ユーザーが再びウェイクワードを発話してfollowOnWakeWordを再度有効にするまで、モーションは実行されません。

Smart Motion extensionを有効にする

Smart Motion extensionを有効にする方法は、このextensionをスキルで使用する方法によって異なります。

• スキル内のすべてのAPLドキュメントにデフォルトのウェイクワード応答を設定する場合 – extensionとウェイクワード応答設定をスキルマニフェストのautoInitializedExtensionsプロパティに追加します。

  これと同じウェイクワード応答をすべてのドキュメントで使用し、Smart Motionコマンド、プロパティ、イベントハンドラーを使用しない場合は、これ以上のコンフィギュレーションは不要です。

• extensionコマンド、プロパティ、イベントハンドラーを使用して、ドキュメント内のモーションエクスペリエンスを制御する場合 – 次の操作を行います。

  • extensionをスキルマニフェストのrequestedExtensionsプロパティに追加します。
  • 必要に応じて、スキルマニフェストのautoInitializedExtensionsに、extensionとデフォルトのウェイクワード応答を追加します。参照しているAPLドキュメントで、独自のウェイクワード応答が明示的に設定されていない場合、デバイスでは、このデフォルトが使用されます。
  • extensionをAPLドキュメントのextensionsプロパティに追加して、ドキュメントで明示的にリクエストします。
  • ドキュメントのsettingsプロパティで、extension設定のドキュメントレベルのコンフィギュレーションを行います。

スキルマニフェストでのSmart Motion extension

ALEXA_EXTENSIONインターフェースには、autoInitializedExtensionsとrequestedExtensionsという2つのプロパティがあります。

• autoInitializedExtensions – このプロパティにSmart Motion extensionを追加し、スキルのすべてのAPLドキュメントでデフォルトとして使用するようウェイクワード応答のコンフィギュレーションを行います。
• requestedExtensions – extensionコマンド、プロパティ、イベントハンドラーを使用する場合、このプロパティにSmart Motion extensionを追加します。

Smart Motion extensionのURIは、"Alexaext:smartmotion:10"です。

次の例は、Smart Motion extensionのコンフィギュレーションが行われたスキルマニフェストを示しています。この例では、デフォルトのウェイクワード応答をturnToWakeWordに設定しています。Smart Motion extensionを明示的にリクエストしないAPLドキュメントでは、このデフォルトが使用されます。マニフェストにもrequestedExtensionsにSmart Motionが含まれています。このため、指定されたAPLドキュメントで、extensionをリクエストしたり、turnToWakeWord応答を上書きしたり、コマンド、プロパティ、イベントハンドラーを使用したりすることもできます。

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

スキルマニフェストのAPL extension設定の詳細については、スキルマニフェストでextensionをリクエストするを参照してください。

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

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

1. 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
2. ビルド＞インターフェースページに移動します。
3. Alexa Presentation Languageインターフェースを有効にします。

4. デフォルトのウェイクワード応答を設定するには、クイックスタートの下にあるWake Word Responseリストから必要なオプションを選択します。

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

5. Smart Motionコマンド、プロパティ、イベントハンドラーを使用するには、ExtensionsリストからSmart Motion v.10を選択します。

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

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

APLドキュメントのSmart Motion extension

APLドキュメントでSmart Motion extensionコマンド、イベントハンドラー、プロパティを使用するには、ドキュメントのextensionsプロパティでextensionをリクエストする必要があります。スキルマニフェストでrequestedExtensionsにextensionを追加した場合も、このリクエストが必要です。

Smart Motion extensionのURIは、"Alexaext:smartmotion:10"です。

次の例では、Smart Motion extensionをリクエストし、その名前をSmartMotionに設定します。次に、ドキュメントで"SmartMotion"の名前を使用して、設定、プロパティ、コマンド、イベントハンドラーを参照します。

{
  "type": "APL",
  "version": "1.6",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ]
}

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

Smart Motion extensionがデバイスでサポートされるかを確認する

すべてのデバイスがSmart Motion extensionをサポートしているわけではありません。ユーザーのデバイスでextensionがサポートされるかどうかは、ドキュメントやコードで確認します。

APLドキュメントでデバイスのサポートを確認する

ドキュメントで環境プロパティを使用して、デバイスがSmart Motion extensionとウェイクワード応答をサポートしているかどうかを確認します。

デバイスでSmart Motion extensionがサポートされているかどうかを確認するには、environment.extensionプロパティを使用します。たとえば、extensionsプロパティでnameにSmartMotionを使用したとします。この場合、デバイスでSmart Motionがサポートされていれば、次のデータバインディング式でtrueが返されます。

${environment.extension.SmartMotion}

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

たとえば、extensionsプロパティでnameにSmartMotionを使用したとします。この場合、デバイスでウェイクワード応答がサポートされていれば、次のデータバインディング式でtrueが返されます。

${environment.extension.SmartMotion.wakeWordResponseSupported}

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

コードでデバイスのサポートを確認する

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

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

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

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

• スキルマニフェストのrequestedExtensionsプロパティでリクエストされていること。
• デバイスでサポートされていること。

extensionの設定

Smart Motion extensionには、次の設定があります。

APLドキュメントでこれらの設定を行うには、settings.AssignedNameを使用します。AssignedNameは、extensionsプロパティでSmart Motion extensionに割り当てられた名前です。

次の例では、extensionにSmartMotionという名前を割り当てた後、settings.SmartMotionでプロパティdeviceStateNameおよびwakeWordResponseを設定しています。

{
  "type": "APL",
  "version": "1.6",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "deviceStateName": "MyDeviceState",
      "wakeWordResponse": "followOnWakeWord"
    }
  },
  "mainTemplate": {}
}

deviceStateName

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

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

{
  "type": "APL",
  "version": "1.6",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "Device angle is ${MyDeviceState.poise.absoluteAngle}"
    }
  }
}

wakeWordResponse

wakeWordResponseプロパティでは、ユーザーがウェイクワードを発話したときに使用されるビルトインモーション応答を設定します。ウェイクワード応答の動作の詳細については、ビルトインSmart Motionの動作（ウェイクワード応答）を参照してください。

次の例では、最後にウェイクワードを発話したユーザーを追尾するようドキュメントのコンフィギュレーションを行います。

{
  "type": "APL",
  "version": "1.6",
  "theme": "dark",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100%",
        "text": "This document sets the wake-word response to <code>followOnWakeWord</code>.",
        "textAlign": "center",
        "textAlignVertical": "center"
      }
    ]
  }
}

APLドキュメントでwakeWordResponseに設定された値は、スキルマニフェストでコンフィギュレーションが行われたウェイクワード応答よりも優先されます。

環境プロパティ（静的）

Smart Motion extensionでは、次の静的環境プロパティが追加されます。

environment.extension.AssignedNameのデータバインディングコンテキストで、これらのプロパティにアクセスします。AssignedNameは、extensionsプロパティでSmart Motion extensionに割り当てられている名前です。

たとえば、extensionにSmartMotionという名前が割り当てられている場合、${environment.extension.SmartMotion.defaultWakeWordResponse}は、デバイスのデフォルトのウェイクワード応答を返します。

データバインディングコンテキストのenvironment.extensionプロパティの詳細については、extensionを参照してください。

version

Smart Motion extensionのバージョンを返します。

defaultWakeWordResponse

スキルでウェイクワード応答を明示的に設定していない場合、有効なデフォルトのウェイクワード応答を返します。ウェイクワード応答の動作の詳細については、ビルトインSmart Motionの動作（ウェイクワード応答）を参照してください。

デバイスでウェイクワード応答がサポートされていない場合、このプロパティは、未定義の値を返します。wakeWordResponseSupportedプロパティを使用すると、デバイスがウェイクワード応答をサポートしているかどうかを確認できます。

{
  "type": "Text",
  "text": "デフォルトのウェイクワード応答を${environment.extension.SmartMotion.defaultWakeWordResponse}に設定します。"
}

wakeWordResponseSupported

environmentのwakeWordResponseSupportedプロパティは、デバイスがウェイクワード応答をサポートしている場合にtrueを返します。

デバイスでウェイクワード応答がサポートされていない場合、このプロパティはfalseを返します。デバイスは、スキルマニフェスト、APLドキュメント、SetWakeWordResponseコマンドで設定されたウェイクワード応答を無視します。

デバイスはモーションとウェイクワード応答を同時にサポートすることはできません。他のモーション機能のステータスを確認するには、environment.extensionプロパティを使用します。

availableChoreos

デバイスで使用可能な名前付きコレオのコレクションを返します。availableChoreosプロパティは、使用可能な各コレオ（choreo）のオブジェクトを含むマップです。コレオを再生するには、PlayNamedChoreoを使用します。

choreo

choreoオブジェクトはデバイスで使用可能なコレオを記述します。以下の表は、choreoオブジェクトのプロパティを示しています。

ライブデータプロパティ

Smart Motion extensionは、ライブデータプロパティをデータバインディングコンテキストに追加します。ライブデータプロパティは、APLドキュメントのライフサイクル中に変更できるデータオブジェクトです。

Smart Motion extensionでは、データバインディングコンテキストに次のライブデータオブジェクトが追加されます。

ライブデータの詳細については、Extensionのライブデータを参照してください。

DeviceState

DeviceStateライブデータオブジェクトは、現在のデバイスの物理的な状態とデバイスの機能を表します。

DeviceStateにアクセスするには、extension settingsでdeviceStateNameプロパティを設定する必要があります。deviceStateNameがない場合、または空の文字列が含まれている場合、DeviceStateは使用できません。

以下の表は、DeviceStateプロパティを示しています。

完全なDeviceStateデータバインディングコンテキストの構造の例を次に示します。

{
  "error": "",
  "errorCode": 0,
  "motionLimit": {
    "minAngle": -20,
    "maxAngle": 30
  },
  "poise": {
    "absoluteAngle": 0,
    "angularVelocity": 0
  },
  "screenAngle": 0
}

error、errorCode

DeviceState.errorプロパティとDeviceState.errorCodeプロパティは、モーション関連のデバイスエラーに関する情報を報告します。

エラーが発生すると、errorCodeは0以外のコード、errorはエラーに関する説明を報告します。デバイスの動作中にエラーが発生していない場合、errorCodeは0を返し、errorは空の文字列を返します。

エラーは、意図したモーションとは反対方向に強い力が外側からデバイスに加わっているときや、機械的な故障が起こっているときに多く発生します。エラーの一般的な原因は、物理的な障害物があるか、デバイスが転倒していることです。

errorCodeが0でない場合は、デバイスの機能が制限されます。モーターコントローラーはerrorCodeイベントを検出するとシャットダウンし、errorCode条件がクリアされたかどうかを定期的に確認します。errorCode条件がクリアされると、モーターコントローラーの通常の動作が再開されます。

errorCodeの値が変化すると、OnDeviceStateChangedイベントがトリガーされます。

以下の表は、Alexaデバイスで利用可能なerrorCodeとそれに対応するerrorプロパティを示しています。errorの説明とerrorCodeの値はデバイスごとに異なります。このため、デバイスによっては別の値が示される場合があります。

これらのエラー値は、デバッグ目的で使用してください。errorの文字列はローカライズされません。このため、errorやerrorCodeの値はユーザーに表示しないでください。

motionLimit

DeviceState.motionLimitプロパティは、デバイスモーターのモーションの範囲が記述されたオブジェクトを返します。このオブジェクトには、次のプロパティがあります。

物理環境によっては、デバイスの動作が制限され、理論上の最大範囲まで動作しない場合があります。たとえば、ユーザーが壁を背にしてデバイスを置いているとします。壁が邪魔になって、モーターがモーションの最大範囲まで動けない場合が考えられます。

motionLimit値が変更されると、OnDeviceStateChangedイベントがトリガーされます。

poise

DeviceState.poiseプロパティは、画面表示の位置が記述されたオブジェクトを返します。以下の表は、poiseオブジェクトのプロパティを示しています。

poise.absoluteAngleは、デバイスの角度位置（度単位）を表します。poise.angularVelocityは、デバイスが動作しているときの現在のモーション速度（度/秒）を表します。

poise値が変化しても、OnDeviceStateChangedイベントはトリガーされません。

screenAngle

DeviceState.screenAngleプロパティは、画面の向き（度単位）を返します。画面の角度が0度の場合、画面は地面に対して直角になります。画面が後方に回転して真上に向いた状態では、screenAngleは45度です。

screenAngleが変化すると、OnDeviceStateChangedイベントがトリガーされます。

コマンド

Smart Motion extensionでは、新しいextensionコマンドが追加されます。

Smart Motionコマンドを実行するには、コマンドのtypeプロパティをAssignedName:CommandNameに設定します。AssignedNameは、extensionsプロパティでSmart Motion extensionに割り当てられた名前です。たとえば、extensionにSmartMotionという名前を割り当てた場合は、GoToRestPositionコマンドを実行するときに、SmartMotion:GoToRestPositionのように使います。

FollowPrimaryUser

エンゲージメントが最も高いユーザーがいる場合は、そのユーザーに従うようデバイスに指示します。エンゲージメントが最も高いユーザーは、PrimaryUserです。

デバイスが新しいPrimaryUserを割り当てると、FollowPrimaryUserコマンドの実行時にその新しいユーザーを追尾します。PrimaryUserがない場合、デバイスは、別のモーションコマンドまたはwakeWordResponseによってモーションがキャンセルされるまでユーザーを探し続けます。

FollowPrimaryUserは、前のモーションコマンド（wakeWordResponseなど）を実行した結果生じた現在のモーションをキャンセルします。

FollowPrimaryUserコマンドには、パラメーターはありません。

次の例では、ユーザーが"Let's Play Chase!"ボタンを選択したときにFollowPrimaryUserコマンドが実行されます。

{
  "type": "APL",
  "version": "1.6",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ],
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "doNotMoveOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "justifyContent": "center",
        "item": {
          "type": "AlexaButton",
          "alignSelf": "center",
          "buttonText": "Let's Play Chase!",
          "primaryAction": [
            {
              "type": "SmartMotion:FollowPrimaryUser"
            }
          ]
        }
      }
    ]
  }
}

GoToRestPosition

デバイスを静止位置に移動します。静止位置はデバイスごとに異なります。

GoToRestPositionは、前のモーションコマンド（wakeWordResponseなど）を実行した結果生じた現在のモーションをすべてキャンセルします。

GoToRestPositionコマンドには、パラメーターを指定する必要はありません。

次の例では、ユーザーが"Press to start the game"というテキストを選択すると、デバイスが静止位置に移動します。

{
  "type": "APL",
  "version": "1.6",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ],
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Container",
      "justifyContent": "center",
      "item": {
        "type": "AlexaButton",
        "alignSelf": "center",
        "buttonText": "Press to start the game",
        "primaryAction": [
          {
            "type": "SmartMotion:GoToRestPosition"
          }
        ]
      }
    }
  }
}

GoToCenter（廃止）

SetWakeWordResponse

デバイスの現在のビルトインウェイクワード応答モーションの動作を変更します。このコマンドにより、スキルマニフェストまたはextension設定で設定されたウェイクワード応答が上書きされます。ウェイクワード応答の詳細については、ビルトインSmart Motionの動作（ウェイクワード応答）を参照してください。

このコマンドを実行すると、ドキュメントのライフサイクルの間、このコマンドが再実行されるまで、新しいウェイクワード応答が有効になります。

SetWakeWordResponseコマンドのwakeWordResponseプロパティに指定された値が現在の応答動作と一致している場合、このコマンドによる影響はありません。

モーションコマンドを実行すると、この新しいコマンドによって、ウェイクワード応答または前のコマンドからの既存のモーションがキャンセルされます。この設定は持続し、次回ユーザーがウェイクワードを発話したときに動作が再開されます。

SetWakeWordResponseコマンドのプロパティは1つのみです。

wakeWordResponseをfollowOnWakeWordに設定すると、デバイスは最後にウェイクワードを発話したユーザーを追跡しようとします。wakeWordResponseをturnToWakeWordに設定すると、デバイスは次のウェイクワード発話を待ち受けます。

StopMotion

前のモーションコマンド（ウェイクワード応答を含む）を実行した結果生じた現在のモーションをキャンセルします。

TurnToPrimaryUser

エンゲージメントが最も高いユーザーがいる場合は、そのユーザーの方向に回転するようデバイスに指示します。エンゲージメントが最も高いユーザーは、PrimaryUserです。ウェイクワードを発話していないユーザーがPrimaryUserである場合もあります。

デバイスはPrimaryUserに向かって移動し、デバイスのディスプレイがユーザーのpoiseに一致すると停止します。ユーザーが移動している場合、デバイスがユーザーの角度と速度に一致するまでモーションは継続します。調整の精度は、デバイスごとに異なります。

このコマンドは、PrimaryUserが存在しないときは直ちに停止します。

TurnToPrimaryUserは、前のモーションコマンドを実行した結果生じた現在のモーションをキャンセルします。これには、wakeWordResponseも含まれます。

TurnToPrimaryUserコマンドには、パラメーターはありません。

次の例では、ドキュメントを読み込み、2秒の遅延をおいてからTurnToPrimaryUserコマンドが実行されます。

{
  "type": "APL",
  "version": "1.6",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "doNotMoveOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "Welcome to the Game.",
      "textAlign": "center",
      "textAlignVertical": "center"
    }
  },
  "onMount": [
    {
      "type": "SmartMotion:TurnToPrimaryUser",
      "delay": 2000
    }
  ]
}

PlayNamedChoreo

指定されたコレオを実行します。このコマンドを実行する前に、ユーザーのデバイスにコレオが存在することを確認します。使用可能なコレオのリストを取得するには、availableChoreos環境プロパティを使用します。

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

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

以下の表は、標準コマンドプロパティと、PlayNamedChoreoコマンドのプロパティを示しています。

name

実行するコレオの名前です。

利用可能なコレオ

次の名前付きコレオが利用できます。

実行する名前付きコレオです。次の名前付きコレオが利用できます。

イベントハンドラー

Smart Motion extensionでは、新しいextensionイベントハンドラーが追加されます。Smart Motion extensionで生成されたイベントに対応するには、APLドキュメントの最上位のプロパティにハンドラーを追加します。ハンドラー名には、AssignedName:EventHandlerNameを使用します。AssignedNameはextensionsプロパティでSmart Motion extensionに割り当てた名前、EventHandlerNameはハンドラーの名前です。

たとえば、extensionにSmartMotionという名前を設定した場合、OnDeviceStateChangedハンドラーからのイベントに対応するには、SmartMotion:OnDeviceStateChangedを使用します。

OnDeviceStateChanged

デバイスの状態が変化したときに呼び出されます。poise以外のデバイスプロパティが変更されると、OnDeviceStateChangedイベントがトリガーされます。

以下の表は、OnDeviceStateChangedハンドラーがイベントコンテキストに追加するプロパティを示しています。

DeviceStateプロパティのリストについては、DeviceStateを参照してください。

生成されるイベントの形式は次のようになります。

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

以下は、errorCodeプロパティが変更されたときにTextコマンドにバインドされるプロパティを更新するOnDeviceStateChangedハンドラーの例です。

{
  "type": "APL",
  "version": "1.6",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord",
      "deviceStateName": "DeviceState"
    }
  },
  "SmartMotion:OnDeviceStateChanged": [
    {
      "type": "SetValue",
      "componentId": "mainContainerId",
      "property": "FaultStatus",
      "value": "${event.changed.errorCode != 0 ? 'FAULTED' : 'NORMAL'}"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "id": "mainContainerId",
      "bind": [
        {
          "name": "FaultStatus",
          "value": ""
        }
      ],
      "items": [
        {
          "type": "Text",
          "text": "現在のデバイスのステータス: ${FaultStatus}"
        }
      ]
    }
  }
}

このイベントハンドラーのコマンドは、常に高速モードで実行されます。

画像フィルター

Smart Motion extensionは、新しい画像フィルターを追加しません。

関連トピック

• APL Extensions
• APL Entity Sensing Extension