APL Smart Motion extension



APL Smart-Motion Extension

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

Extensionの概要

サポートされるAPLの最小バージョン APL 1.4
Extension URI alexaext:smartmotion:10
設定
環境プロパティ
ライブデータプロパティ DeviceState
コマンド
イベントハンドラー OnDeviceStateChanged
画像フィルター なし
スキルマニフェストで必要か はい。Smart Motionコマンド、プロパティ、イベントハンドラーを使用するには、requestedExtensionsに追加します。スキルマニフェストでのSmart Motion extensionを参照してください。
設定は自動的に初期化されるか はい。wakeWordResponse設定は、autoInitializedExtensionsで設定できます。詳細については、スキルマニフェストでのSmart Motion 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インターフェースには、autoInitializedExtensionsrequestedExtensionsという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プロパティでnameSmartMotionを使用したとします。この場合、デバイスでSmart Motionがサポートされていれば、次のデータバインディング式でtrueが返されます。

${environment.extension.SmartMotion}

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

たとえば、extensionsプロパティでnameSmartMotionを使用したとします。この場合、デバイスでウェイクワード応答がサポートされていれば、次のデータバインディング式で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には、次の設定があります。

名前 デフォルト 説明
deviceStateName 文字列 "" DeviceStateデータバインディングに使用する名前です。
wakeWordResponse doNotMoveOnWakeWord | followOnWakeWord | turnToWakeWord デバイス独自のデフォルト デバイスがこのドキュメントをレンダリングするときに使用されるウェイクワード応答です。

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プロパティにアクセスできません。

次の例は、deviceStateNameMyDeviceStateに設定してから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では、次の静的環境プロパティが追加されます。

名前 デフォルト 説明
version 文字列 "" Smart Motion extensionのバージョンです。
defaultWakeWordResponse doNotMoveOnWakeWord | followOnWakeWord | turnToWakeWord "" デバイスのデフォルトのウェイクワード応答を返します。
wakeWordResponseSupported ブール値 false デバイスがウェイクワード応答をサポートしている場合は、trueを返します。
availableChoreos コレオのマップ {} このデバイスで利用可能な名前付きコレオ(choreos)です。

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オブジェクトのプロパティを示しています。

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

ライブデータプロパティ

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

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

名前 説明
DeviceState オブジェクト 現在のデバイスの物理的な状態とデバイスの機能を表します。

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

DeviceState

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

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

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

名前 説明
error 文字列 読み取り可能なエラーメッセージです。エラーがない場合は""です。
errorCode 数値 エラーコードです。エラーがない場合は0です。
motionLimit オブジェクト モーションの範囲です。
poise オブジェクト モーションと位置の状態です。
screenAngle 数値 表示方向(度単位)です。

完全な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の値はデバイスごとに異なります。このため、デバイスによっては別の値が示される場合があります。

errorCode 名前 エラーテキストの例
0 ENABLED  
1 DISABLED_BLOCKING Motion is blocked due to user interaction.
2 DISABLED_WW Commands are disabled due to wake word acknowledgment.

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

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

motionLimit

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

名前 説明
minAngle 数値 モーション範囲の最小角度(度単位)です。
maxAngle 数値 モーション範囲の最大角度(度単位)です。

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

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

poise

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

名前 説明
absoluteAngle 数値 画面表示の角度位置(度単位)です。
angularVelocity 数値 変化の回転速度(度/秒)です。

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 doNotMoveOnWakeWord | followOnWakeWord | turnToWakeWord デバイス独自のデフォルト 使用する新しいウェイクワード応答です。

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

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 文字列 必須 実行する名前付きコレオの名前です。このコレオは、デバイス上で利用可能でなければなりません。

name

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

利用可能なコレオ

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

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

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

イベントハンドラー

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ハンドラーがイベントコンテキストに追加するプロパティを示しています。

名前 説明
changed オブジェクト 変更されたDeviceStateプロパティのサブセットです。
current オブジェクト デバイス状態プロパティの完全なコレクションです。このプロパティ値は、イベント時のデバイス状態を表します。これには、イベントの影響を受ける値も含まれます。

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は、新しい画像フィルターを追加しません。