Flutter 實作 DeepLink 完整指南 ⎮ Part 3: Flutter 開發

Yii Chen

Follow

Published in

Flutter Taipei

11 min readAug 30, 2024

--

不可忽視的 Deep Link 體驗

Flutter Development

如果你的專案是使用 Navigator 進行頁面的 Route 處理，而不是 Navigator 2 或者 GoRouter、auto_route 等等新式解決方案，在處理連結上會稍嫌麻煩。我們一起從最基礎的 Navigator 了解，實際上根據需求去管理導航就好，不必遵守某一套特定做法。提供了以下的範例跟大家分享

通常要捕捉設置的 Links，可以使用 app_links 套件協助我們。

app_links | Flutter package

Android App Links, Deep Links, iOs Universal Links and Custom URL schemes handler for Flutter (desktop included).

pub.dev

它有提供了幾個精簡的 API 方便開發，其中包含：

getInitialAppLink()
uriLinkStream
allUriLinkStream

getInitialAppLink()

取得 APP 初始連結，也就是被系統捕捉到但還沒處理的連結。必須存在的 API，因為當應用程式處於 cold state 也就是 terminated（終止）的時候使用者可能會點擊到連結，就需要這個 callback 的觸發，在開啟 APP 後能做一些反應。例如：跳轉到指定頁面、儲存資料。

final initialAppLinkUri = await _appLinks.getInitialAppLink();
if (initialAppLinkUri != null) {
  handleDeepLink(initialAppLinkUri);
}

uriLinkStream

當 APP 開啟時 (在背景和前景) 使用者點擊連結，uriLinkStream 會提供事件，包含 uri 資料，讓我們做後續處理。

_appLinks.uriLinkStream.listen(
  (uri) {
    handleDeepLink(uri);
  },
);

allUriLinkStream

APP 在任何的狀態下都能捕捉到連結，包含 getInitialAppLink() 和 uriLinkStream 的功用。在大部分情境下，可以只選擇使用它就好

_appLinks.allUriLinkStream.listen(
  (uri) {
    handleDeepLink(uri);
  },
);

根據場景需求，通常捕捉 Deep Link 為兩種實作方式：

getInitialAppLink() + uriLinkStream
allUriLinkStream

避免三種都使用，否則同一個連結事件，可能會造成重複處理的狀況

在監聽到 Deep Link 觸發之後，可以檢查 URI 是否為我們設置的格式，將內容提取出來使用。可能有多個連結，可以進行個別處理。

void handleDeepLink(Uri? uri) {
  if (uri == null) {
    return;
  }

final uriHost = uri.host;
  final uriPath = uri.path;

// if (uriOrigin.contains(StringConstants.deepLinkDomainVibzCool) &&
  // uriPath.contains(StringConstants.deepLinkPathUsers)) {
  if (uriHost == 'yii.cool') {
    final userName = uriPath.split('/').elementAtOrNull(1);
    if (userName == null) {
      return;
    }
  
    // Navigate to specific page
    ...
  }

if (uriHost == 'share.yii.cool') {
    if (uriPath.contains('/product')) {
      final productName = uriPath.split('/').elementAtOrNull(2);
      if (productName == null) {
        return;
      }
   
      // Navigate to specific page
      ...
    }
  }
}

Test and Check

實作完成後，我們會需要透過完整的測試來驗證所設定的 Deep Link，確保在各種情境下能夠順利運行，提供好的用戶體驗。

多情境測試

在多種目標平台與社交平台上測試，例如 Web、Social Platform(Instagram, Facebook)、Line、Slack 等，點擊連結來確認完整性。另外包含應用在背景和前景下的狀況，嚴謹地確認用戶能透過連結打開 APP 並跳轉到指定頁面。

2. DevTools Deeplinking Web Validator

在 Flutter 3.19，支援 Android 上的 Web 檢查，驗證資源檔案 assetlinks.json。開發人員可以開啟 DevTools，點擊進入 Deep Links 選項，然後匯入包含深層連結的 Flutter 專案，Validator 會告訴我們 Web 檔案是否配置正確。

Simulator Testing

當在電腦運行模擬器時，可以透過 Terminal 輸入命令驗證 Deep Link 是否有效。

Android 指令：

adb shell am start -a android.intent.action.VIEW \\
    -c android.intent.category.BROWSABLE \\
    -d "<https://vibz.cool/test555>"

# simple
adb shell am start "<https://vibz.cool/test555>"

# 跳過數位資產連結的驗證步驟，提早測試
adb shell am start -d "<https://www.airbnb.co.uk/rooms/12275365>" 
adb shell am start -d "vibz://vibz.cool/test7733"

取得應用驗證後的結果

adb shell pm get-app-links com.yiichen.test

iOS 指令：

// Web Link
xcrun simctl openurl booted <https://vibz.cool/test555>

// Custom Link
xcrun simctl openurl booted vibz://vibz.cool/test555

需確保 scheme、host、path，與 AndroidManifest.xml、Info.plist 中設置的都相同

Deep Linking Validator

存在於 Devtools Deep Links 分頁，幫助開發者了解哪些連結的配置不正確，透過狀態快速了解情況。

載入 Flutter 專案後，在列表可清楚知道哪些連結的設定是正確的，哪些是有問題的。可查看資訊包括：

連結的相關路徑
Scheme 格式
OS 作業系統
配置狀態，成功與否

Deep Link 設定錯誤通常會有幾種原因，URL 格式錯誤、Manifest 檔案設定錯誤、Digital Asset 沒有放置，或是內容不完整。

有關數位資源內容錯誤的情境可看下方截圖：

請大家善用 Deep Link Validator，所有的情況它都能幫我們快速的確認，在開發上是一個很棒的工具。不需要再手動花費多餘的時間囉～

目前僅支援驗證 Android 連結的配置，iOS 開發中 (May. 2024)

實際問題

Android Deep Link 啟動

Android 在 Deep Link 運作時，如果 APP 是完全關閉且未開啟的狀態，有可能會導致啟動時畫面卡住，無法正常運行。原因是，專案的 Routes 設置，Deep Link 需要有 / 路徑名稱的頁面，通常都是首頁，就跟網頁一樣。而我遇到的問題就是因為 APP Route 沒有 /，初始頁面為自定義名稱，導致 Deep Link 執行第一次啟動時沒有入口可以進入。

這個問題沒有很多 log meassge 可以參考，使用 print() 也沒用，較難 Debug。以下是發現的錯誤訊息：