更新记录

0.0.1（2026-11-05）

第一个版本,支持 uni-app x 蒸汽模式 Android/iOS (鸿蒙等待手机来测试) Android 阿里百川旗舰版 5.0.2.6 iOS 阿里百川旗舰版 5.0.0.18

平台兼容性

uni-app(5.31)

uni-app x(5.31)

其他

长寻阿里百川插件

插件 ID：changxun-alibc。统一 UTS API 插件，封装阿里百川旗舰版。面向 uni-app x 蒸汽模式，Android 与 iOS 共用接口，原生实现独立；鸿蒙暂未实现。

功能与支持范围

已验环境为 HBuilderX 5.34、uni-app x Vapor、匹配签名的自定义基座和真机。Android 主要测试机为 Android 14；编译最低 Android 6.0，不能理解为所有系统已测。iOS 最低 15.5，仅 arm64 真机。普通 uni-app、VDOM、模拟器、鸿蒙、Web、小程序不在当前已验范围。

当前版本 Android 旗舰版 5.0.2.6 / iOS 旗舰版 5.0.0.18。两端已验证与 DCloud 支付宝模块共存，保留百川 UTDid；没有执行真实支付。未取得独立拒绝回调的场景仍按原始失败码处理，不把取消等同拒绝。

1. 从插件市场安装

1. 在 HBuilderX 5.34 或更高版本中创建或打开 uni-app x 蒸汽模式工程。
2. 在 DCloud 插件市场搜索 changxun-alibc，从详情页选择“使用 HBuilderX 导入插件”，选择你的工程。授权方案以最终市场页面为准。
3. 安装后本地会出现 uni_modules/changxun-alibc，这是市场模块正常的接口与配置文件，不是让业务 App 手工维护源码副本。
4. 使用根目录导入；更新时右键插件目录选择“从插件市场更新”。不使用旧 Weex 的 requireNativePlugin。

import {
  initialize, login, logout, getLoginState, getUserInfo,
  authorizeTop, openPromotionUrl, openProduct, openCart
} from '@/uni_modules/changxun-alibc'

市场安装示例单独提供，不内置插件源码；首次发布前没有虚构的数字详情页 ID。先从真实市场安装再运行。发布候选包用于作者上传，不能代替消费者的市场安装验收。

2. 准备每个宿主自己的材料

插件 ID 不是宿主包名。Android 的安全图申请还需匹配签名 APK。安全图、证书、密码、Token 不提交 Git、不放市场示例、不发到作者服务器。

3. Android 宿主配置

使用当前 Android 旗舰版匹配的 V6.1 安全图。将官方取得的图片保持原始字节，按本插件锁定 SDK 的集成名称放到：

<宿主工程>/nativeResources/android/res/drawable/yw_1222_baichuan.jpg

以上是本版已验 SDK 的实际资源名，不是直接把旧教程的 yw_1222.jpg 放入 assets。不要压缩、裁剪、转格式，也不要用安全图当授权图标。

在宿主 manifest.json 合并以下配置，保留已有字段：

{
  "uni-app-x": { "vapor": true, "vapor-render-target": "bytecode" },
  "app-android": { "distribute": { "enableResourceOptimizations": false } }
}

安全图按名称加载，必须禁止资源重命名。不要移除插件自带的淘宝/天猫包可见性声明，否则可能影响拉起淘宝。

Android 14 蒸汽自定义基座兼容

本版百川 UC 调试内核在默认蒸汽宿主上曾复现广播兼容问题。生成测试宿主兼容配置后再云打包：

python uni_modules/changxun-alibc/debug-host/prepare.py --project "<宿主工程绝对路径>" --package-name "<自己的Android包名>" --hbuilderx "<HBuilderX安装目录>" --jdk "<JDK17安装目录>"

此脚本使用本机 HBuilderX/JDK 编译自有适配器，生成宿主 AndroidManifest.xml 和适配器 AAR；云端实际使用随工程上传的 AAR，不读取本机磁盘。需要 Python 3 和 JDK 17。已有自定义 Application/Factory 时脚本会停止，先合并宿主兼容逻辑，不覆盖其他插件配置。该步骤针对调试基座，正式发行配置需独立核验；SDK、资源或原生配置变化后重新打基座。

4. iOS 宿主配置

使用对应 iOS 应用的 V6 安全图，当前验收版本不能沿用 Android V6.1 图。放入：

<宿主工程>/nativeResources/ios/Resources/yw_1222_baichuan.jpg
<宿主工程>/nativeResources/ios/Resources/mtopsdk_configuration.plist

第二个文件内容为：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict><key>DefaultID</key><string>OPEN</string></dict></plist>

宿主 manifest.json 设置 app-ios.distribute.deploymentTarget 为 15.5 或更高。宿主根目录 Info.plist 的 CFBundleURLTypes 追加 tbopen<本宿主百川AppKey>，保留其他回跳 scheme；例如 AppKey 为占位值 123456 时为 tbopen123456，必须替换为自己的实际值：

<key>CFBundleURLTypes</key>
<array><dict>
  <key>CFBundleTypeRole</key><string>Editor</string>
  <key>CFBundleURLName</key><string>ChangxunAlibc</string>
  <key>CFBundleURLSchemes</key><array><string>tbopen123456</string></array>
</dict></array>

插件已声明淘宝查询 scheme，并通过 UTS 生命周期钩子接收回跳，不要再次重复转发。安全图放宿主资源中，不需要使用者修改加密实现。

iOS 插件内包含针对当前 SDK 的宿主 Bundle 与 Scene 窗口兼容适配，不绕过百川安全校验；SDK 升级需要重新回归。UTDid 默认保留，当前 DCloud 支付宝组合不需要删除它。宿主外部提供模式尚无已验运行组合，不能仅因勾选支付宝就删除 UTDID.framework。

