啟用及自訂跨裝置接力功能

「繼續」功能導入了新的方法和類別，可讓您指出對該功能的支援，並提供傳遞所需的必要資料。這樣一來，您就能在接收裝置上正確恢復使用者體驗。

支援

您必須為每項活動分別導入「繼續」支援功能 (預設為關閉)。如要啟用這項功能，請呼叫 setHandoffEnabled，將目前活動標示為可接力。呼叫 setHandoffEnabled(true, null) 後，活動隨時可能接力，因此請務必在活動準備好接力時再呼叫。

您可以使用 isHandoffEnabled 檢查活動是否已啟用「繼續」功能。如果活動已啟用接力功能，也必須實作 onHandoffActivityDataRequested，確保傳回非空值的 HandoffActivityData，因為系統不會實作預設行為。

class MyHandoffActivity : Activity() {

    ...

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Do stuff
    ...
    // Enable handoff
    setHandoffEnabled(true, null)
  }

  // Override and implement onHandoffActivityDataRequested
  override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {
    // Create and return handoff data
  }
}

您可以使用任何相關額外項目和備用 URI 設定 HandoffActivityData 物件，告知「繼續」如何執行交接至接收裝置。

系統在以下兩種情況下需要這項資料：

  • Activity 進入背景，必須儲存相關資料。
  • 活動位於前景，且已要求接力。您可以查看交接要求的狀態。

檢查狀態

HandoffActivityDataRequestInfo 類別提供目前要求交接活動的相關資訊。使用 isActiveRequest 判斷要求目前是否有效。如果方法傳回

  • true，表示目前活動位於前景，且使用者已要求在其他裝置上繼續，但如果
  • false：活動已停止並在背景執行，但使用者日後可能會要求接力。

在傳送裝置上，如要顯示 UI 向使用者指出接力已發生或正在進行中，可以檢查 isActiveRequest 是否有進行中的要求。不過，請勿將這段程式碼做為 onHandoffActivityDataRequested 的一部分同步執行。請改為將任何程式碼排入佇列，以非同步方式執行，以免封鎖或延遲交接。

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  // Create and return handoff data
}

建立接力資料

為確保使用「繼續」功能接續執行時，所有相關和必要資料都能傳遞，您必須在 HandoffActivityData 物件中加入資料。

HandoffActivityData 類別代表與活動相關聯的接力資料。HandoffActivityData 會告知「繼續先前的活動」功能，如何在接收裝置上處理及重新建立活動。交接資料包括：

  • 元件名稱 (必要)：在接收裝置上啟動的對應活動 ComponentName，以便在接力後繼續使用者歷程。在大多數情況下，為了精確複製活動，這會是建立 HandoffActivityData 的相同活動的元件名稱。
  • Extras (選用)：您可以指定要納入活動啟動 Intent 的額外項目。這是一個 PersistableBundle，可用來為元件提供額外資訊。額外內容必須小於 50 KB。

如要建立 HandoffActivityData 物件，請使用建構工具類別 HandoffActivityData.Builder。傳遞應接收接續互通的活動 ComponentName (例如目前 Activity 的 this.getComponentName，或明確的 ComponentName(this, TargetActivity::class.java))，藉此建構新的建構工具。接著，使用 setExtras 方法選擇性指定額外項目。最後，呼叫 build 建立 HandoffActivityData 物件。

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  val extras: PersistableBundle = PersistableBundle()
  // Put relevant and necessary values into extras (e.g. scroll position)
  extras.putString("data_id", getDataId())
  extras.putInt("scroll_position", getScrollPosition())

  // Create and return handoff data
  return HandoffActivityData.Builder(getComponentName()) // Designate handoff to the same activity
    .setExtras(extras)
    .build()
}

設定網頁備用選項

如果無法在接收裝置上啟動指定活動，您也可以使用 setFallbackUri 設定備用網址，在裝置上以使用者的預設瀏覽器開啟。

如要允許「繼續」建議顯示在未安裝應用程式的接收裝置上，請在呼叫 setHandoffEnabled 時，傳遞 HandoffActivityParams 例項，並將 setAllowHandoffWithoutPackageInstalled 設為 true：

setHandoffEnabled(
  true,
  HandoffActivityParams.Builder()
    .setAllowHandoffWithoutPackageInstalled(true)
    .build()
)

接著在 HandoffActivityData 中加入備用網址：

val fallbackWebLink: Uri = Uri.parse("https://myapp.com/fallback?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.Builder(getComponentName())
  .setExtras(extras)
  .setFallbackUri(fallbackWebLink)
  .build()

直接導入至網站

或者，如要實作直接移轉至網頁，請將 HandoffActivityParams 與 setAllowHandoffWithoutPackageInstalled(true) 傳遞至 setHandoffEnabled，並使用 HandoffActivityData.createWebHandoff 方法產生 HandoffActivityData：

val webHandoffLink: Uri = Uri.parse("https://myapp.com/handoff?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.createWebHandoff(webHandoffLink)

接收及處理轉接意圖

在接收裝置上，應用程式必須處理接力作業，並從傳送裝置重新建立使用者的體驗。具體來說，在 onHandoffActivityDataRequested 傳回的 HandoffActivityData 中指定的活動中，您需要處理意圖，並擷取包含如何適當重建活動資訊的額外資訊。

如果您指定將接續互通作業交給同一個活動，可以在活動的 onCreate 方法中接收意圖，以便擷取資料並為使用者預先填入適當內容。

class MyHandoffActivity : Activity() {

    ...

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Do stuff
    ...

    // Get the launch intent and retrieve extras
    val intent: Intent = getIntent()
    if (intent != null && intent.hasExtra("data_id")) {
      val dataID: String = intent.getStringExtra("data_id")
      // Retrieve the data that corresponds to the data ID
      ...
      // Populate activity UI with relevant data
      ...

      if (intent.hasExtra("scroll_position")) {
        val scrollPosition: Int = intent.getIntExtra("scroll_position", 0)
        // Move the page to the scroll position
        ...
      }
    }
  }
}