更新记录

1.0.0（2026-09-16）

首个正式版本：交易主链路与登录授权在 Android / iOS 双端跑通，同一份代码同时支持 uni-app x 与经典 uni-app（Vue）。完整接口清单见 readme 的「API 列表」。

• 交易链路：setup / openByUrl / openByCode / openByCodeOld / openItemDetail / openShop / buildTradeContext
• 登录授权：login / logout / topAuth / isLogin / getLoginUserInfo / getInteractiveTask
• 诊断与配置：getSecurityImageInfo / isTaobaoInstalled / isTmallInstalled / handleOpenURL / setLogEnabled / setNativeDebugEnabled / setAnalysisToolEnabled / setTriverProxyConfig
• iOS：本地二进制集成（不依赖远程 Pod），随包为 cloud-lite profile。openByCode、openByCodeOld、getInteractiveTask、buildTradeContext 在 iOS 返回 9001999，属预期边界——直播链路因此仅 Android 可用
• 安装后必做：替换包内示例安全图与示例 AppKey tbopen35308421，否则 setup() 必然失败

平台兼容性

uni-app(5.24)

uni-app x(5.24)

hans-ali-bc

阿里百川电商 SDK 的 UTS 封装（APP），支持交易主链路与直播链路。同一份代码同时适用于 uni-app x 与经典 uni-app（Vue）。

平台支持

两个宿主只有一处使用差异：经典 uni-app 必须在 App.vue 里自行转发 openURL 回跳，uni-app x 则由插件内的 UTSiOSHookProxy 自动接管。见「经典 uni-app（Vue）宿主：必须转发 openURL 回跳」。

⚠️ 安装后第一件事：替换包内示例安全图与 AppKey

插件目录里自带示例安全图（utssdk/app-ios/Resources/yw_1222_baichuan.jpg、utssdk/app-android/res/drawable/yw_1222_baichuan.jpg 与 yw_1222.jpg），utssdk/app-ios/Info.plist 里的回跳 scheme 也是作者的 tbopen35308421。这两样都绑在作者的百川账号上，不换掉就一定跑不起来：

• 安全图：(appKey, 包名, 签名证书) 三元组封在图中。用作者的图做身份校验必然失败——Android 原生码 125、iOS 原生码 100102，setup() 直接返回 9001004。
  • Android：删掉 utssdk/app-android/res/drawable/ 下的两张图，改由你自己的项目侧 nativeResources/android/res/drawable/ 提供（见「前置配置 → Android」）。包里留着同名资源会重复打包，届时用哪一张没有保证。
  • iOS：用你自己的图覆盖 utssdk/app-ios/Resources/ 下的同名文件（见「前置配置 → iOS」）。
• URL Scheme：把 utssdk/app-ios/Info.plist 里的 tbopen35308421 改成 tbopen<你的AppKey>。不改的话淘宝 App 授权后回跳不回你的应用，login 固定失败并报 AlibabaAuthSDK 错误 1003。

安全图需要到百川开放平台后台重新生成，三元组（AppKey / 包名 / 签名证书）必须与你的应用完全一致。不确定包里这张图的实际内容时，用 getSecurityImageInfo() 先验一下（见下）。

前置配置

Android

1. 先删掉插件自带的两张示例图：uni_modules/hans-ali-bc/utssdk/app-android/res/drawable/yw_1222_baichuan.jpg 与 yw_1222.jpg（见开头的「安装后第一件事」）
2. 把你自己的安全图放到项目侧的 nativeResources/android/res/drawable/
3. 文件名需与百川后台的 authCode 对应（如 yw_1222_baichuan.jpg）
4. 在 manifest.json 中关闭资源名优化。云打包默认开启资源名混淆，会重命名这张图，SDK 按文件名 yw_1222 就找不到了（表现为初始化失败、原生码 125）。两种宿主的路径不同：
   • uni-app x：app-android.distribute.enableResourceOptimizations = false
   • 经典 uni-app：app-plus.distribute.android.enableResourceOptimizations = false

iOS

