更新记录

1.0.0（2026-09-28）

首个版本，把阿里百川（淘宝联盟）电商 SDK 标准版能力封装为跨平台 UTS 插件，Android / iOS / 鸿蒙三端对外 API 完全一致。

新增

• 初始化：initAlibcSDK(options)，建议在 App.uvue 的 onLaunch 中调用一次
• 打开淘宝/天猫页面：openAlibcDetail（商品详情）、openAlibcShop（店铺）、openAlibcCart（购物车，仅 Android/iOS）、openAlibcUrl（任意 url）
• 淘宝授权：alibcLogin / alibcLogout / isAlibcLogin / getAlibcLoginInfo
• 淘客分佣：pid / adzoneId / subPid / unionId / extraParams
• 唤端控制：clientType（taobao / tmall）、forceNative、failMode（应用内 H5 / 下载页 / 浏览器 / 不处理）
• 回调统一为 success / fail / complete 三段式，内置演示页 pages/alibc/alibc.uvue

注意

• 必须打自定义基座或云打包，标准基座不包含插件内的 aar / framework / ohpm 依赖
• 需自行准备与「包名 + 签名 + AppKey」匹配的百川安全图片
• Android 打包需关闭资源混淆，否则安全图片改名会导致初始化失败

平台兼容性

uni-app

uni-app x(4.25)

阿里百川电商SDK（淘宝客） mh-alibc

插件名：mh-alibc 类型： UTS 插件（本体封装，非原生插件） 平台： Android / iOS / HarmonyOS SDK 版本： Android 4.2.0.0（标准版）/ iOS 4.1.0.5 / 鸿蒙 1.0.1 来源 demo： BaiChuan_Standard_Demo_4109 / iOS标准版官网Demo / BaichuanDemo_1112

把阿里百川 AlibcTradeSDK 的能力做了跨平台统一封装：初始化、打开淘宝/天猫页面（商品详情、店铺、购物车、任意 url）、淘宝授权登录。三端对外 API 完全一致，业务层不需要写平台判断。

一、接入前置（缺一项就跑不起来）

1. 安全图片（必须）

安全图绑定「包名 + 签名证书 + AppKey」，没有这张图，初始化必然失败（原生错误码 SecException 122）。

本插件已放入，且两平台的图不能互换——它们是两张不同的图，但文件名一模一样，极易弄混：

以下任一变更后都要重新生成安全图（用自己的签名打一个安装包 → 上传 百川后台）：换签名证书、改包名、换 AppKey。

⚠️ 遗留待核实项：当前这份图来自本产品 uni-app(vue) 版 app1.0，其文档记录「是否与后台本应用 AppKey/签名匹配仍待核实」。若真机报 122 且确认路径、文件名无误，就要按上面的方式重新生成并替换。

2. AppKey

当前使用 34381591（tbopen34381591）。若百川后台登记的不是这个值，需同步修改 两处：

• manifest.json → app-ios.distribute.urltypes
• utssdk/app-ios/Info.plist → CFBundleURLTypes

（鸿蒙端还要改 harmony-configs 里的 querySchemes，见第 4 条。）

3. Android 资源混淆必须关掉（关键坑）

百川安全组件是按固定资源名 yw_1222_baichuan 直接从 APK 里读这张图的字节的（不走 R 资源引用）。一旦被打包工具改名成 P_.jpg 之类，就会报 122。

manifest.json 已配置：

"app-android": {
    "distribute": {
        "enableResourceOptimizations": false,
        "aaptOptions": [ "noCompress 'png', 'jpg', 'jpeg'" ]
    }
}

同时确认 HBuilderX 打包/自定义基座界面里「资源混淆 / 混淆 res」的勾选已取消。

打包后 30 秒自检：把 apk 改名为 .zip 解开，检查 res/drawable/yw_1222_baichuan.jpg 是否存在（名字没变说明配置生效）；若只看到 P_.jpg 之类的短名，就是资源混淆没关掉。

4. 鸿蒙端需要在项目里补两处（插件层改不了）

harmony-configs/ 下：

（1）overrides 只能在根 oh-package 生效（DCloud 文档明确说明 UTS 插件的依赖位于非根目录，overrides 不生效）

先跑一次生成 unpackage/dist/dev/app-harmony，把其中的 oh-package 源文件复制到 harmony-configs/oh-package，再加：

"overrides": { "@ohos/alibc": "file:./libs/alibc-default_1_0_1_2026_04_08.tgz" }

（2）声明 querySchemes 与回跳 scheme（官方 demo 写在 entry/src/main/module.json5 与 EntryAbility 的 skills.uris 里）

"querySchemes": ["tbopen", "tbaccount你的appkey"],
// EntryAbility skills.uris
{ "scheme": "taobaooauth你的appkey" }

这两处不配，鸿蒙端无法检测/唤起淘宝。

5. 必须打自定义基座 / 云打包

