更新记录

0.1.0（2026-03-03） 下载此版本

更新日志

[0.1.0] - 2026-03-03

新增

• 新增 uni-app 原生插件 Branch-UniPlugin，支持 Android + iOS 双端集成。
• 新增会话初始化能力 initSession，支持返回归因参数。
• 新增动态配置 Branch Key 能力 setBranchKey。
• 新增用户身份绑定能力 setIdentity。
• 新增用户登出能力 logout。
• 新增首次归因参数获取 getFirstReferringParams。
• 新增最新归因参数获取 getLatestReferringParams。
• 新增短链生成能力 generateShortUrl。
• 新增事件上报能力 logEvent。
• 新增 JS Promise 封装调用层（js_sdk/index.js）。

iOS

• 集成 BranchSDK.framework，完成原生桥接模块 BranchUniModule。
• 支持 branchKey 与 useTestKey 运行时配置。
• 支持 launchOptions、isReferrable 初始化参数透传。

Android

• 集成 Branch Android SDK（io.branch.sdk.android:library:5.20.3）。
• 完成原生桥接模块 BranchUniModule。
• 支持 branchKey 与 useTestKey 运行时配置。
• 支持短链参数（alias/channel/feature/stage/campaign/tags/params）透传。

配置

• 新增插件市场参数映射：
  • android_live_branch_key -> io.branch.sdk.BranchKey
  • android_test_branch_key -> io.branch.sdk.BranchKey.test
  • ios_live_branch_key -> branch_key:live
  • ios_test_branch_key -> branch_key:test
• Android 新增网络权限声明：
  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE

文档

• 新增 README，包含接入说明、API 列表、调用示例、上架检查清单。

注意事项

• 插件调用名为：Branch-UniPlugin
• 请在 App 端（自定义基座/云打包安装包）中使用，H5 环境下不可用。

平台兼容性

uni-app(4.0)

uni-app x(5.0)

Branch-UniPlugin（uni-app 原生插件）

1. 插件简介

Branch-UniPlugin 用于在 uni-app 中调用 Branch 原生 SDK（Android + iOS），提供统一的 JS API，支持深度链接归因、身份绑定、短链生成、事件上报等能力。

当前插件类型为 module，适用于 uni-app App 端（云端打包 / 原生离线打包）。

2. 功能列表

• 初始化会话（支持测试环境切换）
• 动态设置 Branch Key（支持 test/live）
• 设置用户身份
• 用户登出
• 获取首次归因参数
• 获取最新归因参数
• 生成短链
• 上报自定义事件

3. 目录结构

uni-branch-plugin/
├─ package.json
├─ js_sdk/
│  └─ index.js
├─ android/
│  ├─ build.gradle
│  └─ src/main/java/io/branch/uniplugin/BranchUniModule.java
└─ ios/
   ├─ BranchUniModule.h
   └─ BranchUniModule.m

4. 接入前准备

4.1 Branch 后台

• 在 Branch 控制台创建应用并获取：
  • Live Key（key_live_xxx）
  • Test Key（key_test_xxx）

4.2 iOS 动态库

• 本插件 package.json 已声明 BranchSDK.framework。
• 发布插件包时，请将 BranchSDK.framework 放到 ios/ 目录下，并与本插件一起打包上传。
• 这里必须是已编译好的 .framework 成品，不能直接放 Branch SDK 的源码目录。

5. 插件配置（package.json）

已支持在云打包配置参数注入：

• Android
  • android_live_branch_key -> io.branch.sdk.BranchKey
  • android_test_branch_key -> io.branch.sdk.BranchKey.test
• iOS
  • ios_live_branch_key -> branch_key:live
  • ios_test_branch_key -> branch_key:test

Android 侧已声明网络权限：

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE

6. JS API

插件引入：

import Branch from '@/nativeplugins/Branch-UniPlugin/js_sdk/index.js'

6.1 initSession(options)

初始化 Branch 会话。

options 可选字段：

• branchKey: string
• useTestKey: boolean
• launchOptions: object（iOS）
• isReferrable: boolean（iOS）

6.2 setBranchKey(branchKey, useTestKey) / setBranchKey(options)

动态设置 Key，支持两种写法：

await Branch.setBranchKey('key_test_xxx', true)
await Branch.setBranchKey({ branchKey: 'key_live_xxx', useTestKey: false })

6.3 setIdentity(userId)

await Branch.setIdentity('user_1001')

6.4 logout()

await Branch.logout()

6.5 getFirstReferringParams()

const firstParams = await Branch.getFirstReferringParams()

6.6 getLatestReferringParams()

const latestParams = await Branch.getLatestReferringParams()

6.7 generateShortUrl(options)

const result = await Branch.generateShortUrl({
  alias: 'invite-1001',
  channel: '***',
  feature: 'share',
  stage: 'onboarding',
  campaign: 'spring',
  tags: ['invite', 'v1'],
  params: {
    userId: '1001',
    from: 'invite'
  }
})

6.8 logEvent(options)

await Branch.logEvent({
  eventName: 'purchase',
  customData: {
    orderId: 'A0001',
    amount: '99.00'
  }
})

7. 完整示例

import Branch from '@/nativeplugins/Branch-UniPlugin/js_sdk/index.js'

async function runBranchFlow() {
  await Branch.setBranchKey('key_test_xxx', true)
  await Branch.initSession({ useTestKey: true, isReferrable: true })
  await Branch.setIdentity('user_1001')
  const latest = await Branch.getLatestReferringParams()
  const short = await Branch.generateShortUrl({
    channel: '***',
    feature: 'share',
    params: { uid: '1001' }
  })
  await Branch.logEvent({ eventName: 'share_success', customData: { url: short.url } })
  return latest
}

8. 返回格式

原生层统一返回：

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {}
}

• errCode = 0 表示成功
• errCode != 0 表示失败，JS 层会 reject 为 Error

9. 上架前检查清单（uni 插件市场）

1. 确认 package.json 为合法 JSON，且 _dp_type 为 nativeplugin
2. 确认 android 与 ios 的 plugins、integrateType、frameworks 配置正确
3. 确认 ios/BranchSDK.framework 已放入插件目录
4. 用 HBuilderX 通过本地插件进行一次云端打包验证
5. 验证以下核心接口可正常调用：
   • initSession
   • setBranchKey
   • generateShortUrl
   • logEvent
6. 将插件目录压缩为 zip（压缩包内需包含 uni-branch-plugin 顶层目录）
7. 在 uni 插件市场提交 zip 并填写说明、更新日志、测试账号信息（如需要）

10. 已知说明

• 请确保业务在调用 generateShortUrl 前已执行 initSession。
• iOS/Android 的 Branch key 配置错误会导致初始化或上报失败。
• setUseTestBranchKey 与 setBranchKey 建议在会话初始化前设置。