5. 初始化与淘宝登录

在用户阅读并同意宿主隐私政策之后初始化。appKey 使用当前运行平台对应的值。下例中的变量应来自宿主配置与真实隐私同意状态：

initialize({ appKey: hostAppKey, privacyAccepted: userAcceptedPrivacy }, (result) => {
  if (result.code != 'OK') {
    // 向用户展示状态和可重试入口；不要打印完整授权对象。
    return
  }
  login((loginResult) => {
    if (loginResult.code == 'OK') {
      // 淘宝 SDK 已登录；不等于本 App 会员渠道绑定成功。
    }
  })
})

淘宝已登录时优先走官方客户端授权；是否显示确认页、短信身份验证或降级页面由淘宝 SDK/风控决定，不承诺无条件免密。重复初始化和重复登录仍通过正式接口处理，不缓存一个虚假的成功状态。

getLoginState((r) => { /* LOGGED_IN / LOGGED_OUT / 其他状态 */ })
getUserInfo((r) => { /* r.code、r.openId、r.nickname；不是淘宝数字用户ID */ })
logout((r) => { /* 等待回调；iOS退出存在异步时序 */ })

6. TOP 原生二次授权与渠道绑定

登录成功后调用。官方小窗口下方保留使用者 App 当前页面，插件不附带等待页或作者业务页。

authorizeTop(hostAppKey, (result) => {
  if (result.code == 'OK') {
    // result.accessToken 是敏感凭据；仅经 HTTPS 交给你自己的服务端核验。
    // result.expiresRaw 为 SDK 原始有效期字符串，不自行当成毫秒时间戳。
    // 服务端完成联盟渠道备案后，宿主再更新会员绑定状态和 RID。
  } else if (result.code == 'CANCELLED') {
    // 保持当前宿主页面，允许用户主动重试。
  }
}, { appName: '你的应用名称', iconResourceName: '你的宿主图标资源名' })

第三个参数可省略：默认使用宿主名称和图标。Android 本地图标示例为 drawable/auth_logo；iOS 为宿主 Bundle 图片资源名。Android 也支持 iconUrl HTTPS 地址；iOS 传 iconUrl 返回 NOTSUPPORTED。不要同时传 iconUrl 与 iconResourceName。不可使用 yw 安全资源名作为图标。

插件不直接生成 RID、不绑定任何作者后台，不宣称淘宝登录或 TOP 成功就等于会员返利身份绑定成功。服务端契约由使用者自行设计。

7. 推广链接、详情和购物车

openPromotionUrl(hostPromotionUrl, (r) => { /* OPEN_ACCEPTED表示SDK接受打开 */ })
openProduct({ suiteCode: '', productId: hostProductId, pid: '', relationId: '' }, (r) => {})
openCart({ suiteCode: '', pid: '', relationId: '' }, (r) => {})

使用已归因的淘宝/天猫 HTTPS 推广链接时不要重复拼 PID/RID。默认详情/购物车走淘宝客户端，不需要 suiteCode。需要归因的联盟商品标识建议先由宿主服务端转成推广链接再打开；相关参数校验可能返回 PROMOTION_URL_REQUIRED。

suiteCode 只用于百川内嵌套件，必须由宿主在百川开通。Android 内嵌路径未完成本版真机验收，iOS 非空 suiteCode 明确返回 NOT_IMPLEMENTED。OPEN_ACCEPTED 不代表用户已返回、下单或付款，宿主如需刷新页面应结合自己的页面生命周期。

8. 错误、取消、超时和重试

接口有120秒超时；超时后不会再次回调同一请求成功。用户完成淘宝验证后可能已经登录，先 getLoginState 再决定是否重试。iOS 实测登录取消1002、TOP关闭1001601分别映射 CANCELLED，不能跨接口套用原生码。

9. 打包、更新与示例

• 安全图、SDK、原生配置改变后必须重打自定义基座，普通热更新不更新原生库。
• 原生依赖随工程上传或使用实际声明的 Maven/CocoaPods 来源，不需要作者服务器。
• 若最终采用付费普通授权，UTS/原生混编实现按市场规则加密；试用只用于自定义基座，正式发布需相应授权。加密 UTS 按 DCloud 当前规则使用云端传统打包，不承诺安心或离线打包可用。
• 示例只显示结果状态，不打印用户身份或 TOP 凭据，不执行下单/支付；它的接口导入来源必须是市场安装的本插件。
• 插件更新仍由市场安装更新；宿主安全图、签名及业务服务端配置由使用者维护。

隐私与权限

插件不向作者服务器发送授权数据，也不提供额外读取 UTDid 的 API。百川及其安全、网络、登录等组件可能处理设备/应用信息、SDK 会话、公开资料和授权凭据，宿主必须按实际 SDK 清单向用户告知。不能宣称使用百川就完全不采集数据。

Android SDK 原始依赖包含网络、存储、设备状态等声明，个别内嵌组件还声明相机/音频/日历等权限；最终是否合入与宿主模块、构建有关，应检查最终 APK，不能机械照抄作者测试包的权限。TOP 小窗口不要求悬浮窗权限或开启无障碍服务。iOS 查询及回跳 scheme 不等于系统授权弹窗。SDK 隐私前网络和全量落盘审计尚未完整覆盖，宿主应按实际使用能力补充隐私审核。

官方参考

• DCloud uni_modules 安装与发布
• UTS 发布与授权规则
• 百川旗舰版版本与接入入口
• Android 原生资源
• iOS 原生资源