APLスマートモーション拡張機能

APL応答でスマートモーション拡張機能を使用すると、Echo Show 10などのモーション対応デバイスを制御できます。

拡張機能の概要

スマートモーション拡張機能について

APLスマートモーション拡張機能は、ディスプレイを回転させてユーザーを追跡および追尾できるデバイスで動作します。スマートモーション拡張機能を使用すると、次のような操作を行うことができます。

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

スマートモーション拡張機能は、すべての角度を度単位で表し、速度を度/秒で表します。正方向の回転は、中心の回転軸を0度とした反時計回りの回転です。

ビルトインのスマートモーションの動作（ウェイクワード応答）

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

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

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

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

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

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

デバイスでスマートモーション拡張機能がサポートされていても、ウェイクワード応答がサポートされていない場合があります。wakeWordResponseSupported環境プロパティは、デバイスがウェイクワード応答をサポートしている場合にtrueを返します。

スキルのウェイクワード応答を設定するには、複数の方法があります。

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

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

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

PlayNamedChoreoコマンドを使用して、プリビルドの定型モーションを再生することもできます。たとえば、デバイスを揺らすモーションを実行できます。このようなプリビルドのモーションは「コレオ」と呼ばれます。視覚表現や音声表現を変更するほかのコマンドとPlayNamedChoreoコマンドを組み合わせると、モーションに対応する魅力的な応答を作成できます。使用可能なコレオとその実行に必要な時間は、デバイスによって異なります。この情報を取得するには、availableChoreos環境変数を使用します。

モーションコマンドを実行すると、その新しいコマンドにより、ウェイクワード応答や前のコマンドから継続している既存のモーションがキャンセルされます。たとえば、スキルでfollowOnWakeWordを使用したとします。デバイスは、ウェイクワードを発話したユーザーの方に向いて追尾します。次に、スキルでGoToRestPositionコマンドを実行します。このコマンドにより、ウェイクワード応答モーションがキャンセルされ、画面がデバイスの静止位置まで回転します。デバイスが動きを停止した後は、別のコマンドを実行するか、ユーザーが再びウェイクワードを発話してfollowOnWakeWordが再アクティブ化されるまで、モーションは実行されません。

スマートモーション拡張機能を有効にする

スマートモーション拡張機能を有効にする方法は、この拡張機能をスキルでどのように使用するかによって異なります。

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

  この同じウェイクワード応答をすべてのドキュメントで使用し、スマートモーションのコマンド、プロパティ、イベントハンドラーを使用しない場合は、これ以上の設定は必要ありません。

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

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

スキルマニフェストでのスマートモーション拡張機能

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

• autoInitializedExtensions - このプロパティにスマートモーション拡張機能を追加して、スキルのすべてのAPLドキュメントでデフォルトとして使用するウェイクワード応答を設定できます。
• requestedExtensions - スマートモーション拡張機能のコマンド、プロパティ、イベントハンドラーを使用する場合は、このプロパティに拡張機能を追加します。

スマートモーション拡張機能のURIは、"alexaext:smartmotion:10"です。

次の例は、スマートモーション拡張機能が設定されたスキルマニフェストを示しています。この例では、デフォルトのウェイクワード応答をturnToWakeWordに設定しています。スマートモーション拡張機能を明示的にリクエストしないAPLドキュメントでは、このデフォルトが使用されます。マニフェストのrequestedExtensionsにもスマートモーションが含まれているため、特定のAPLドキュメントで拡張機能をリクエストし、turnToWakeWord応答をオーバーライドしたり、コマンド、プロパティ、イベントハンドラーを使用したりすることもできます。

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

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

開発者コンソールでスキルマニフェストを設定することもできます。

スマートモーション拡張機能を使用するようにスキルを設定するには

1. 開発者コンソールを開き、設定するスキルを見つけて編集をクリックします。
2. ビルド＞インターフェースページに移動します。
3. Alexa Presentation Languageインターフェースを有効にします。

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

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