1. 把你自己后台下载的安全图放到 uni_modules/hans-ali-bc/utssdk/app-ios/Resources/，覆盖包内自带的示例图；也可以由项目宿主统一提供，放到 nativeResources/ios/Resources/
2. 文件名必须与运行态 authCode 对应，命名规则是 yw_1222_<authCode>.jpg。如果你拿到的文件名是 yw_1222.jpg 而运行态 authCode 非空，请重命名后再放入工程
3. 运行态 authCode 的读取方式：setLogEnabled(true) 后调用 setup()，失败日志会打印 setup fail security summary，其中的 securityGuardBridgeAuthCode 即为该值；同样的摘要也在 fail 回调的 err.data.diagnostics 里。包内示例图对应的值是 baichuan，你的可能不同，以实际读到的为准
4. 把 utssdk/app-ios/Info.plist 中 CFBundleURLSchemes 的 tbopen35308421 改成 tbopen<你的AppKey>。这是淘宝 App 授权后回跳回本应用的前提，不改则 login 固定失败
5. iOS 侧不会在 applicationDidFinishLaunchingWithOptions 阶段抢跑初始化，而是等宿主视图就绪后由 setup（或前台重试）触发，以避开过早初始化导致的 100102。接入方无需为此做额外处理

iOS SDK 依赖：开箱即用

本插件走本地二进制集成（不走远程 Pod）：utssdk/app-ios/Frameworks/ 与 utssdk/app-ios/Resources/ 内已带齐百川 SDK 与资源，开箱即可编译，你只需要替换安全图（见「前置配置 → iOS」）。

改动过 iOS 的 framework / bundle / plist / 安全图片后，必须重新打 iOS 自定义基座或重新完整打包；普通的「Syncing program files to device」不会刷新这些原生资源。

iOS 能力边界：cloud-lite profile

本插件 iOS 侧是裁剪版（cloud-lite），只保留交易主链路、登录、TOP 授权与 MTop。由此产生以下预期边界——不是待补的缺口：

正因如此，openItemDetail / openShop 这两个便捷入口刻意建在 openByUrl 上而非 openByCode，否则在 iOS 会整条不可用。

安全图诊断：getSecurityImageInfo

初始化身份校验失败时（Android 原生码 125、iOS 100102），先用它确认包内安全图的实际内容，再谈别的—— (appKey, 包名, 签名证书) 三元组都封在这张图里，图缺失、图旧、或与宿主身份不匹配都会在同一处失败：

import { getSecurityImageInfo } from '@/uni_modules/hans-ali-bc'

const info = getSecurityImageInfo()
// { found: true, name: 'yw_1222_baichuan.jpg', path: '…', sizeBytes: 1702,
//   width: 200, height: 200, sha256: '…' }

拿到 sha256 后与已知正确的那张图逐字节比对，能直接区分「图不对」与「图对但签名/包名不匹配」。

客户端安装检测：isTaobaoInstalled / isTmallInstalled

同步返回，用于 openType: 'native' 前判断能否唤起，或按安装情况降级到 H5/下载：

import { isTaobaoInstalled, isTmallInstalled } from '@/uni_modules/hans-ali-bc'

if (isTaobaoInstalled()) {
  openByUrl({ url, showParams: { openType: 'native' } as AliBcShowParams })
}

两端都有前置声明要求，缺了不会报错、只会恒返回 false：

• Android：宿主 AndroidManifest 需要 <queries><package android:name="com.taobao.taobao"/>…</queries>。 Android 11(API 30) 起包可见性默认受限，未声明的包名一律返回 false——那是「看不到」，不是「没装」。本插件已声明淘宝/天猫/淘宝 Lite。
• iOS：宿主 Info.plist 需要 LSApplicationQueriesSchemes 里含 taobao / tmall，否则 canOpenURL 恒为 false。本插件 Info.plist 已声明。

经典 uni-app（Vue）宿主：必须转发 openURL 回跳

uni-app x 在 iOS 侧通过 UTSiOSHookProxy 自动接管回跳；但经典 uni-app（Vue）工程不会触发该 hook，必须由宿主自行接管，否则淘宝授权回跳丢失，login 固定失败并报 AlibabaAuthSDK 错误 1003。

在 App.vue 里读 plus.runtime.arguments 并转给插件：

// App.vue
import { handleOpenURL } from '@/uni_modules/hans-ali-bc'

