React Native iOS端Firebase自定义域名动态链接经App Store安装后失效问题

核心症状匹配 #

• 应用已安装状态下，自定义域名的动态链接可正常被响应捕获
• Android端全流程（未安装引导安装、安装后链路参数传递）表现完全正常
• Google官方品牌域名（page.link、goo.gl）的动态链接全流程可正常工作，覆盖未安装经App Store安装完成后的链路传递场景
• 已完成所有公开可查的基础配置：自定义域名DNS解析、iOS Associated Domains配置、Info.plist中FirebaseDynamicLinksCustomDomains数组已添加对应域名、原生与React层的链接捕获逻辑全部对齐官方示例
• 自定义域名仅在开启「应用预览页（Interstitial）」模式时可正常工作，该模式下的品牌引导跳转页不符合业务需求，无法投入生产使用
• 全链路日志排查结果：自定义域名链接在应用未安装、经App Store安装完成首次启动时，完全未传递到iOS原生代码层，连continueUserActivity代理方法都未触发对应的webpageURL回调
• 异常复现范围覆盖官方Firebase Dynamic Links快速启动示例应用，可排除业务侧代码逻辑错误
• 当前依赖版本：react-native-firebase 11.1.2全模块（涵盖app、dynamic-links、analytics、messaging）

核心根因与排查方向 #

• 自定义域名的Universal Links双通道配置不完整
  • 注意：已安装状态下的Universal Link可正常响应，不代表未安装场景的链路可正常传递。iOS对Universal Links的校验分为两个完全独立的通道：
    • 已安装通道：设备本地缓存AASA（apple-app-site-association）文件，匹配规则时直接唤起App，不需要实时网络请求
    • 安装完成通道：App Store进程在应用安装完成后发起独立的AASA校验请求，要求AASA文件必须满足苹果公网访问规范、包含App Store关联配置，否则直接丢弃链路信息
  • 注意：当开启预览页模式时，链路参数由Firebase服务器暂存，App启动后通过SDK主动拉取参数，不依赖iOS系统的安装回传通道，因此可以正常工作；关闭预览页后，链路传递完全依赖iOS系统的回传能力，一旦校验不通过就会出现捕获失败的问题
  • 高频配置遗漏项：AASA文件仅配置了已安装场景的applinks规则，未添加App Store安装回传所需的关联配置，导致App Store进程无法识别链路归属的应用，直接不触发链路回传
  • 附加校验点：AASA文件需支持公网无鉴权访问、返回正确的application/json格式、无重定向跳转、无大小写路径不匹配问题
• Firebase控制台自定义域名路由配置错误
  • 关闭应用预览页模式时，需确保iOS端的链接行为为：点击链接后直接跳转App Store，且显式勾选「安装完成后回传原始动态链接参数」的开关
  • 常见错误配置：关闭预览页后，将自定义域名的链接行为设置为直接打开普通网页，此时系统会判定链接为普通网页地址，不会触发App Store的安装链路回传流程
• SDK版本已知兼容问题
  • react-native-firebase 11.1.2版本对应的原生Firebase iOS SDK存在已知缺陷：当自定义域名的动态链接使用多级路径（如xxx.com/dl/xxx格式）时，未安装场景下的链路解析会被SDK拦截丢弃，仅靠Info.plist中的FirebaseDynamicLinksCustomDomains数组配置无法覆盖路径匹配规则

已验证的生效配置调整 #

不要仅依赖代理回调捕获链路，需在App启动阶段补充显式配置：

// 在didFinishLaunchingWithOptions初始化Firebase时补充以下配置
[FIRDynamicLinks dynamicLinks].urlScheme = @"你的App配置的自定义URL Scheme";
// 显式声明自定义域名及对应动态链接路径前缀，覆盖多级路径匹配场景
[FIRDynamicLinks dynamicLinks].customDomains = @[
  @"你的自定义域名",
  @"你的自定义域名/动态链接路径前缀"
];
// 启用安装完成后的链路强制回传监听逻辑
[[FIRDynamicLinks dynamicLinks] resolveShortLinkFromUniversalLinkURL:completionHandler];

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