Firebase Dynamic Links在iOS用户通过App Store安装应用时丢失UTM参数问题咨询

该问题是iOS端特有问题，和App Store本身不提供安装来源传递通道有关，UTM参数并未真的在跳转过程中丢失，而是没有通过正确的逻辑从Firebase的延迟深度链接匹配结果中获取，可按照以下步骤排查修复：

1. 基础配置校验 #

• 确认创建动态链接时，UTM参数直接附加在Firebase动态链接本身的查询参数中，而非仅附加在跳转的目标页URL中，Firebase会自动识别utm_source/utm_medium/utm_campaign等标准UTM字段存入动态链接的 payload
• 检查Xcode项目Info.plist中已正确添加FirebaseDynamicLinksCustomDomains配置项，写入你使用的动态链接域名（自定义域名必须配置，默认的page.link域名可省略）
• 确认App Store Connect中关联域名（Associated Domains）配置正确，applinks:你的动态链接域名无拼写错误

2. 代码逻辑调整 #

iOS新安装场景的参数不会走已安装App的通用链接回调，必须在首次启动时主动触发Firebase的参数匹配逻辑：

• 在application:didFinishLaunchingWithOptions:回调中主动调用Dynamic Links的匹配接口，代码示例：

// Swift 示例
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // 初始化Firebase之后添加以下逻辑
    if let userActivity = launchOptions?[.userActivity] as? NSUserActivity,
       let url = userActivity.webpageURL {
        DynamicLinks.dynamicLinks().handleUniversalLink(url) { [weak self] dynamicLink, error in
            guard let dynamicLink = dynamicLink, let linkUrl = dynamicLink.url else { return }
            // 解析UTM参数
            let queryItems = URLComponents(url: linkUrl, resolvingAgainstBaseURL: false)?.queryItems
            let utmSource = queryItems?.first { $0.name == "utm_source" }?.value
            let utmMedium = queryItems?.first { $0.name == "utm_medium" }?.value
            let utmCampaign = queryItems?.first { $0.name == "utm_campaign" }?.value
            // 手动将UTM参数上报到Google Analytics
            if let utmSource = utmSource, let utmMedium = utmMedium, let utmCampaign = utmCampaign {
                Analytics.setCampaignParametersFrom(
                    ["utm_source": utmSource,
                     "utm_medium": utmMedium,
                     "utm_campaign": utmCampaign]
                )
            }
        }
    }
    return true
}

• 确认Firebase控制台动态链接设置中，「延迟深度链接」开关处于启用状态，该选项默认开启，若手动关闭过需要重新打开

3. 测试&适配优化 #

• 测试时必须完全模拟用户场景：先卸载App → 点击动态链接跳转到App Store页面 → 不要跳转回来，直接通过Xcode/TestFlight安装App并首次启动，才能触发延迟匹配逻辑，直接本地安装App不会触发该流程
• iOS 15+版本受ATT权限影响，若用户拒绝追踪权限，Firebase的IP+UA匹配精度会下降，可开启Firebase动态链接的短链 fallback 配置提升匹配率
• 兜底方案：可将UTM参数同时编码到动态链接的ofl参数（App Store跳转的 fallback URL）中，双份存储避免极端场景丢失

内容的提问来源于stack exchange，提问作者nanz