// #ifdef APP-PLUS
function forwardPlusOpenURL(source) {
  try {
    if (typeof plus === 'undefined' || !plus.runtime) return
    const args = plus.runtime.arguments
    if (!args) return
    console.log('App openURL (' + source + ')', args)
    handleOpenURL(args)
  } catch (e) {
    console.log('App openURL forward failed', e)
  }
}
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    forwardPlusOpenURL('onLaunch')
    if (typeof document !== 'undefined' && document.addEventListener) {
      document.addEventListener('newintent', function() { forwardPlusOpenURL('newintent') }, false)
    }
    // #endif
  },
  onShow() {
    // #ifdef APP-PLUS
    forwardPlusOpenURL('onShow')
    // #endif
  }
}

注意：经典运行时没有 plus.runtime.addEventListener('openURL', ...) 这个 API，只能读 plus.runtime.arguments；而 App 已在后台被 scheme 唤起时该值可能不更新，因此 newintent 与 onShow 两处都要读。

同时确认 URL Scheme 已注册且与你的 AppKey 一致（见开头的「安装后第一件事」）——这是淘宝 App 回跳回本应用所必需的。

Android 侧写同一份代码即可：handleOpenURL 在 Android 是记录型入口，回跳由百川 SDK 经 Activity intent 自行完成，该方法不消费 URL。

安装

1. 通过 HBuilderX 导入插件，或把 hans-ali-bc 目录复制到工程的 uni_modules/ 下
2. 替换安全图、改掉 tbopen35308421（见「安装后第一件事」）——跳过这步，setup() 一定失败
3. 在页面里调用 setup()，成功后再调其它接口（见「使用示例 → 初始化」）
4. 之后只要改动过原生资源（安全图 / framework / bundle / plist），就必须重新打自定义基座或重新完整打包，否则改动不会生效

API 列表

使用示例

初始化

import {
  setup,
  setLogEnabled,
  setNativeDebugEnabled,
  AliBcInitSuccess,
  AliBcFail
} from '@/uni_modules/hans-ali-bc'

// 可选：开启调试日志
setLogEnabled(true)
setNativeDebugEnabled(true)

// 初始化 SDK
setup({
  success: (res: AliBcInitSuccess) => {
    console.log('初始化成功', res.ready, res.isLogin)
    if (res.userInfo) {
      console.log('用户信息', res.userInfo.userId, res.userInfo.userNick)
    }
  },
  fail: (err: AliBcFail) => {
    console.error('初始化失败', err.errCode, err.errMsg)
  }
})

说明：iOS 侧会延迟到宿主视图就绪后才真正初始化百川 SDK（两种宿主一致）；手动调用 setup 仍是推荐入口，重复调用不会重复初始化，只会在 SDK ready 后返回当前状态。

打开商品详情

import {
  openByUrl,
  openByCode,
  OpenByUrlOptions,
  OpenByCodeOptions,
  AliBcTradeSuccess,
  AliBcFail
} from '@/uni_modules/hans-ali-bc'

// 方式一：通过商品 URL 打开
const openByUrlOptions: OpenByUrlOptions = {
  url: 'https://detail.tmall.com/item.htm?id=123456',
  showParams: {
    openType: 'native',    // 'auto' | 'native'
    backUrl: 'alisdk://',
    degradeType: 'h5'      // 'none' | 'h5' | 'download'
  },
  taokeParams: {
    pid: 'mm_xxx_xxx_xxx'
  },
  success: (res: AliBcTradeSuccess) => {
    console.log('唤端成功', res.dispatched, res.dispatchCode)
  },
  fail: (err: AliBcFail) => {
    console.error('唤端失败', err.errCode, err.errMsg)
  }
}

openByUrl(openByUrlOptions)

// 方式二：通过套件 code 打开
const openByCodeOptions: OpenByCodeOptions = {
  code: 'suite://bc.suite.basic/bc.template.detail',
  bizParams: {
    id: '743632141802'
  },
  showParams: {
    openType: 'native',
    backUrl: 'alisdk://',
    degradeType: 'h5'
  },
  success: (res: AliBcTradeSuccess) => {
    console.log('唤端成功', res.dispatched, res.dispatchCode)
  }
}

openByCode(openByCodeOptions)

按 ID 打开商品 / 店铺

只想按 ID 打开时用这两个便捷入口，不必自己拼 URL 或 code。它们内部走的是 openByUrl，所以双端行为一致（openByCode 在 iOS 不可用，建在它上面会让 iOS 整条失效）。

import {
  openItemDetail,
  openShop,
  OpenItemDetailOptions,
  OpenShopOptions,
  AliBcTradeSuccess,
  AliBcFail
} from '@/uni_modules/hans-ali-bc'

