更新记录

1.2.0（2026-08-27）

0.01

1.1.0（2026-08-25）

• 修复【Android】新版 TikTok App 点"继续"后授权结果不回调、误报"用户取消授权"： TikTok 2.x 实际通过 redirect_uri（App Link）返回结果（由 CallbackActivity 的 onCreate/onNewIntent 接收），onActivityResult 仅收到 RESULT_CANCELED+null。 新增 handleActivityResult 统一入口：兼容旧版 setResult 返回 + 新版 redirect 返回 （1200ms 宽限期延迟判定），并修复回调被 clear() 竞态丢失、success/fail 重复触发问题
• 修复【iOS】网页授权拉不起来：presentationAnchor 改为遍历 connectedScenes 取 keyWindow（原 keyWindow 在 iOS 13+ 场景化环境可能返回 nil）
• 【iOS】恢复官方推荐链路：已装 TikTok 优先拉起 App 授权（Universal Link 回跳）， 未装自动降级网页授权（common/tiktokLogin.js 不再强制 iOS 走网页授权）
• 【Android】Manifest queries 增加 CustomTabsService 声明，提升未装 TikTok 时 网页授权降级的可靠性
• common/tiktokLogin.js 恢复 120s 超时兜底，避免授权流程异常时 Promise 永久挂起

平台兼容性

uni-app(3.99)

tiktok-auth

TikTok 授权登录 + 分享 uni-app 插件（Android / iOS），基于 TikTok OpenSDK 官方 Android / iOS SDK（Share Kit） 封装为 UTS 插件，登录与分享合并在同一插件模块内。

• 登录：客户端仅获取 authCode，由你的服务端用 authCode + codeVerifier + client_secret 换取 access_token，符合 TikTok OAuth2 PKCE 流程。
• 分享：将图片 / 视频分享到 TikTok（支持普通发布与 Green Screen 绿幕模式）。TikTok 只能读取系统相册 / MediaStore 中的媒体，插件原生层会先把媒体保存到相册，再拉起 TikTok。

适用于 uni-app（vue2 / vue3）App 端。不支持 H5、小程序、鸿蒙。

一、功能特性

• ✅ 登录：已安装 TikTok App → 拉起 App 原生授权，结果经原生回调 + App 生命周期钩子 + JS 兜底三重通道返回；未安装 → 直接提示"未安装 TikTok"，不做网页授权降级
• ✅ 分享（v1.4.0 新增）：Android 拉起 TikTok 发布页（SystemShareActivity），iOS 以 Universal Link 拉起 TikTok 分享；支持多图（1~35 张）、多视频（≤12 个、3s~10min、mp4）、绿幕模式
• ✅ 媒体自动预处理：本地绝对路径（兼容 file:// 前缀）或远程 https:// URL 均可，原生层自动下载 / 写入系统相册（iOS PHPhotoLibrary）/ MediaStore（Android），再发起分享
• ✅ 分享结果回调：原生 completion → UTS 钩子 → App.vue 从 plus.runtime.arguments 兜底，幂等去重；冷启动被 TikTok 回跳拉起也能取回结果
• ✅ 内置 PKCE（code_verifier 自动生成并在冷启动回跳时持久化恢复）
• ✅ 支持自定义 scope / language / redirectUri
• ✅ Android queries 已声明 TikTok 包名；iOS LSApplicationQueriesSchemes 已声明；iOS 已内置 Photos.framework 与相册写入权限说明

二、环境要求

⚠️ UTS 原生代码改动后，必须重新制作自定义基座或重新云打包才能生效，热重载不更新原生层。

三、TikTok 开发者后台配置（必做）

在使用前，需到 TikTok for Developers 完成：

1. 创建 App，获取 Client Key（即 clientKey）。
2. 配置 Redirect URL（redirect_uri）：例如 https://code.xxx.com，需与代码中传入的 redirectUri 完全一致（登录与分享共用）。
3. 配置 Android 包名（com.xxx.xxx）与 签名 SHA256 指纹。
4. 配置 iOS Bundle ID 与 URL Scheme（值为你的 clientKey）。
5. 申请所需 Scopes（如 user.info.basic、user.info.profile）。
6. 开启 Share Kit 能力（v1.4.0 分享必需）：在 App 的 Products / Share Kit 处申请开启，使用与登录同一个 Client Key。iOS 分享回跳与登录共用 Universal Link（apple-app-site-association 已部署则无需额外配置）。

四、插件配置（接入必做）

Android

插件 AndroidManifest.xml 已注册一个用于拦截授权/分享回跳的 TikTokAuthCallbackActivity，其 intent-filter 拦截的 host 为：

