Unity C#中如何捕获Branch.io延迟深度链接的键值参数？

我刚好在Unity项目里折腾过Branch的延迟深度链接，给你整理一套完整的C#实现步骤，亲测靠谱：

一、先确保Branch SDK初始化时机正确 #

延迟深度链接的核心是APP启动时第一时间捕获链接参数，所以初始化代码一定要放在APP启动的最早阶段，比如挂载在一个全局单例的Awake()方法里：

using UnityEngine;
using BranchX;

public class BranchDeepLinkHandler : MonoBehaviour
{
    void Awake()
    {
        // 初始化Branch会话，传入回调方法处理深度链接
        Branch.InitSession(OnDeepLinkReceived, this);
    }

    // 深度链接回调：冷启动APP时会触发
    void OnDeepLinkReceived(BranchUniversalObject buo, BranchLinkProperties linkProps, string error)
    {
        if (!string.IsNullOrEmpty(error))
        {
            Debug.LogError("Branch初始化出错: " + error);
            return;
        }

        // 拿到参数后，交给专门的方法处理路由逻辑
        ProcessDeepLinkParams(buo, linkProps);
    }
}

二、读取链接中的自定义键值参数 #

你在Branch后台/API创建链接时添加的自定义参数（比如target_screen、item_id），都会存在BranchUniversalObject的ContentMetadata.CustomData字典里，直接读取即可：

void ProcessDeepLinkParams(BranchUniversalObject buo, BranchLinkProperties linkProps)
{
    if (buo == null || buo.ContentMetadata?.CustomData == null)
    {
        Debug.Log("没有获取到深度链接参数");
        return;
    }

    // 示例1：读取"target_screen"参数，跳转指定页面
    if (buo.ContentMetadata.CustomData.TryGetValue("target_screen", out object targetScreenObj))
    {
        string targetScreen = targetScreenObj.ToString();
        Debug.Log("要跳转的目标页面: " + targetScreen);
        // 调用你的页面跳转逻辑，比如用SceneManager加载场景
        // SceneManager.LoadScene(targetScreen);
    }

    // 示例2：读取"item_id"参数，加载指定内容详情
    if (buo.ContentMetadata.CustomData.TryGetValue("item_id", out object itemIdObj))
    {
        string itemId = itemIdObj.ToString();
        Debug.Log("要加载的商品ID: " + itemId);
        // 调用你的内容加载逻辑
        // ItemDetailManager.LoadItem(itemId);
    }

    // 额外：还能读取Branch自带的链接属性，比如渠道、标签
    if (linkProps != null)
    {
        Debug.Log("链接来源渠道: " + linkProps.Channel);
        Debug.Log("链接标签: " + string.Join(",", linkProps.Tags));
    }
}

三、处理APP后台唤醒的场景 #

如果用户点击链接时APP已经在后台运行，冷启动的回调不会触发，这时候需要订阅Branch的DeepLinkActivated事件来捕获：

void OnEnable()
{
    // 订阅热启动时的深度链接事件
    Branch.DeepLinkActivated += OnDeepLinkActivated;
}

void OnDisable()
{
    // 记得取消订阅，避免内存泄漏
    Branch.DeepLinkActivated -= OnDeepLinkActivated;
}

void OnDeepLinkActivated(BranchUniversalObject buo, BranchLinkProperties linkProps)
{
    // 复用之前的参数处理方法
    ProcessDeepLinkParams(buo, linkProps);
}

四、测试小技巧 #

• 在Branch后台生成测试链接，手动添加自定义参数（比如target_screen=Shop&item_id=1001）
• 冷启动测试：完全退出APP，点击链接看控制台是否打印参数
• 热启动测试：把APP切到后台，点击链接看是否能触发DeepLinkActivated事件

常见坑排查 #

• 如果捕获不到参数，先检查初始化代码是不是在所有逻辑之前执行（比如不要放在某个场景的Start里，要放在全局单例的Awake里）
• 确认Branch后台的链接配置中，自定义参数的键名和代码里的完全一致（大小写敏感！）
• 虽然你说快速链接能打开APP，但还是要核对Android的AndroidManifest.xml、iOS的Info.plist里的深度链接配置是否完整，这是延迟链接生效的基础

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