// 按商品 ID 打开详情
const itemOptions: OpenItemDetailOptions = {
  itemId: '743632141802',
  showParams: {
    openType: 'native',
    backUrl: 'alisdk://',
    degradeType: 'h5'
  },
  taokeParams: {
    pid: 'mm_xxx_xxx_xxx'
  },
  success: (res: AliBcTradeSuccess) => {
    console.log('唤端成功', res.dispatched, res.dispatchCode)
  },
  fail: (err: AliBcFail) => {
    console.error('打开失败', err.errCode, err.errMsg)
  }
}

openItemDetail(itemOptions)

// 按店铺 ID 打开店铺
const shopOptions: OpenShopOptions = {
  shopId: '123456789',
  showParams: {
    openType: 'native',
    backUrl: 'alisdk://',
    degradeType: 'h5'
  },
  success: (res: AliBcTradeSuccess) => {
    console.log('唤端成功', res.dispatched)
  }
}

openShop(shopOptions)

itemId / shopId 为空时不同步抛错，而是走 fail 回调并返回错误码 9001012。

打开直播间（仅 Android）

直播链路复用 openByCode，而 iOS 侧为 cloud-lite profile（无 Triver 容器），openByCode 会返回 9001999，所以这条链路目前只能在 Android 上跑。

import {
  openByCode,
  OpenByCodeOptions,
  AliBcTradeSuccess
} from '@/uni_modules/hans-ali-bc'

const liveOptions: OpenByCodeOptions = {
  code: 'suite://bc.suite.live/bc.template.live.list',
  bizParams: {
    extParams: {
      id: '610409740620'
    } as UTSJSONObject
  },
  showParams: {
    openType: 'native',
    backUrl: 'alisdk://',
    degradeType: 'h5'
  },
  success: (res: AliBcTradeSuccess) => {
    console.log('打开直播', res.dispatched)
  }
}

openByCode(liveOptions)

登录授权

import {
  login,
  logout,
  isLogin,
  getLoginUserInfo,
  topAuth,
  LoginOptions,
  LogoutOptions,
  TopAuthOptions,
  AliBcLoginSuccess,
  AliBcLogoutSuccess,
  AliBcTopAuthSuccess,
  AliBcUserInfo
} from '@/uni_modules/hans-ali-bc'

// 百川登录
// 注意：授权回跳后百川登录桥会先以 AlibabaAuthSDK 1003 触发 fail，登录态约 1s 内才落定。
// 插件已内置等待后再判定；若你在 fail 里提示重试，建议先用 isLogin() 复核（见「注意事项 6」）。
const loginOptions: LoginOptions = {
  success: (res: AliBcLoginSuccess) => {
    console.log('登录成功', res.userInfo)
  }
}
login(loginOptions)

// 检查登录状态
const loggedIn: boolean = isLogin()
console.log('是否登录:', loggedIn)

// 获取用户信息
const userInfo: AliBcUserInfo | null = getLoginUserInfo()
console.log('用户信息:', userInfo)

// TOP 授权（获取 accessToken）
const topAuthOptions: TopAuthOptions = {
  appName: '你的应用名称',
  appIconUrl: 'https://example.com/icon.png',
  success: (res: AliBcTopAuthSuccess) => {
    console.log('授权成功', res.accessToken, res.expireTime)
  }
}
topAuth(topAuthOptions)

// 退出登录
const logoutOptions: LogoutOptions = {
  success: (res: AliBcLogoutSuccess) => {
    console.log('退出成功', res.loggedIn)
  }
}
logout(logoutOptions)

调试工具

import {
  setLogEnabled,
  getLogEnabled,
  setNativeDebugEnabled,
  getNativeDebugEnabled,
  setAnalysisToolEnabled,
  getAnalysisToolEnabled
} from '@/uni_modules/hans-ali-bc'

// 插件桥日志（UTS 层）
setLogEnabled(true)
const logEnabled: boolean = getLogEnabled()
console.log('插件日志状态:', logEnabled)

// 百川原生日志
setNativeDebugEnabled(true)
const nativeDebugEnabled: boolean = getNativeDebugEnabled()
console.log('原生日志状态:', nativeDebugEnabled)

