フォアグラウンド アプリの呼び出し

App Actions を使用すると、ユーザーは Google アシスタントに話しかけて、「OK Google, Example App で配車を注文して」などと話しかけると、アプリの特定のデスティネーションに直接ジャンプできます。フォアグラウンド アプリ呼び出しを使用すると、ユーザーがすでにアプリを開いている場合のエクスペリエンスをさらに向上させることができます。

フォアグラウンド アプリ呼び出しを使用すると、特定のアクティビティがデバイスのフォアグラウンドにある場合に、アプリ名を指定しなくても組み込みインテント(BII)を照合できます。

たとえば、ユーザーがライドシェア アプリをフォアグラウンドで実行し、Google アシスタントに「マウンテン ビューへの乗車を予約して」と話しかけるか入力したとします。アプリは、この入力を使用して、目的地フィールドをマウンテン ビューに設定します。ユーザーが「SFO から配車を依頼して」と話しかけるか入力すると、アプリはアプリの状態を維持しながら乗車場所を設定できます。

制限事項

フォアグラウンド アプリ呼び出しは、次の BII でのみ使用できます。

ロケールのサポートと、特定の BII のフォアグラウンド アプリ呼び出しに関連するサンプルクエリについては、組み込みインテント リファレンスをご覧ください。

フォアグラウンド アプリ呼び出しをサポートする

フォアグラウンド アプリ呼び出しに対するサポートを追加するには、目的のフォアグラウンド アクティビティに基づいて、フルフィルメントの動作を追加します。目的のアクティビティがフォアグラウンドで実行されているときに App Action が呼び出されると、アシスタントはそのアクティビティにフラグを追加してディープリンク インテントを渡し、アプリがその状態を更新できるようにします。

BII のフォアグラウンド アプリ呼び出しを実装する手順は次のとおりです。

  1. shortcuts.xml ファイルで、フォアグラウンド アプリ呼び出しをサポートする BII <capability><intent> タグを追加します。
  2. <intent> タグ内に <extra> タグを追加します。
  3. <extra> タグで、android:key"requiredForegroundActivity" に設定し、android:value を、フォアグラウンドで実行する必要があるアクティビティに設定します。APP_PACKAGE_NAME/ACTIVITY_NAME のように、アプリのパッケージ名、スラッシュ(/)、アクティビティ名を続けて、アクティビティを指定します(クラスの省略形は使用しません)。
  4. "requiredForegroundActivity" に指定したフォアグラウンド アクティビティで、SINGLE_TOP フラグが設定されたディープリンク インテントを処理する onNewIntent() メソッドを実装します。指定したアクティビティがフォアグラウンドで実行されているとき、アシスタントは、このフラグを含むディープリンク インテントをフルフィルメントとして渡します。
  5. onNewIntent() の呼び出しをフォアグラウンド アクティビティに対する更新として扱い、ディープリンクから抽出されたパラメータを使用して、そのアクティビティ内で状態を管理します。

アプリでルーター アクティビティを使用して、すべての外部ディープリンクが単一のゲートキーピング ルーター アクティビティをトリガーできるようにするには、ルーター アクティビティを処理するをご覧ください。

サンプル shortcuts.xml ファイルの次のスニペットは、requiredForegroundActivity 属性を追加する方法を示しています。

  <capability name="actions.intent.CREATE_TAXI_RESERVATION">
      <!-- Trigger with foreground app invocation if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
          <extra
              android:key="requiredForegroundActivity"
              android:value="com.example.app/com.example.app.MainActivity" />
      </intent>
      <!-- This won't trigger if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
      </intent>
  </capability>

ユーザー権限

フォアグラウンド アプリ呼び出しが機能するには、ユーザーがデバイス設定で [画面のテキストを使用] を有効にする必要があります。

フォアグラウンド アプリの呼び出しがユーザーに対して機能するためには、ユーザーの [画面のテキストを使用] デバイス設定が有効になっている必要があります。この設定の場所と正確な名前は、OEM とデバイス メーカーによって異なります。たとえば、ユーザーのデバイスでは、このデバイス設定が [画面のコンテキストを使用] と呼ばれている場合があります。

Google Pixel でこの Android の設定にアクセスするには、まず [設定] > [アプリと通知] > [デフォルト アプリ] > [アシストアプリ] に移動し、[アシストと音声入力] 画面で [画面のテキストを使用] を有効にします。

呼び出しをテストする

フォアグラウンド アプリの呼び出しを試す手順は次のとおりです。

  1. ユーザー権限セクションの手順に沿って、デバイス設定で [画面のテキストを使用] を有効にします。
  2. アプリを開き、必要なフォアグラウンド アクティビティとしてリストしたアクティビティにアクセスします。
  3. ホームボタンを長押しすると、アシスタントを現在のアプリのオーバーレイとして開きます。アプリ名自体を指定せずに、実装した BII に対応するクエリを提供します。問題がなければ、アプリは状態を維持したままで、アクティビティを再起動することなく、クエリに基づいて自動的に更新されます。

ルーター アクティビティを処理する

一部のアプリは、単一のゲートキーピング ルーター アクティビティを使用して、すべての外部ディープリンクを処理します。ルーター アクティビティは、適切なビジネス ロジック アクティビティを(なんらかのチェックと検証を行った後で)開始し、ビジネス ロジック アクティビティをフォアグラウンドに戻します。

ディープリンクをトリガーすると、ルーター アクティビティがタスクスタックの一番上(フォアグラウンド アクティビティより上)に追加されることがあります。ルーター アクティビティを使用するアプリでは、ルーター アクティビティが、Google アシスタントから送信されたインテントを、現在のフォアグラウンド アクティビティ インスタンスに配信する必要があります。この要件を満たす方法は、ルーター アクティビティが開始される場所によって異なります。

ルーターがビジネス ロジック アクティビティと同じタスクスタックで開始される場合は、SINGLE_TOPCLEAR_TOPNEW_TASK のビット演算 OR を使用してインテントを転送します。

Kotlin

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Java

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK

ルーターがビジネス ロジック アクティビティとは別のタスクスタックで起動する場合は、代わりに SINGLE_TOP フラグが設定されたインテントをビジネス ロジック アクティビティに転送します。