5. スマートモーションのコマンド、プロパティ、イベントハンドラーを使用するには、拡張機能の一覧でSmart Motion v.10をオンにします。

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

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

APLドキュメントでのスマートモーション拡張機能

APLドキュメントでスマートモーション拡張機能のコマンド、イベントハンドラー、プロパティを使用するには、ドキュメントのextensionsプロパティで拡張機能をリクエストする必要があります。これは、スキルマニフェストのrequestedExtensionsに拡張機能を追加することに加えて求められる要件です。

スマートモーション拡張機能のURIは、"alexaext:smartmotion:10"です。

次の例では、スマートモーション拡張機能をリクエストし、その名前をSmartMotionに設定します。その後、ドキュメントで「SmartMotion」という名前を使用して、設定、プロパティ、コマンド、イベントハンドラーを参照できます。

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

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

デバイスでスマートモーション拡張機能がサポートされるかどうかを確認する

スマートモーション拡張機能は、すべてのデバイスでサポートされるとは限りません。ユーザーのデバイスで拡張機能がサポートされるかどうかを、ドキュメントやコードで確認する必要があります。

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

ドキュメントでは、環境プロパティを使用して、デバイスでスマートモーション拡張機能とウェイクワード応答がサポートされるかどうかを確認します。

デバイスでスマートモーション拡張機能がサポートされるかどうかを確認するには、environment.extensionプロパティを使用します。たとえば、extensionsプロパティでnameにSmartMotionを指定したとすると、デバイスでスマートモーションがサポートされていれば、次のデータバインディング式からtrueが返されます。

${environment.extension.SmartMotion}

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

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

${environment.extension.SmartMotion.wakeWordResponseSupported}

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

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

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

次の例は、スマートモーション拡張機能をサポートするデバイスからのリクエストを示しています。

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

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

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

拡張機能の設定

スマートモーション拡張機能には、次の設定があります。

APLドキュメントでこれらの設定を行うには、settings.AssignedNameという形式を使用します。AssignedNameは、extensionsプロパティでスマートモーション拡張機能に割り当てた名前です。

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

{
  "type": "APL",
  "version": "2024.3",
  "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": "2024.3",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "デバイスの角度は${MyDeviceState.poise.absoluteAngle}度です。"
    }
  }
}

wakeWordResponse

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

次の例では、最後にウェイクワードを発話したユーザーを追尾するようにドキュメントを設定します。

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100%",
        "text": "このドキュメントでは、ウェイクワード応答を<code>followOnWakeWord</code>に設定しています。",
        "textAlign": "center",
        "textAlignVertical": "center"
      }
    ]
  }
}

APLドキュメントでwakeWordResponseに設定した値は、スキルマニフェストのウェイクワード応答の設定よりも優先されます。

環境プロパティ（静的）

スマートモーション拡張機能により、次の静的環境プロパティが追加されます。

これらのプロパティにアクセスするには、データバインディングコンテキストのenvironment.extension.AssignedNameを使用します。AssignedNameは、extensionsプロパティでスマートモーション拡張機能に割り当てた名前です。

たとえば、拡張機能にSmartMotionという名前を割り当てたとすると、${environment.extension.SmartMotion.defaultWakeWordResponse}によってデバイスのデフォルトのウェイクワード応答が返されます。

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

version

スマートモーション拡張機能のバージョンを返します。

defaultWakeWordResponse

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

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

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

wakeWordResponseSupported

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

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

デバイスによっては、モーションをサポートしていながら、ウェイクワード応答をサポートしていないこともあり得ます。ほかのモーション機能のステータスを確認するには、environment.extensionプロパティを使用します。

availableChoreos

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

choreo

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

ライブデータプロパティ

スマートモーション拡張機能は、データバインディングコンテキストにライブデータプロパティを追加します。ライブデータプロパティは、APLドキュメントのライフサイクル中に変更される可能性のあるデータオブジェクトです。