插件引入了 aar / framework / gradle / ohpm 依赖，标准基座跑不起来。

运行 → 运行到手机或模拟器 → 制作自定义调试基座，之后云打包。

另外 iOS 端的 UTS 插件编译需要 Mac + Xcode，Windows 上只能走云打包。

二、目录结构

uni_modules/mh-alibc/
├─ readme.md                      本文件
├─ package.json                   插件声明（三端均已启用）
└─ utssdk/
   ├─ interface.uts               跨平台类型定义（字段与官方 demo 对齐）
   ├─ app-android/
   │  ├─ index.uts                封装实现
   │  ├─ config.json              minSdkVersion 21 + fastjson 依赖
   │  ├─ AndroidManifest.xml      权限 + queries 包可见性 + exported 修复
   │  ├─ libs/                    11 个 aar + 2 个 jar
   │  └─ res/drawable/            安全图片
   ├─ app-ios/
   │  ├─ index.uts                封装实现
   │  ├─ config.json              deploymentTarget 12.0 + 15 个系统库
   │  ├─ Info.plist               scheme 与查询白名单
   │  ├─ Frameworks/              20 个 .framework
   │  └─ Resources/               5 个 .bundle + 安全图片
   └─ app-harmony/
      ├─ index.uts                封装实现
      ├─ config.json              @ohos/alibc 本地 tgz 依赖
      ├─ module.json5             网络权限
      └─ libs/                    alibc-default_1_0_1_2026_04_08.tgz

三、API

初始化

在 App.uvue 的 onLaunch 里调一次即可。

import { initAlibcSDK } from '@/uni_modules/mh-alibc'

initAlibcSDK({
    isvVersion: '2.2.2',
    isvAppName: 'miaohui',
    debug: false,
    success: () => {
        console.log('百川 SDK 初始化成功')
    },
    fail: (code : number, msg : string) => {
        console.log('百川 SDK 初始化失败', code, msg)
    }
})

方法一览

回调一律是 uni 习惯的 success / fail / complete 三段式。

打开淘宝页面

import { openAlibcDetail } from '@/uni_modules/mh-alibc'

const extra = new Map<string, string>()
extra.set('taokeAppkey', '你的淘客appkey')   // 走 adzoneId 分佣时必传，否则打点失败

openAlibcDetail('37196464781', {
    taoke: {
        pid: 'mm_98836808_1507450087_110257500101',
        adzoneId: '110257500101',
        extraParams: extra
    },
    clientType: 'taobao',   // taobao | tmall，默认 taobao
    forceNative: false,     // true=强制唤端(OpenType.Native)
    failMode: 0,            // 0=应用内H5(默认) 1=下载页 2=浏览器 3=不处理
    success: (resultType : number) => {
        // 只有「加购成功」或「发生支付」才回调：0=加购 1=支付
        console.log('交易回调', resultType)
    },
    fail: (code : number, msg : string) => {
        console.log('打开失败', code, msg)
    }
})

failMode 对外是统一语义，各端内部自己映射。iOS / 鸿蒙没有「跳浏览器」模式，传 2 会退化为 0。

授权登录

import { alibcLogin, isAlibcLogin, getAlibcLoginInfo } from '@/uni_modules/mh-alibc'

alibcLogin({
    success: (loginResult : number, userId : string, nick : string) => {
        console.log('登录成功', loginResult, userId, nick)
    },
    fail: (code : number, msg : string) => {
        console.log('登录失败', code, msg)
    }
})

if (isAlibcLogin()) {
    const info = getAlibcLoginInfo()
    if (info != null) {
        console.log(info.userId, info.nick, info.openId, info.avatarUrl)
    }
}

有完整交互演示页：pages/alibc/alibc.uvue。

四、各平台差异

两个已知缺口

iOS 回跳：淘宝回跳到 tbopen34381591 后，需要把 URL 转交给 [[AlibcTradeSDK sharedInstance] application:openURL:options:] 才能完成回跳与登录态同步。这属于 AppDelegate 层，UTS 插件挂不上钩子，需要在 nativeResources/ios/ 或原生混编里处理。

鸿蒙回跳：官方 demo 在 EntryAbility.onNewWant 里调用 Alibc.onNewWant(want)。UTS 插件挂不到 UIAbility 的 onNewWant，本插件用 UTSHarmony.onAppAbilityWindowStageCreate 拿 Context 并调 setAuthorizeWindowStage，能覆盖 init 和授权浮层，但覆盖不了 onNewWant，所以鸿蒙端的分佣回跳链路可能不完整。

五、与 uniCloud 云函数的边界（重要）

百川 SDK 不需要、也不可能放进云函数。

它三端分别是 Java aar / Objective-C framework / ArkTS har+hsp，而 uniCloud 云函数是 Node.js 运行时，加载不了这些二进制。更根本的原因是它依赖的东西全在设备上：唤端要拉手机淘宝、安全图绑定「包名 + 签名证书」、设备标识取自本机、授权会话落在本地 WebView。这些云函数一个都拿不到。

