React Native中Locality推送的Branch.IO Deeplink参数提取与页面跳转问题

我之前也碰到过类似的Branch链接在推送通知里参数解析失效的情况，咱们一步步来拆解解决：

一、先排查Locality推送负载的链接格式问题 #

首先要确认推送负载里的Branch链接没有被意外转义或截断：

• 检查推送payload中的深度链接是否和Branch控制台生成的原始链接完全一致，避免推送服务自动对URL中的&、=等符号做转义处理（比如转成&），这会导致Branch SDK无法正确解析参数。
• 确保Locality推送是把Branch链接放在了支持深度链接的字段中（比如部分推送平台要求放在deeplink或url专属字段，而不是普通的文本字段）。
• 先用Branch官方的测试工具验证链接本身的有效性，确认链接能正常解析出参数，再放到推送里测试。

二、React Native中提取Branch参数的正确姿势 #

不要手动拆分URL解析参数！一定要用Branch官方的React Native SDK来处理，因为Branch链接可能是短链或者经过平台处理的，手动解析很容易丢参数：

1. 确保SDK正确集成 #

先确认你已经安装并配置好react-native-branch（包括iOS的Associated Domains、Android的Manifest配置）。

2. 处理不同启动场景的参数获取 #

App的启动状态分为冷启动、后台唤醒、前台运行，要覆盖所有场景：

import branch from 'react-native-branch';
import { useNavigation } from '@react-navigation/native';

// 在App的根组件中初始化并监听
const App = () => {
  const navigation = useNavigation();

  useEffect(() => {
    // 处理冷启动/后台唤醒时的链接参数
    const initBranchSession = async () => {
      const { error, params } = await branch.initSession();
      if (!error && params) {
        console.log('启动时拿到的Branch参数:', params);
        navigateToTargetScreen(params, navigation);
      }
    };

    // 监听前台运行时收到的链接
    const unsubscribe = branch.subscribe(({ error, params }) => {
      if (!error && params) {
        console.log('前台收到的Branch参数:', params);
        navigateToTargetScreen(params, navigation);
      }
    });

    initBranchSession();
    return () => unsubscribe();
  }, [navigation]);

  // ... 你的导航组件代码
};

3. 推送点击后的参数提取 #

如果Locality推送的回调里能拿到链接URL，也可以主动用Branch SDK解析：

// 假设这是Locality推送点击的回调函数
const handleNotificationTap = async (deeplinkUrl) => {
  try {
    // 用Branch SDK解析链接，而非手动拆分
    const params = await branch.getLatestReferringParams();
    // 或者如果是新链接，也可以用branch.openURL(deeplinkUrl)触发解析
    // await branch.openURL(deeplinkUrl);
    console.log('推送链接解析出的参数:', params);
    // 跳转页面
    navigateToTargetScreen(params, navigation);
  } catch (err) {
    console.error('解析Branch参数失败:', err);
  }
};

三、根据参数实现页面跳转（以React Navigation为例） #

写一个通用的跳转函数，根据Branch参数里的自定义字段（比如你在Branch控制台设置的target_screen、product_id等）来跳转：

const navigateToTargetScreen = (params, navigation) => {
  // 假设你在Branch链接里设置了`screen`参数指定目标页面
  switch (params.screen) {
    case 'ProductDetail':
      // 携带商品ID参数跳转
      navigation.navigate('ProductDetail', { 
        productId: params.product_id 
      });
      break;
    case 'UserProfile':
      navigation.navigate('UserProfile', { 
        userId: params.user_id 
      });
      break;
    default:
      // 默认跳转到首页
      navigation.navigate('Home');
  }
};

额外排查点 #

• 检查Branch控制台的链接配置，确认你需要的参数已经添加到链接的自定义数据中。
• iOS端：确保Info.plist里配置了正确的Associated Domains（格式为applinks:<你的Branch域名>）。
• Android端：确认AndroidManifest.xml里的intent-filter配置正确，能匹配Branch的链接。

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