在 Flutter 應用程式中建立 Dynamic Links

您可以使用 Firebase Dynamic Links Builder API 建立短或長 Dynamic Links。這個 API 接受長 Dynamic Link 或包含 Dynamic Link 參數的物件，並傳回類似下列範例的網址：

https://example.com/link/WXYZ
https://example.page.link/WXYZ

設定 Firebase 和 Dynamic Links SDK

您必須先加入 Firebase SDK，才能在 Android 應用程式中建立 Dynamic Links。如果應用程式已設定接收 Dynamic Links，代表您已完成這些步驟，可以略過本節。

1. 如果尚未安裝及初始化 Flutter 適用的 Firebase SDK，請先完成這項操作。

2. 在 Flutter 專案的根目錄中，執行下列指令來安裝 Dynamic Links 外掛程式：

   flutter pub add firebase_dynamic_links
   

3. 如果您正在建構 Android 應用程式，請開啟 Firebase 控制台的「Project settings」(專案設定) 頁面，確認您已指定 SHA-1 簽署金鑰。如果您使用應用程式連結，也請指定 SHA-256 金鑰。

4. 在 Firebase 控制台中，開啟「Dynamic Links」部分。

   1. 如果尚未為 Dynamic Links 設定網域，請按一下「Get Started」(開始使用) 按鈕，然後按照提示操作。

      如果您已有 Dynamic Links 網域，請記下該網域。透過程式建立 Dynamic Links 時，必須提供 Dynamic Links 網域。

   2. 建議做法：在「更多」(⋮) 選單中，指定深層連結和備用連結中允許的網址模式。這樣一來，未經授權的使用者就無法建立 Dynamic Links，從您的網域重新導向至您無法控管的網站。

      請參閱「允許特定網址模式」。

使用參數建立 Dynamic Link

如要建立 Dynamic Link，請建立新的 DynamicLinkParameters 物件，並將其傳遞至 buildLink() 或 buildShortLink()。

以下範例說明如何建立 https://www.example.com/ 的長 Dynamic Link，在 Android 上使用 com.example.app.android 開啟，在 iOS 上使用 com.example.app.ios 應用程式開啟：

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(packageName: "com.example.app.android"),
  iosParameters: const IOSParameters(bundleId: "com.example.app.ios"),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildLink(dynamicLinkParams);

如要建立短 Dynamic Link，請將 DynamicLinkParameters 物件傳遞至 buildShortLink()。建構短連結需要網路呼叫。 例如：

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(packageName: "com.example.app.android"),
  iosParameters: const IOSParameters(bundleId: "com.example.app.ios"),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams);

根據預設，系統產生的短 Dynamic Links 後置字串只有幾個字元。雖然這會讓連結更精簡，但也可能讓他人猜出有效的短連結。通常，如果有人這麼做，並不會造成任何傷害，因為連結會導向公開資訊。

不過，如果短連結會導向使用者專屬資訊，建議您建立較長的連結，並加上 17 個字元的尾碼，這樣一來，他人就不太可能猜出有效的 Dynamic Link。如要這麼做，請將 ShortDynamicLinkType.unguessable 傳遞至 buildShortLink() 方法：

final unguessableDynamicLink = await FirebaseDynamicLinks.instance.buildShortLink(
    dynamicLinkParams,
    shortLinkType: ShortDynamicLinkType.unguessable,
);

Dynamic Link 參數

您可以使用 Dynamic Link Builder API，以任何支援的參數建立 Dynamic Links。請參閱 API 參考資料。

以下範例會建立 Dynamic Link，並設定幾個常見參數：

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(
    packageName: "com.example.app.android",
    minimumVersion: 30,
  ),
  iosParameters: const IOSParameters(
    bundleId: "com.example.app.ios",
    appStoreId: "123456789",
    minimumVersion: "1.0.1",
  ),
  googleAnalyticsParameters: const GoogleAnalyticsParameters(
    source: "twitter",
    medium: "social",
    campaign: "example-promo",
  ),
  socialMetaTagParameters: SocialMetaTagParameters(
    title: "Example of a Dynamic Link",
    imageUrl: Uri.parse("https://example.com/image.png"),
  ),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams);