但和它配对的那一半，本来就必须在云函数里（而且本项目已经有了）：

衔接点

1. AppKey 三处是同一个值 34381591

云函数 app-cps/uniCloud/cloudfunctions/common/cps-util/tb-top.js 里的 appKey、百川后台登记的 AppKey、iOS scheme tbopen34381591 —— 已经核对一致。换 AppKey 时三处都要改。

2. pid / adzoneId 建议走云函数下发，别写死在客户端

cps-taobao 的 getPlatformConfig 已经会返回 pid 与 adzoneId，正好就是本插件打开页面时 taoke 要传的两个字段：

// 伪代码：pid 从云端拿，再喂给百川 SDK
const cfg = await getPlatformConfig()   // 已有云函数
openAlibcDetail(itemId, {
    taoke: { pid: cfg.pid, adzoneId: cfg.adzoneId }
})

3. 「先转链再打开」比「直接 openAlibcDetail」更可控

直接用 openAlibcDetail 是把转链交给 SDK 内部处理；如果佣金归属或埋点要精确控制，更稳的链路是：云函数转链拿到带券链接 → 客户端用 openAlibcUrl 打开。项目里 cps-taobao 的 convertLink / convert / convertUrl 已经是现成的转链入口。

4. ⚠️ 两套授权体系不要混用

这是最容易踩的坑：

alibcLogin 拿到的 openId 不能当 TOP 的 access_token/session 用；反过来阿里妈妈的 token 也不能让淘宝 App 免登录。两者是独立的，绑用户账号时不要互相顶替。

六、排查

各端 SDK 依赖（已随插件落地，勿单独删减）

• Android：13 个文件是互相依赖的整体，拆开必然 ClassNotFoundException。nb_trade 是入口，依赖 AlibcTradeCommon/AlibcTradeBiz/alibc_link_partner/alibabauth_*/osmss3rd-*/ut-analytics，外加 mtopsdk_allinone_open.jar 与 utdid4all.jar（网络层与设备标识，必选）。
• iOS：20 个 framework + 5 个 bundle。其中 5 个 framework 原本缺 Modules/module.modulemap（Swift 无法 import），已补齐；AlibabaAuthSDK.framework 无 Headers，属纯二进制，随链接自动带入。
• 鸿蒙：必须用官方发的 .tgz，不能只用单独的 .har。alibc.har 是接口声明包（packageType: InterfaceHar + integratedHsp: true，内部只有 .d.ets），真实现全在 .hsp 里；.tgz 把两者一起打包，ohpm 才能正确安装。

七、第三方 SDK 与合规声明（分发前必读）

1. 插件里带的是什么

本插件是阿里百川（淘宝联盟）电商 SDK 标准版的封装层，不含业务实现，随附的二进制全部来自官方 SDK 包：

2. 再分发授权

插件内含第三方 SDK 二进制，作者不代任何一方授予再分发权利。对外分发（发布到插件市场、交付给客户、开源仓库等）之前，请自行确认：

1. 已通过 百川开放平台 取得该 SDK 的使用与再分发授权，并遵守其最新协议。
2. 安全图 yw_1222_baichuan.jpg 必须绑定你自己的包名、签名证书与 AppKey。不要使用他人（含本插件示例）的安全图对外发布——那等于把别人的 AppKey 带进你的包，分佣与授权都会出问题。
3. 上架应用商店时，按各商店要求自行完成第三方 SDK 合规申报：隐私政策中说明 SDK 名称、提供方、使用目的与采集的信息类型。

3. 数据与权限

• 本插件不采集任何数据，没有作者服务器，不产生任何回传。唤起淘宝、授权登录等网络请求由百川 SDK 直接发起。
• 插件自身在 Android 侧只声明网络相关权限（INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE）与包可见性 <queries>；其余权限由百川 aar 自带的清单在合并时引入，请以最终 APK 的清单为准。
• 百川 SDK 会读取设备标识（UTDID）用于其自身的归因与风控，这属于 SDK 行为，不是本插件额外添加的。

4. 关于 package.json 的 uni_modules.encrypt

该字段在 uni_modules 规范中的用途是加密云函数 / 公共模块 / clientDB Action，填这些文件的真实路径：

"uni_modules": {
    "dependencies": [],
    "encrypt": [ // 配置云函数，公共模块，clientDB Action加密
        "uniCloud/cloudfunctions/uni-admin/controller/permission.js"
    ]
}

本插件是纯客户端 UTS 插件，不含云函数与公共模块，因此保持为空数组 []，这是正确配置（填 uts 源码路径不会生效）。

UTS 源码的保护由插件市场的付费插件机制处理（dcloudext.sale.sourcecode.price 这一档由 DCloud 提供加密与版权保护），作者端不需要也无法通过 encrypt 配置。