android:host="https://your-domain.com/callback"

⚠️ 上架前的必改项：示例中的 host 为作者演示域名。你需将两处对齐：

1. 把上表中的 host 改成你自己的 redirect_uri 域名（且 intent-filter 内 data 不要写 path，Android 12+ 才执行 App Links 自动验证）。
2. 代码中 tiktokLogin({ redirectUri }) 传入的 redirectUri 必须与该 host 同域。
3. 该域名需在 TikTok 后台登记的 Redirect URL 内，并做 Apple/Google 的 App Links / Universal Link 托管验证（assetlinks.json / apple-app-site-association）。

Android 分享还需：设备已安装 TikTok、分享时传入 clientKey、分享媒体已可被 MediaStore 读取（插件自动处理）。

iOS

插件 info.plist 使用占位符 YOUR_TIKTOK_CLIENT_KEY，打包/上架前必须替换成你自己的 Client Key（两处：SDK 读取的 TikTokClientKey 与回调 CFBundleURLSchemes，二者必须一致）：

<key>TikTokClientKey</key>
<string>YOUR_TIKTOK_CLIENT_KEY</string>

<!-- 授权回调 URL Scheme：必须为你的 Client Key -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_TIKTOK_CLIENT_KEY</string>
    </array>
  </dict>
</array>

<!-- 用于检测 TikTok App 是否安装 -->
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>snssdk1233</string>
  <string>snssdk1180</string>
  <string>tiktokopensdk</string>
</array>

<!-- 分享：把媒体"保存到相册"的权限说明（v1.4.0 起内置，仅 Add-only 写入权限） -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>需要将视频/图片保存到系统相册，以便分享到 TikTok</string>

⚠️ 一键替换：仓库根目录 scripts/replace_tiktok_key.sh 可一次性替换 iOS key 与 Android 回跳 host：

bash scripts/replace_tiktok_key.sh <你的ClientKey> <你的redirect域名>
# 例：bash scripts/replace_tiktok_key.sh axxxxxxxxxx code.example.com

若不替换，所有安装包会共用同一 Scheme 导致冲突、且授权校验失败。替换后请勿将含真实 key 的文件提交到公开仓库。

iOS Photos.framework 已写入插件 config.json 的 frameworks，无需手动添加；App Store 审核时相册权限按 "Add photos only"（仅添加）声明。

域名托管验证配置（App Links / Universal Link）

回调域名（如 https://code.example.com）若要被 Android / iOS 系统识别为合法的 App Links / Universal Link 回跳地址，必须在该域名下托管校验文件，向系统证明"这个域名归你的 App 所有"。否则 Android 12+ 会用浏览器打开回调页、iOS 不会以 Universal Link 形式回跳，导致登录/分享结果拿不到。

这些文件部署在你的服务器 / CDN 上，与 HBuilderX 工程代码无直接关系；但代码中 redirectUri 与插件 host 必须指向这个已验证的域名。

1. Android：Digital Asset Links（assetlinks.json）

在回调域名根路径或 .well-known 下放置 assetlinks.json：

https://code.example.com/.well-known/assetlinks.json

文件内容（把 sha256_cert_fingerprints 换成你签名证书的 SHA256 指纹，package_name 换成你的 Android 包名）：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.yourapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

• 获取 SHA256 指纹：

  keytool -list -v -keystore your.keystore -alias your_alias
  # 复制输出中 "SHA256:" 那一行，标准格式为冒号分隔的大写十六进制

• 文件必须 HTTPS 可访问、Content-Type 为 application/json、无需登录 / 不能有 301 跳转到 www、正文无多余 BOM。

• 在线校验：

  https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://code.example.com&relation=delegate_permission/common.handle_all_urls

  返回中 debugString 无 ERROR 即验证通过。

2. iOS：Universal Links（apple-app-site-association）

在回调域名根路径或 .well-known 下放置不带扩展名的 apple-app-site-association：

https://code.example.com/apple-app-site-association
https://code.example.com/.well-known/apple-app-site-association

文件内容（appID 为 TeamID.BundleID，paths 放行回跳路径）：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.yourapp",
        "paths": ["/callback/*", "/share/*", "*"]
      }
    ]
  }
}

