Plugin Runtime延迟初始化在iOS端失效问题求助

问题背景 #

已按照官方指南配置Defer Initialization for Plugin Runtime，Android端运行正常，但iOS端存在问题：冷启动App通过Deep Link触发时，branch.subscribe({})未被调用，无法获取URL中的数据。

已完成的配置：

• 添加branch.json文件到项目，并确认其存在于Copy Bundle Resources phase环节

复现步骤 #

• 通过Deep Link URL触发深度链接流程
• 冷启动App
• branch.subscribe({})未执行，无法获取链接数据

预期行为 #

冷启动时能通过branch.subscribe({})接收深度链接数据

环境信息 #

• SDK版本：react-native-branch@6.0.0、react-native@0.72.3
• 操作系统：iOS 17

解决方案 #

1. 确认branch.json配置正确性 #

确保branch.json中明确开启延迟初始化，并配置正确的Branch密钥：

{
  "branch_key": "YOUR_LIVE_BRANCH_KEY",
  "branch_test_key": "YOUR_TEST_BRANCH_KEY",
  "deferInitialization": true
}

2. 检查iOS原生端初始化逻辑 #

• Objective-C（AppDelegate.mm）：确保没有在RN初始化前调用Branch的初始化方法，删除或注释掉类似以下代码：

  // 不要提前调用这个方法，让RN侧控制初始化
  // [Branch initSessionWithLaunchOptions:launchOptions isReferrable:YES];
  

• Swift（AppDelegate.swift）：同理，确保没有过早调用：

  // 不要提前调用这个方法
  // Branch.initSession(launchOptions: launchOptions, isReferrable: true)
  

3. 正确调用branch.subscribe和手动初始化 #

在RN根组件的挂载生命周期中，先订阅再手动触发Branch初始化（延迟模式下必须手动调用initSession）：

import branch from 'react-native-branch';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // 先订阅深度链接回调
    const unsubscribe = branch.subscribe(({ error, params }) => {
      if (error) {
        console.error('Branch订阅错误:', error);
        return;
      }
      if (params && !params['+non_branch_link']) {
        // 处理深度链接数据
        console.log('深度链接参数:', params);
      }
    });

    // 手动初始化Branch会话
    branch.initSession();

    // 组件卸载时取消订阅
    return unsubscribe;
  }, []);

  // ... 其他组件代码
}

export default App;

4. iOS 17权限与Universal Links适配 #

• 添加App Tracking Transparency权限：在Info.plist中新增键值对：

  <key>NSUserTrackingUsageDescription</key>
  <string>需要此权限以处理深度链接和个性化内容</string>
  

• 验证Universal Links配置：确认Apple Developer后台的App ID已启用Associated Domains，且apple-app-site-association文件配置正确。

5. 清理缓存并重新构建 #

• 清理Xcode缓存：使用Cmd+Shift+K清理项目，再删除Derived Data（Xcode -> Settings -> Locations -> Derived Data路径）
• 卸载设备上的App，重新执行pod install并构建运行

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