问题描述 #

先给大家梳理下我遇到的（相信很多开发者也踩过的）具体异常场景：

• 异常现象：在WhatsApp消息的按钮中点击Branch.io深度链接（如https://abc.app.link/sample-link），无法直接唤起已安装的目标APP；
• 错误跳转流程：点击链接后先打开WhatsApp内嵌浏览器，随后自动重定向到Play Store；
• 后续数据丢失：在Play Store弹窗中点击「打开」唤起APP后，APP内的深度链接监听器完全接收不到任何链接参数。

核心原因分析 #

折腾了好几天，终于定位到是两个层面的问题叠加导致的：

1. WhatsApp内嵌浏览器的拦截逻辑：WhatsApp的内置WebView会拦截标准的深度链接唤起行为，强制走网页重定向流程，直接绕过了Branch.io的「直接唤起APP」机制；
2. Branch链接的延迟关联配置缺失：默认的Branch链接在重定向到Play Store时，没有把原始深度链接的参数通过延迟关联的方式存储，导致从Play Store跳转回APP后，无法恢复之前的链接上下文。

分步解决方案 #

下面是我亲测有效的修复步骤，从控制台配置到客户端代码调整都覆盖到了：

1. 调整Branch控制台的链接跳转规则

• 登录Branch控制台，进入对应项目的「Link Settings」页面；
• 找到「Redirect Behavior」模块，针对已安装APP的设备，把跳转行为从默认的「Redirect to App Store」改成「Direct Open App」；
• 开启「Deferred Deep Linking」（延迟深度链接）功能，这个是关键！它能让Branch通过设备标识，把Play Store跳转的用户和之前的深度链接请求关联起来；
• 针对WhatsApp做UA特殊规则：在「Advanced Options」里添加User Agent过滤，当检测到UA包含WhatsApp关键词时，强制触发APP唤起逻辑，跳过网页重定向。

2. 移动端SDK配置与代码校验

Android端（Manifest + 初始化逻辑）

• 先检查目标Activity的intent-filter配置，确保包含Branch链接的域名和自定义scheme，并且加上android:autoVerify="true"：

<activity android:name=".MainActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 替换为你的Branch链接域名 -->
        <data android:scheme="https" android:host="abc.app.link" />
        <data android:scheme="abc" /> <!-- 自定义scheme，用于直接唤起 -->
    </intent-filter>
</activity>

• 确保APP启动时尽早初始化Branch SDK，在Application的onCreate方法里添加：

@Override
public void onCreate() {
    super.onCreate();
    Branch.getAutoInstance(this);
}

• 最后在MainActivity里正确处理链接数据，覆盖onStart和onNewIntent方法，保证APP从后台唤起时也能拿到参数：

@Override
protected void onStart() {
    super.onStart();
    Branch.sessionBuilder(this).withCallback(branchReferralInitListener).init();
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    Branch.sessionBuilder(this).withCallback(branchReferralInitListener).reInit();
}

private final BranchReferralInitListener branchReferralInitListener = new BranchReferralInitListener() {
    @Override
    public void onInitFinished(JSONObject referringParams, BranchError error) {
        if (error == null) {
            // 这里处理拿到的深度链接参数
            Log.d("BranchData", "收到链接参数：" + referringParams.toString());
        } else {
            Log.e("BranchError", "链接解析失败：" + error.getMessage());
        }
    }
};

iOS端（Info.plist + 代码逻辑）

• 先在Info.plist里配置好Universal Links和自定义scheme：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>abc</string> <!-- 自定义scheme -->
        </array>
    </dict>
</array>
<key>NSUserActivityTypes</key>
<array>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER).branch</string>
</array>

• 在AppDelegate里完成Branch初始化和Universal Links的处理：

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
        if let validParams = params {
            // 处理深度链接参数
            print("收到Branch链接参数：\(validParams)")
        }
    }
    return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return Branch.getInstance().continue(userActivity)
}

3. 测试验证技巧

• 清除WhatsApp缓存：WhatsApp会缓存链接的跳转结果，测试前一定要进入WhatsApp设置清除缓存，避免旧的错误行为干扰；
• 模拟WhatsApp UA测试：在Branch控制台的「Link Tester」里，输入WhatsApp的UA字符串（比如Mozilla/5.0 (Linux; Android 10; SM-G973F) AppleWebKit/537.36 (KHTML, like Gecko) WhatsApp/2.23.10.72 Chrome/109.0.5414.89 Mobile Safari/537.36），预览链接的跳转路径是否正确；
• 查看Branch统计：在Branch Dashboard的「Analytics」里，检查点击事件的UA标识和跳转路径，确认是否正确识别了WhatsApp环境。

额外注意事项 #

• 一定要用最新版本的Branch SDK：旧版本的SDK大概率没适配WhatsApp内嵌浏览器的最新拦截规则；
• Android 12+权限配置：如果APP目标SDK是31及以上，需要在AndroidManifest.xml里添加queries条目，允许检测Branch相关的包：

<queries>
    <package android:name="io.branch.sdk.android" />
</queries>

• 别搞短链嵌套：不要在Branch链接外面再套一层其他短链，否则会彻底干扰Branch的跳转逻辑识别。

如果大家还有其他特殊场景的问题，欢迎在评论区一起讨论～