Flutter Android中Branch.io链接跳转异常问题求助

核心问题回顾 #

• 点击Branch验证链接可唤起App，但payload被识别为非Branch链接
• 自定义Branch链接点击后跳转fallback页面，但手动打开App后监听器能获取到payload
• 使用url_launcher打开链接出现相同异常，且为仅集成Branch SDK的纯净新项目

分步排查与修复 #

1. 检查Android Manifest 配置 #

• 确认Branch专属的intent-filter配置完整且正确，需包含scheme、host，并设置高优先级确保优先处理：

  <intent-filter android:autoVerify="true" android:priority="1000">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="你的Branch Scheme" />
      <data android:host="open" />
  </intent-filter>
  

• 确保android:autoVerify="true"已添加，且与Branch控制台的Android配置中填写的域名完全匹配，避免其他intent-filter抢占链接处理逻辑。

2. 确认Branch SDK初始化时机 #

• 在main()方法中优先完成Branch初始化，必须在WidgetsFlutterBinding.ensureInitialized()之后执行：

  void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    // 注意区分测试/生产环境的Branch Key，不要混用
    await BranchIO.init("your_branch_key");
    runApp(const MyApp());
  }
  

• 禁止在初始化前执行页面跳转或其他异步操作，确保SDK完全启动后再处理业务逻辑。

3. 修正链接监听器注册逻辑 #

• 在App首页的initState()中尽早注册Branch监听器，避免错过链接唤醒事件：

  @override
  void initState() {
    super.initState();
    BranchIO.listener((payload) {
      // 直接打印payload排查内容，确认是否为Branch格式
      print("Branch Payload: $payload");
    });
  }
  

• 不要将监听器注册延迟到用户交互后，确保App启动时就监听深层链接事件。

4. 验证App Links 配置有效性 #

• 检查Branch控制台的Android配置中，SHA256 指纹与当前打包使用的签名指纹完全一致（debug/release环境需分别配置）。
• 确认assetlinks.json已正确部署到域名的/.well-known/路径，文件内容需包含App的包名和对应签名指纹，可直接通过浏览器访问该文件验证有效性。

5. 调整url_launcher 调用方式 #

• 使用LaunchMode.externalApplication让系统处理链接，避免在App内WebView打开导致Branch无法拦截：

  await launchUrl(
    Uri.parse("your_branch_link"),
    mode: LaunchMode.externalApplication,
  );
  

• 禁止使用LaunchMode.inAppWebView或强制WebView打开的参数，确保链接触发系统的深层链接解析逻辑。

6. 启用调试日志定位问题 #

• 开启Branch调试日志，查看链接解析过程中的错误信息：

  // 初始化前开启调试模式
  await BranchIO.setDebug(true);
  await BranchIO.init("your_branch_key");
  

• 查看Android Studio的Logcat，过滤Branch关键词，重点关注签名验证、intent匹配、链接解析相关的报错信息。

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