// 分析工具（Android 浮窗 / iOS 自检入口）
setAnalysisToolEnabled(true)
const analysisEnabled: boolean = getAnalysisToolEnabled()
console.log('分析工具状态:', analysisEnabled)

Triver 代理配置（Android）

import {
  setTriverProxyConfig,
  getTriverProxyConfig,
  AliBcTriverProxyConfig
} from '@/uni_modules/hans-ali-bc'

// 在首次 setup() 前配置，禁用插件默认代理
const proxyConfig: AliBcTriverProxyConfig = {
  navigateMode: 'none',   // 'system' | 'none'
  imageMode: 'none'       // 'simple' | 'none'
}

setTriverProxyConfig(proxyConfig)

const currentConfig: AliBcTriverProxyConfig = getTriverProxyConfig()
console.log('代理配置:', currentConfig)

互动任务（仅 Android）

import {
  getInteractiveTask,
  GetInteractiveTaskOptions,
  AliBcInteractiveTaskSuccess,
  AliBcFail
} from '@/uni_modules/hans-ali-bc'

const taskOptions: GetInteractiveTaskOptions = {
  params: {
    scene: 'default'
  } as UTSJSONObject,
  success: (res: AliBcInteractiveTaskSuccess) => {
    console.log('互动任务', res.total, res.tasks)
  },
  fail: (err: AliBcFail) => {
    console.error('获取失败', err.errCode, err.errMsg)
  }
}

getInteractiveTask(taskOptions)

预构建交易上下文（仅 Android）

import {
  buildTradeContext,
  BuildTradeContextOptions,
  AliBcTradeContextSuccess,
  AliBcFail
} from '@/uni_modules/hans-ali-bc'

const contextOptions: BuildTradeContextOptions = {
  bizParams: {
    id: '743632141802'
  },
  showParams: {
    openType: 'native',
    backUrl: 'alisdk://',
    degradeType: 'h5'
  },
  success: (res: AliBcTradeContextSuccess) => {
    console.log('上下文构建成功', res.prepared, res.debugStatus)
  },
  fail: (err: AliBcFail) => {
    console.error('构建失败', err.errCode, err.errMsg)
  }
}

buildTradeContext(contextOptions)

参数说明

showParams 通用字段

showParams Android 特有字段

showParams iOS 特有字段

taokeParams 字段

bizParams 字段

trackParams 字段

UTSJSONObject | null，透传给百川 SDK 的埋点参数。openByUrl / openByCode / openItemDetail / openShop / buildTradeContext 均支持，双端一致。

openItemDetail / openShop 入参

错误码

注意事项

1. 初始化顺序: 建议页面进入后先调用 setup()，再执行其他操作
2. 安全图片: 必须替换成你自己的（见开头的「安装后第一件事」）——不换则 setup() 必然失败
3. 回调说明: openByUrl/openByCode/openByCodeOld 返回 dispatched 表示百川已受理路由，不代表页面已完全展示
4. 平台差异: openByCodeOld、getInteractiveTask、buildTradeContext 仅 Android 支持；openByCode 在 iOS 上因 cloud-lite 返回 9001999，因此也仅 Android 可用
5. 直播链路: 复用 openByCode()，code 使用 suite://bc.suite.live/...，直播间 id 放到 bizParams.extParams.id。仅 Android 可用（依赖 openByCode）
6. 登录态是异步落定的: 淘宝授权回跳送达后，百川登录桥会先以 AlibabaAuthSDK 错误 1003 触发失败回调，登录态约 1s 内才生效。插件已内置等待（轮询 isLogin()，最多 6s）后再判定，正常接入无需额外处理。但如果你在 fail 回调里做了"失败即提示重试"，建议先用 isLogin() 复核一次再提示——真机实测存在"回调报 1003 而登录实际成功"的情况
7. iOS 回跳转发: uni-app x 自动接管；经典 uni-app（Vue）必须由宿主转发，否则回跳丢失、login 固定失败。见「前置配置 → 经典 uni-app（Vue）宿主」
8. 依赖 App 的降级行为: 需要淘宝 App 参与的链路（login、openByUrl 的 openType: 'auto'）在未安装淘宝 App 时会降级（登录走 H5 表单、商品页留在 App 内 WebView）。这与插件配置无关，确认 Info.plist 的 LSApplicationQueriesSchemes 已包含 tbopen（注意 iOS 只认前 50 条）