ReactNative iOS端Branch.io延迟链接仅二次启动生效问题排查

问题现象 #

通过Branch.io生成的延迟链接安装iOS应用后，首次启动无法获取完整链接参数（返回No pre-install link matched提示），重启应用后才能正常拿到包含deeplinkURL、渠道/活动信息的正确数据；Android端无此问题。

核心原因分析 #

1. iOS链接匹配时机延迟：首次启动时，Branch SDK需要异步完成设备与链接的关联匹配（依赖IDFA、设备标识符等），若React Native的订阅逻辑触发过早，会错过匹配完成后的参数回调。
2. AppDelegate回调处理不全：未正确将Universal Links/URL Scheme的系统回调转发给Branch SDK，导致延迟链接的初始化数据未被捕获。
3. ATT权限影响：若App请求了App Tracking Transparency权限，首次启动时用户未授权会导致Branch无法获取IDFA完成设备匹配，重启后权限已授权，匹配流程正常执行。

排查与解决步骤 #

1. 完善AppDelegate中的Branch回调处理 #

确保以下关键方法正确实现，将系统回调转发给Branch SDK：

#import <Branch/Branch.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // 优先初始化Branch（放在RN初始化代码之前）
  Branch *branch = [Branch getInstance];
  [branch initSessionWithLaunchOptions:launchOptions isReferrable:YES];

  // 其他RN初始化代码...
  return YES;
}

// 处理Universal Links/Handoff
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
  return [[Branch getInstance] continueUserActivity:userActivity];
}

// 处理URL Scheme
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  return [[Branch getInstance] application:app openURL:url options:options];
}

2. 在React Native中主动获取链接参数 #

除了订阅Branch事件，在组件挂载时主动调用getLatestReferringParams，覆盖首次启动的延迟匹配场景：

import branch, { BranchSubscriptionEvent } from 'react-native-branch';

useEffect(() => {
  // 主动获取最新参数，处理首次启动的延迟匹配
  const fetchBranchParams = async () => {
    try {
      const params = await branch.getLatestReferringParams();
      // 验证是否为有效Branch链接
      if (params['+clicked_branch_link'] || params.deeplinkURL) {
        console.log('有效链接参数:', params);
        // 此处添加你的链接逻辑处理
      }
    } catch (error) {
      console.error('获取Branch参数失败:', error);
    }
  };

  fetchBranchParams();

  // 订阅Branch事件处理后续链接
  const unsubscribe = branch.subscribe((value: BranchSubscriptionEvent) => {
    console.log('订阅事件参数:', value);
    // 处理链接数据
  });

  return unsubscribe;
}, [...dependencyList]);

3. 处理ATT权限的影响 #

如果App使用了ATT权限，在用户授权后重新触发Branch参数获取：

import { requestTrackingPermissions } from 'react-native-tracking-transparency';

// 在合适时机请求权限
const requestATT = async () => {
  const { status } = await requestTrackingPermissions();
  if (status === 'granted') {
    // 权限授权后重新获取Branch参数
    const params = await branch.getLatestReferringParams();
    // 处理参数逻辑
  }
};

4. 验证Branch配置正确性 #

• 确认Xcode的Info.plist中已添加Branch的branch_key配置（对应Branch Dashboard的iOS Key）
• 检查Associated Domains是否配置了applinks:{你的Branch域名}（如applinks:yourapp.app.link）
• 确保Branch Dashboard中的iOS Bundle ID与App的Bundle ID完全匹配

为什么重启后能正常获取数据？ #

首次启动时，Branch SDK在后台异步完成设备与延迟链接的关联匹配，这个过程可能因网络、权限等因素未在React Native订阅触发前完成；重启应用时，匹配已完成，Branch会直接读取缓存的链接参数，因此能正常返回数据。

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