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は、すべての角度(度単位)と速度(度/秒)を参照します。正方向の回転は、回転軸の中心を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コマンドを使用すると、あらかじめ用意されている一定のモーション(デバイスを揺らすモーションなど)を実行できます。これらの事前に作成されたモーションは、コレオ(choreos)と呼ばれます。PlayNamedChoreoコマンドを、視覚表現や音声表現を変更する他のコマンドと組み合わせると、モーションを使った魅力的な応答を作成できます。使用可能なコレオとその実行に必要な時間は、デバイスによって異なります。この情報を取得するには、availableChoreos環境変数を使用します。

モーションコマンドを実行すると、この新しいコマンドによって、ウェイクワード応答または前のコマンドからの既存のモーションがキャンセルされます。たとえば、スキルでfollowOnWakeWordを使用するとします。デバイスは移動して、ウェイクワードを発話したユーザーを追尾します。スキルでGoToCenterコマンドを実行します。これにより、ウェイクワード応答モーションがキャンセルされ、画面が中央の位置まで回転します。画面が中央の位置への移動を終えると、別のコマンドを実行するか、ユーザーが再びウェイクワードを発話して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コマンド、プロパティ、イベントハンドラーを使用するには、エクステンションリストから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.4",
  "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.4",
  "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.4",
  "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.4",
  "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プロパティを使用すると、デバイスがウェイクワード応答をサポートしているかどうかを確認できます。

wakeWordResponseSupported

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

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

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

availableChoreos

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

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プロパティは、画面表示の位置が記述されたオブジェクトを返します。このオブジェクトには、次のプロパティがあります。

名前 説明
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という名前を割り当てた場合は、GoToCenterコマンドを実行するときに、SmartMotion:GoToCenterのように入力します。

FollowPrimaryUser

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

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

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

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

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

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

{
  "type": "APL",
  "version": "1.4",
  "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"
            }
          ]
        }
      }
    ]
  }
}

GoToCenter

デバイスを中央の位置に移動します。中央の位置は、デバイスごとに異なります。

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

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

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

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

{
  "type": "APL",
  "version": "1.4",
  "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: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.4",
  "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 デバイスをすばやく左右に揺らすモーション。デバイスの現在の位置を基準にモーションが開始されます。

イベントハンドラー

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ハンドラーでは、イベントコンテキストに次の2つのプロパティが追加されます。

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

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

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

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

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