前景應用程式叫用

應用程式動作可讓使用者在與 Google 助理交談時,直接說出「Ok Google,幫我在範例應用程式上叫車」之類的指令。透過前景應用程式叫用,您可以進一步提升使用者開啟應用程式時的體驗。

前景應用程式叫用可讓系統比對內建意圖 (BII),而不需要在裝置前景執行時提及應用程式名稱。

舉例來說,假設使用者在前景開啟代僱駕駛服務應用程式,然後向 Google 助理說出「幫我叫車去山景城」。您的應用程式會使用此輸入內容,將目的地欄位設為山景城。之後,當使用者說出或輸入「幫我叫車,從 SFO 出發」時,您的應用程式就能設定上車地點,同時保留應用程式的狀態。

限制

前景應用程式叫用僅適用於下列 BII:

如要針對特定 BII 的前景應用程式叫用取得語言支援和查詢範例,請參閱「內建意圖參考資料」。

支援前景應用程式叫用

新增前景應用程式叫用支援,必須根據所需的前景活動新增執行要求行為。當該活動於前景且叫用應用程式動作時,Google 助理會傳遞深層連結意圖與該活動的額外標記,讓應用程式可更新其狀態。

如要實作 BII 的前景應用程式叫用,請執行下列步驟:

  1. 在您的 shortcuts.xml 檔案中,將 <intent> 標記新增至您要支援前景應用程式叫用的 BII <capability>
  2. <intent> 標記中加入 <extra> 標記。
  3. <extra> 標記中,將 android:key 設為 "requiredForegroundActivity",然後將 android:value 設為需要在前景的活動。指定沒有任何類別縮寫的活動,方法是使用應用程式套件名稱,後面加上正斜線 (/),然後加上活動名稱:APP_PACKAGE_NAME/ACTIVITY_NAME
  4. 在您針對 "requiredForegroundActivity" 指定的前景活動中,實作 onNewIntent() 方法以處理有 SINGLE_TOP 標記組合的深層連結意圖。當指定活動於前景時,Google 助理會傳遞此標記的深層連結意圖做為標記。
  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>

使用者權限

在裝置設定中,使用者必須啟用「使用畫面中的文字」功能,前景應用程式叫用才能使用。

如要讓前景應用程式叫用順利運作,使用者必須啟用「Use text from screen」(使用畫面中的文字) 裝置設定。此設定的位置和確切名稱可能會因原始設備製造商 (OEM) 或裝置製造商而異。舉例來說,裝置設定在使用者裝置上的名稱可能會改為使用螢幕結構定義

如要在 Pixel 手機上前往這項 Android 設定,請先依序前往「設定」>「應用程式和通知」>「預設應用程式」>「輔助應用程式」,然後在「輔助和語音輸入」畫面中啟用「使用畫面中的文字」

測試叫用

如要試用前景應用程式叫用功能,請按照下列步驟操作:

  1. 按照「使用者權限」一節中的操作說明,啟用「Use text from screen」(使用畫面中的文字) 裝置設定。
  2. 開啟應用程式,前往您列為必要前景活動的活動。
  3. 按住主畫面按鈕,即可在目前應用程式上以重疊方式開啟 Google 助理。請提供與已實作的 BII 相對應的查詢,無須提及應用程式名稱本身。成功時,應用程式會根據查詢內容自行更新,同時保留狀態,不會重新啟動活動。

處理路由器活動

部分應用程式會使用單一隔離路由器活動來處理所有外部深層連結。然後路由器活動會啟動適當的商業邏輯活動 (檢查和驗證後),並將商業邏輯活動傳回至前景。

觸發深層連結可能會導致路由器活動新增至前景活動上方的工作堆疊頂端。對於使用路由器活動的應用程式,您必須確保路由器活動會將 Google 助理傳送的意圖傳送至目前的前景活動執行個體。達成此要求的方式會因路由器活動開始時間而異。

如果您的路由器會開始進行與業務邏輯活動相同的工作堆疊,請使用位元或 SINGLE_TOPCLEAR_TOPNEW_TASK 來轉送意圖:

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 標記,將意圖轉送至商業邏輯活動。