• appID = Apple Developer 后台的 Team ID + . + App Bundle ID。
• paths 写你回调实际使用的路径；* 表示全路径放行（也可精简为 /callback/*）。
• 文件必须 HTTPS、Content-Type 为 application/json（iOS 会请求无扩展名的该文件名），且不要让 CDN/网关返回 gzip 却不声明 Content-Encoding，否则校验失败。
• 验证：iOS 设备安装 App 后系统会在首次启动时静默拉取；可在 Safari 长按该域名链接选择"在 App 中打开"做连通性测试，或检查设备控制台是否有 SWC / AppLinks 相关日志。

3. 与 TikTok 后台的联动

• 同一个回调域名（如 https://code.example.com）需同时在 TikTok 开发者后台的 Redirect URL 中登记，并完成上面的 App Links / Universal Link 托管验证。
• Android：assetlinks.json 未通过验证时，Android 12+ 不会自动跳回 App，而是用浏览器打开回调页 → 授权/分享结果回跳失败。
• iOS：apple-app-site-association 缺失时，TikTokAuthCallbackActivity 无法以 Universal Link 回跳，结果同样收不到。
• 登录与分享共用同一个回调域名，上述验证只需针对该域名做一次，无需分别为两者托管两份文件。

五、安装

方式一：通过 HBuilderX 插件市场导入 uni_modules/tiktok-auth。

方式二：手动将 tiktok-auth 目录放到项目 uni_modules/ 下。

六、使用方式

1. 引入

import { tiktokLogin, tiktokShare } from '@/uni_modules/tiktok-auth'
// 推荐：分享走 Promise 封装（含超时/冷启动兜底）
import { tiktokShare, consumePendingShareResult } from '@/common/tiktokShare.js'

上面的 @/common/tiktokShare.js 是项目内的 Promise 封装（插件本身只导出回调式 tiktokShare）。建议把它放到的你项目 common/ 目录下，源码如下：

/**
 * TikTok 分享封装（依赖 UTS 插件 tiktok-auth，双端通用）
 *
 * 用法：
 *   import { tiktokShare } from '@/common/tiktokShare.js'
 *   try {
 *     const res = await tiktokShare({
 *       mediaType: 'video',           // 'video' | 'image'
 *       paths: ['https://cdn.xxx/a.mp4'],  // 本地绝对路径 或 远程 https URL
 *       greenScreen: false,           // 可选：绿幕模式（仅单媒体）
 *       clientKey: 'sbawwsw3d3nxrgc4b3'   // Android 必传；iOS 走 Info.plist 可留空
 *     })
 *     // res.code === 200：{ shareState, requestId }；shareState 20015/20016 = 已存草稿
 *   } catch (e) {
 *     // e.code === -1 用户取消；-2 失败/未安装；401 参数错误
 *   }
 *
 * 说明：
 * - 分享媒体会先由原生层保存到系统相册（iOS PHPhotoLibrary / Android MediaStore），
 *   TikTok 只能读取相册/公共存储中的资源；远程 URL 原生层自动下载。
 * - 媒体限制：图片 1~35 张；视频最多 12 个、3s~10min、mp4；绿幕仅 1 个媒体。
 * - 未安装 TikTok 直接抛错（errMsg：未安装 TikTok），不做商店/网页兜底。
 * - iOS 首次会弹"保存到相册"权限申请（NSPhotoLibraryAddUsageDescription）。
 */
import * as tiktokAuthModule from '@/uni_modules/tiktok-auth'
const tiktokAuthShare = tiktokAuthModule.tiktokShare || tiktokAuthModule.TikTokShare

/**
 * 发起 TikTok 分享
 * @param {Object} options
 * @param {String} options.mediaType  'video' | 'image'
 * @param {String[]} options.paths    媒体路径数组（本地绝对路径或 https URL，全同类型）
 * @param {String}  [options.clientKey]   Android 必传；iOS 走 Info.plist 可留空
 * @param {Boolean} [options.greenScreen] 绿幕模式（仅单媒体），默认 false
 * @param {String}  [options.state]        透传标识，原样回传
 * @param {Number}  [options.timeout]      超时毫秒，默认 120000
 * @returns {Promise<{code:number, shareState?:number, requestId?:string, state?:string, message?:string}>}
 */
export function tiktokShare(options = {}) {
    return new Promise((resolve, reject) => {
        const timeoutMs = options.timeout || 120000
        let settled = false
        const finish = (fn, arg) => {
            if (settled) return
            settled = true
            clearTimeout(timer)
            fn(arg)
        }
        const timer = setTimeout(() => {
            finish(reject, { code: -3, message: '分享超时，请重试' })
        }, timeoutMs)

        tiktokAuthShare({
            clientKey: options.clientKey || 'sbawwsw3d3nxrgc4b3',
            mediaType: options.mediaType || 'video',
            paths: options.paths || [],
            greenScreen: !!options.greenScreen,
            state: options.state || '',
            success: (res) => {
                finish(resolve, {
                    code: 200,
                    shareState: res.shareState,
                    requestId: res.requestId,
                    state: res.state
                })
            },
            fail: (err) => {
                finish(reject, { code: err.errCode || -2, message: err.errMsg || '分享失败' })
            }
        })
    })
}