スマートモーション拡張機能により、データバインディングコンテキストに次のライブデータオブジェクトが追加されます。

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

DeviceState

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

DeviceStateにアクセスするには、拡張機能の設定で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イベントがトリガーされます。

コマンド

スマートモーション拡張機能により、新しい拡張機能コマンドが追加されます。

スマートモーションのコマンドを実行するには、コマンドのtypeプロパティをAssignedName:CommandNameに設定します。AssignedNameは、extensionsプロパティでスマートモーション拡張機能に割り当てた名前です。たとえば、拡張機能にSmartMotionという名前を割り当てたとすると、GoToRestPositionコマンドはSmartMotion:GoToRestPositionとして実行できます。

FollowPrimaryUser

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

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

FollowPrimaryUserは、前のモーションコマンド（wakeWordResponseを含む）を実行した結果として続いている現在のモーションをキャンセルします。

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

次の例は、ユーザーが「追いかけましょう」というボタンを押したときに、FollowPrimaryUserコマンドを実行します。

{
  "type": "APL",
  "version": "2024.3",
  "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": "追いかけましょう",
          "primaryAction": [
            {
              "type": "SmartMotion:FollowPrimaryUser"
            }
          ]
        }
      }
    ]
  }
}

GoToRestPosition

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

GoToRestPositionは、前のモーションコマンド（wakeWordResponseを含む）を実行した結果として続いている現在のモーションをキャンセルします。

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

次の例は、ユーザーが「ここを押してゲームを開始」というテキストを押したときに、デバイスを静止位置まで動かします。

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.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": "ここを押してゲームを開始",
        "primaryAction": [
          {
            "type": "SmartMotion:GoToRestPosition"
          }
        ]
      }
    }
  }
}

GoToCenter（廃止）

SetWakeWordResponse

デバイスの現在のビルトインウェイクワード応答モーションの動作を変更します。このコマンドは、スキルマニフェストまたは拡張機能の設定で指定されたウェイクワード応答をオーバーライドします。ウェイクワード応答の詳細については、ビルトインのスマートモーションの動作（ウェイクワード応答）を参照してください。

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

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

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

SetWakeWordResponseコマンドには、プロパティが1つあります。

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

StopMotion

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

TurnToPrimaryUser

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

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

このコマンドは、PrimaryUserが存在しないときは即座に終了します。

TurnToPrimaryUserは、前のモーションコマンド（wakeWordResponseを含む）を実行した結果として続いている現在のモーションをキャンセルします。

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

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

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "doNotMoveOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "ゲームへようこそ。",
      "textAlign": "center",
      "textAlignVertical": "center"
    }
  },
  "onMount": [
    {
      "type": "SmartMotion:TurnToPrimaryUser",
      "delay": 2000
    }
  ]
}

PlayNamedChoreo

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

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

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

PlayNamedChoreoコマンドには、標準のコマンドプロパティに加えて、次の表に示すプロパティがあります。

name

再生するコレオの名前です。

使用可能なコレオ

次の名前付きコレオを使用できます。

再生する名前付きコレオです。次の名前付きコレオを使用できます。

イベントハンドラー

スマートモーション拡張機能により、新しい拡張機能イベントハンドラーが追加されます。スマートモーション拡張機能で生成されるイベントに応答するには、APLドキュメントのトップレベルのプロパティにハンドラーを追加します。ハンドラー名にはAssignedName:EventHandlerNameという形式を使用します。AssignedNameはextensionsプロパティでスマートモーション拡張機能に割り当てた名前、EventHandlerNameはハンドラーの名前です。

たとえば、拡張機能に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": "2024.3",
  "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}"
        }
      ]
    }
  }
}

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

画像フィルター

スマートモーション拡張機能によって追加される新しい画像フィルターはありません。

関連トピック

• APL拡張機能
• APL Entity Sensing拡張機能

最終更新日: 2025 年 12 月 04 日