您可以透過下列方法設定 Dynamic Link 參數：

DynamicLink 參數
setLink	應用程式會開啟的連結。指定應用程式可處理的網址，通常是應用程式的內容或酬載，用於啟動應用程式專屬邏輯 (例如向使用者提供優待券或顯示歡迎畫面)。這個連結必須是格式正確的網址、經過適當的網址編碼、使用 HTTP 或 HTTPS，且不得為其他 Dynamic Link。
setDomainUriPrefix	Dynamic Link 網址前置字串，可在 Firebase 控制台找到。Dynamic Link 網域如下所示： https://example.com/link https://example.page.link

AndroidParameters
setFallbackUrl	未安裝應用程式時要開啟的連結。指定這項屬性後，如果使用者未安裝應用程式，系統就不會從 Play 商店安裝應用程式，而是執行其他動作，例如開啟行動版網站內容，或顯示應用程式的宣傳頁面。
setMinimumVersion	可開啟連結的應用程式最低版本 versionCode。如果安裝的是舊版應用程式，系統會將使用者導向 Play 商店，以便升級應用程式。

IosParameters
setAppStoreId	應用程式的 App Store ID，用於在未安裝應用程式時將使用者導向應用程式商店
setFallbackUrl	未安裝應用程式時要開啟的連結。指定這項參數後，如果使用者未安裝應用程式，系統就不會從應用程式商店安裝應用程式，而是執行其他動作，例如開啟行動版網站內容，或顯示應用程式的宣傳頁面。
setCustomScheme	應用程式的自訂網址配置 (如果定義為應用程式軟體包 ID 以外的值)
setIpadFallbackUrl	未安裝應用程式時，在 iPad 上開啟的連結。指定這項參數後，如果使用者未安裝應用程式，系統就不會從應用程式商店安裝應用程式，而是執行其他動作，例如開啟網頁版內容，或顯示應用程式的宣傳頁面。
setIpadBundleId	在 iPad 上開啟連結時，要使用的 iOS 應用程式軟體包 ID。您必須在 Firebase 控制台的「Overview」(總覽) 頁面中，將應用程式連結至專案。
setMinimumVersion	可開啟連結的應用程式最低版本號碼。應用程式開啟時，系統會將這個標記傳遞給應用程式，應用程式必須決定如何處理。

NavigationInfoParameters
setForcedRedirectEnabled	如果設為「1」，開啟 Dynamic Link 時會略過應用程式預覽頁面，改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可更可靠地將使用者導向最合適的目的地，當他們在應用程式中開啟動態連結時；不過，如果您預期動態連結只會在可以可靠開啟動態連結的應用程式中開啟，而不需要這個頁面，您可以使用這個參數停用它。這個參數只會影響 Dynamic Link 在 iOS 上的行為。

SocialMetaTagParameters
setTitle	在社群貼文中分享 Dynamic Link 時使用的標題。
setDescription	在社群貼文中分享 Dynamic Link 時使用的說明。
setImageUrl	與這個連結相關的圖片網址。圖片大小至少應為 300x200 像素，且不得超過 300 KB。

GoogleAnalyticsParameters
setSource setMedium setCampaign setTerm setContent	Google Play 數據分析參數。這些參數 (`utm_source`、`utm_medium`、`utm_campaign`、`utm_term`、`utm_content`) 會傳遞至 Play 商店，並附加至連結酬載。

ItunesConnectAnalyticsParameters
setProviderToken setAffiliateToken setCampaignToken	iTunes Connect 數據分析參數。這些參數 (`pt`、`at`、`ct`) 會傳遞至應用程式商店。