/**
 * 冷启动兜底读取：App 在分享期间被系统杀死、分享完成后由 TikTok 回跳拉起时，
 * App.vue 会把结果缓存在 uni._tiktokSharePending 并广播 'tiktok:share:result'。
 * 业务页 onShow 可调用本方法取回未消费的结果（取完即清），
 * 避免冷启动场景下 Promise 已随页面销毁、用户看不到分享结果。
 * @returns {Object|null} { success, shareState|errCode, ... }
 */
export function consumePendingShareResult() {
    try {
        const pending = uni._tiktokSharePending
        if (pending) {
            uni._tiktokSharePending = null
            return pending
        }
    } catch (e) { }
    return null
}

2. 发起授权登录

// 注意：tiktokLogin 是【回调式】API（返回 void，非 Promise），不能用 .then
tiktokLogin({
  clientKey: '你的ClientKey',
  // Android 端 redirectUri 必须与插件 AndroidManifest 的 CallbackActivity host 同域
  // iOS 端 clientKey 必须与 info.plist 的 URL Scheme 一致
  redirectUri: 'https://your-domain.com/callback',
  scope: 'user.info.basic,user.info.profile',
  language: 'en',
  success: (res) => {
    console.log('authCode', res.authCode)
    console.log('codeVerifier', res.codeVerifier)
    // 把 authCode + codeVerifier 发到你后端，换取 access_token
    uni.request({
      url: 'https://your-server.com/api/tiktok/exchange',
      method: 'POST',
      data: { authCode: res.authCode, codeVerifier: res.codeVerifier }
    })
  },
  fail: (err) => {
    // err.errCode: -1 用户取消；-2 失败/未安装 TikTok；401 参数错误
    uni.showToast({ title: err.errMsg || '授权失败', icon: 'none' })
  }
})

自 v1.3.0 起不再提供网页授权兜底：未安装 TikTok 时两端直接回调"未安装 TikTok，请先安装 TikTok 应用后重试"，autoAuthDisabled 参数已无效（原生恒走 App 授权）。

3. 分享到 TikTok

// 回调式
tiktokShare({
  clientKey: '你的ClientKey',      // Android 必传；iOS 走 Info.plist 可留空
  mediaType: 'video',             // 'video' | 'image'，paths 内媒体必须全部同类型
  paths: [
    'https://cdn.yours.com/promo/a.mp4',  // 远程 https URL（自动下载）
    '/storage/emulated/0/.../b.mp4'       // 或本地绝对路径（兼容 file:// 前缀）
  ],
  greenScreen: false,             // 可选：true=绿幕模式（仅支持 1 个媒体）
  state: 'share_001',             // 可选：透传标识，回调原样返回
  success: (res) => {
    // res.shareState: 20000 分享成功；20015/20016 已保存草稿
    console.log('shareState', res.shareState, 'requestId', res.requestId)
  },
  fail: (err) => {
    // err.errCode: -1 用户取消；-2 失败/未安装；401 参数错误
    uni.showToast({ title: err.errMsg || '分享失败', icon: 'none' })
  }
})

// 或 Promise 式（推荐，common/tiktokShare.js）
const res = await tiktokShare({
  mediaType: 'video',
  paths: ['https://cdn.yours.com/promo/a.mp4']
})
// res.code === 200 → 成功；否则 throw { code, message }（-1 取消 / -2 失败 / -3 超时）

说明：

• 媒体会先由原生层保存到系统相册（iOS）/ MediaStore（Android），TikTok 只能读取相册中的资源；期间 App 会退到后台，属正常现象。
• iOS 首次分享会弹"允许添加到照片"授权（仅写入，不读取相册）。
• 媒体限制：图片 1~35 张；视频最多 12 个、单个 3s~10min、仅 mp4；绿幕模式仅支持 1 个媒体。
• 未安装 TikTok 直接回调"未安装"，不弹商店/浏览器引导。
• 冷启动兜底：若 App 在分享期间被杀，结果由 App.vue 缓存并广播 tiktok:share:result，业务页在 onShow 调 consumePendingShareResult() 取回。

七、错误码

登录 / 分享通用

分享 shareState（原生状态码）

八、常见问题（FAQ）

Q1：点击授权后无反应 / 拉不起 TikTok？

• 检查 TikTok App 是否安装；未安装不会降级网页授权，而是直接提示未安装。
• 确认 clientKey 与后台、包名、签名一致（Android 端签名指纹不匹配会导致 SDK 判 TikTok「未安装」）。
• UTS 原生改动后是否重新制作了自定义基座/云打包。

Q2：登录返回 -2 但无授权页弹出？

• 多为 clientKey / 包名 / 签名 / Bundle Id 与 TikTok 后台不匹配，或 scope 含后台未申请的权限。
• 查看原生日志 TikTokAuth 标签，会打印 authError 具体值（如 invalid_client、E10001）。

Q3：分享点了没反应 / 一闪而过？

• 确认已安装 TikTok 且版本支持分享（Android 需 TikTok ≥ 某版本支持 SystemShareActivity，iOS 同理）。
• 确认 TikTok 后台已开启 Share Kit 能力，且用同一 Client Key 发包。
• 媒体限制是否满足（视频 ≤12 个、3s~10min、mp4；图片 1~35 张；绿幕仅 1 个媒体）；远程 URL 需可公网直连下载。
• iOS 首次分享需授权"添加到照片"，拒绝后分享无法进行，需到系统设置开启。

Q4：分享完成/取消后没有回到 App？

• Android：TikTok 会显式拉起插件注册的 TikTokAuthCallbackActivity（带分享结果），无需配置；若被杀进程则冷启动回跳，业务页 onShow 调 consumePendingShareResult() 取回。
• iOS：分享回跳是 Universal Link，redirect_uri（默认 https://code.xxx.com）必须已在 apple-app-site-association 放行（与登录共用域名即可，插件以 share_state/from_platform=tiktoksharesdk 参数区分登录与分享回跳）。

Q5：iOS 提示 canOpenURL 被拒 / 检测不到 TikTok？

• 已在 info.plist 声明 LSApplicationQueriesSchemes，无需额外处理；若自定义渠道版 TikTok，可补充对应 scheme。

九、兼容性与限制

• 仅支持 uni-app App 端（Android / iOS），不支持 H5、各平台小程序、鸿蒙。
• Android 最低 API 23；iOS 最低 12.0，仅 arm64 架构。
• 登录依赖：androidx.browser:browser:1.3.0、com.google.code.gson:gson:2.9.1（已写入 config.json，自动集成）。
• iOS 分享依赖：Photos.framework（已写入 config.json frameworks）；需 NSPhotoLibraryAddUsageDescription（已内置）。
• 分享媒体限制：图片 1~35 张；视频最多 12 个、单个 3s~10min、仅 mp4（含远程 URL 下载后校验）；绿幕模式仅支持 1 个媒体；媒体须为系统相册可读格式。
• 实现说明：iOS 分享为官方 Share Kit 源码移植（同 OpenSDK v2.3.1 家族）；Android 分享因官方 share AAR 未随 OpenSDK 提供，按 ShareRequest Bundle 协议（TYPE_SHARE_REQUEST）自研实现拉起发布页。

十、隐私与权限说明

• 登录：仅用于 TikTok 授权登录，获取用户公开资料（头像、昵称、open_id）；客户端仅持有 auth_code，由你的服务端换取 access_token，插件不采集、不上传任何其他数据。
• 分享：仅在用户主动发起分享时，将所选媒体保存到系统相册（iOS PHPhotoLibraryAdd / Android MediaStore）以完成分享，不读取相册既有内容、不读取任何用户隐私数据；媒体来源为用户传入的本地文件或远程 URL。
• iOS 相册权限为 Add-only（仅添加），上架审核按 "Add photos only" 声明；不涉及广告、无其他系统权限申请。

十一、版本记录

• v1.4.0：新增 TikTok 分享（双端），与登录合并于同一插件；媒体先存相册/MediaStore 再拉起分享；结果回调三重保险 + 冷启动兜底；iOS 内置 Photos framework 与相册权限说明。
• v1.3.0：移除网页授权兜底，未安装 TikTok 直接提示，登录行为双端统一。
• v1.1.0：基于官方 OpenSDK 封装 UTS 插件；支持 App 原生授权；修复 Android 新版 TikTok 点"继续"误报取消、iOS 授权页拉不起等问题；内置 PKCE 与冷启动 codeVerifier 恢复。
• v1.0.0：首个版本。

十二、参考资料

• TikTok Login Kit 文档
• TikTok Share Kit iOS Quickstart
• TikTok Share Kit Android Quickstart
• TikTok OpenSDK Android
• TikTok OpenSDK iOS