更新记录

0.0.1（2026-09-16）

初始化TapTap SDK，支持登录/合规认证/排行榜/REP

平台兼容性

uni-app(5.01)

其他

TapTap SDK（UTS 插件）

基于 TapTap SDK v4 原生 SDK 封装的 uni-app UTS 插件，提供以下能力：

• TapTap 登录：授权登录、登录态检查、获取用户信息、退出登录
• 合规认证：实名认证、防沉迷（时段/时长/年龄限制）事件监听
• 排行榜：分数上报、打开原生排行榜页面、拉取榜单数据
• TapTap REP：打开 REP 运营页面（如每日签到、活动页等）

平台支持

仅支持在真机运行，标准基座不包含本插件原生 Framework，调试请制作自定义基座。

接入准备

1. 在 TapTap 开发者中心 创建游戏，获取 Client ID 和 Client Token，并在后台完成排行榜等服务配置。
2. 将本插件导入项目的 uni_modules 目录。
3. 配置 URL Scheme（必做）：TapTap 授权完成后需通过 URL Scheme 回跳 App。打开插件目录下的 utssdk/app-ios/Info.plist，将 CFBundleURLSchemes 中的值修改为 tt + 您自己的 Client ID：

<key>CFBundleURLSchemes</key>
<array>
    <!-- 格式：tt + Client ID，例如 Client ID 为 eqxdzy12dsaf1oilebvb，则为 tteqxdzy12dsaf1oilebvb -->
    <string>tt替换为您的ClientID</string>
</array>

LSApplicationQueriesSchemes（跳转 TapTap App）及登录回跳的 openURL 生命周期处理插件已内置，无需额外配置。

4. 制作自定义调试基座或提交云打包后即可使用。

通用约定

引入方式

import {
  initSDK,
  login,
  checkLoginStatus,
  getCurrentUser,
  logout,
  registerComplianceCallback,
  startCompliance,
  exitCompliance,
  registerLeaderboardCallback,
  submitScores,
  loadLeaderboardScores,
  loadMyLeaderboardScore,
  loadCenteredScores,
  openLeaderboard,
  openRep,
  setDebugMode
} from '@/uni_modules/tap-sdk'

三种调用模式

插件 API 均返回 Promise，但根据原生 SDK 的特性分为三类：

1. 同步型：Promise resolve 的即为真实结果。 如 checkLoginStatus、getCurrentUser、logout、startCompliance、exitCompliance、openLeaderboard、openRep。
2. 单次异步回调型：Promise 立即 resolve（仅表示调用已发起），真实结果通过第二个参数 onResult 回调返回一次。 如 initSDK、login、submitScores、loadLeaderboardScores、loadMyLeaderboardScore、loadCenteredScores。
3. 持久事件回调型：首次回调 { code: 'success' } 表示注册成功，此后业务事件持续通过 onEvent 回调。 如 registerComplianceCallback、registerLeaderboardCallback。

统一返回码

一、初始化

应用启动时必须先初始化 SDK，初始化成功后才能调用其他接口。

initSDK(options, onResult) 为单次异步回调型，真实初始化结果通过 onResult 返回：

initSDK({
  clientId: '您的Client ID',
  clientToken: '您的Client Token',
  region: 'CN',                 // 可选，CN（国内，默认）/ OVERSEAS（海外）
  enableLog: true,              // 可选，是否开启 SDK 原生日志，默认 false
  screenOrientation: 'portrait' // 可选，portrait 竖屏（默认）/ landscape 横屏
}, (res) => {
  if (res.code === 'success') {
    console.log('TapSDK 初始化成功')
  } else {
    console.error('初始化失败', res.message)
  }
})

调试日志开关：可在任何时候动态开关原生侧日志，无需重新云打包：

setDebugMode({ enable: true })

二、TapTap 登录

发起登录

拉起 TapTap 授权（已安装 TapTap App 时跳转 App 授权，否则使用网页授权），授权完成后自动回跳。

login(
  { scopes: ['public_profile'] }, // 可选，授权范围，默认使用基础权限
  (res) => {
    if (res.code === 'success') {
      // 登录成功
      const user = res.user
      // user.openId    —— TapTap 用户唯一标识，建议作为业务账号 ID / 合规认证 userId
      // user.unionId   —— 开放平台 unionId
      // user.nickname  —— 昵称
      // user.avatar    —— 头像 URL
    } else if (res.code === 'cancel') {
      // 用户取消授权
    } else {
      // res.code === 'error'，res.message 为错误信息
    }
  }
)

检查登录状态

同步返回本地是否已存在有效登录态：

const res = await checkLoginStatus({})
if (res.isLoggedIn) {
  // 已登录
}

获取当前登录用户

try {
  const res = await getCurrentUser({})
  // res.user: { openId, unionId, nickname, avatar }
} catch (e) {
  // 未登录
}

退出登录

await logout({})

建议：进入需要登录的功能（如排行榜）前先调用 checkLoginStatus，未登录时先 login，成功后再继续业务流程。

三、合规认证（实名防沉迷）

合规认证需在登录成功后进行，建议使用当前玩家的 openId 作为 userId。

1. 注册合规事件回调（持久监听）

registerComplianceCallback({}, (event) => {
  // 首次回调为 { code: 'success' } 表示注册成功，之后为合规业务事件
  switch (event.code) {
    case 500:
      // 玩家不受限制，正常进入游戏
      break
    case 1000:
      // 退出防沉迷（需退出游戏 / 回到登录前状态）
      break
    case 1001:
      // 用户点击切换账号（应退出登录并重新走登录流程）
      break
    case 1030:
      // 当前时段限制，无法进行游戏
      break
    case 1050:
      // 当日可玩时长已用完
      break
    case 1100:
      // 年龄限制，无法进入游戏
      break
    case 1200:
      // 网络错误，可提示玩家稍后重试
      break
    case 9002:
      // 实名认证窗口被用户关闭（需重新引导认证）
      break
  }
})

2. 启动合规认证

注册回调成功后调用，SDK 会根据需要弹出实名认证窗口，并通过上面的事件回调通知结果：

await startCompliance({
  userId: openId // 必传，建议传 TapTap openId
})

3. 退出合规

退出登录时同步退出防沉迷（logout 不会自动调用，需业务自行处理）：

await exitCompliance({})

其他辅助接口

await getAgeRange({})       // 年龄段：-1 未知 / 0 儿童 / 8 少年 / 16 青年 / 18 成人
await getRemainingTime({})  // 当日剩余可玩时长（秒）

四、排行榜

使用前请在 TapTap 开发者后台创建排行榜并记录排行榜 ID。

上报分数

单次异步回调，支持单条或批量上报，每次最多 5 条，超过请分批调用：

// 批量格式
submitScores({
  scores: [
    { leaderboardId: '排行榜ID1', score: 100 },
    { leaderboardId: '排行榜ID2', score: 9527 }
  ]
}, (res) => {
  if (res.code === 'success') {
    // 上报成功
  } else {
    // res.message
  }
})

// 单条格式
submitScores({ leaderboardId: '排行榜ID', score: 100 }, (res) => {})

打开原生排行榜页面

await openLeaderboard({
  leaderboardId: '排行榜ID',
  collection: 'public' // 可选，public 全服榜（默认）/ friends 好友榜
})

拉取榜单数据

// 1. 排行榜分数列表（分页）
loadLeaderboardScores({
  leaderboardId: '排行榜ID',
  collection: 'public', // public / friends
  nextPage: '',         // 可选，首页传空，翻页使用上次返回的 nextPage
  periodToken: ''       // 可选，榜单周期标识，默认当前周期
}, (res) => {
  // res.code === 'success' 时，res 中包含榜单列表及 nextPage
})

// 2. 当前玩家在某榜单中的分数与排名
loadMyLeaderboardScore({
  leaderboardId: '排行榜ID',
  collection: 'public'
}, (res) => {})

// 3. 以当前玩家为中心的榜单
loadCenteredScores({
  leaderboardId: '排行榜ID',
  collection: 'public',
  maxCount: 10 // 可选，返回条数，默认 10
}, (res) => {})

排行榜事件回调

用于接收原生排行榜页面内的异常事件（如未登录等）：

registerLeaderboardCallback({}, (event) => {
  // event: { code, message }
})

五、TapTap REP

打开由 TapTap REP 运营平台（rep.taptap.cn）生成的活动页面，例如每日签到、福利活动等。

try {
  await openRep({
    url: 'https://tap.cn/xxxxxxxx' // REP 平台生成的完整活动链接
  })
} catch (e) {
  console.error('打开 REP 页面失败', e.message)
}

完整接入流程示例

import {
  initSDK, login, checkLoginStatus, getCurrentUser,
  registerComplianceCallback, startCompliance,
  submitScores, openLeaderboard, openRep
} from '@/uni_modules/tap-sdk'

// 1. 初始化
initSDK({
  clientId: '您的Client ID',
  clientToken: '您的Client Token',
  region: 'CN',
  enableLog: true
}, async (res) => {
  if (res.code !== 'success') return

  // 2. 检查登录态，未登录则拉起登录
  const status = await checkLoginStatus({})
  if (!status.isLoggedIn) {
    login({}, (loginRes) => {
      if (loginRes.code !== 'success') return // 取消或失败
      startAntiAddiction(loginRes.user.openId)
    })
  } else {
    const userRes = await getCurrentUser({})
    startAntiAddiction(userRes.user.openId)
  }
})

// 3. 注册合规回调并启动认证
function startAntiAddiction(openId) {
  registerComplianceCallback({}, (event) => {
    if (event.code === 500) {
      // 认证通过，正常进入游戏，之后可上报分数 / 打开排行榜
      submitScores({
        scores: [{ leaderboardId: '排行榜ID', score: 100 }]
      }, () => {})
    }
  })
  startCompliance({ userId: openId })
}

// 4. 打开排行榜
function showLeaderboard(id) {
  openLeaderboard({ leaderboardId: id, collection: 'public' })
}

// 5. 打开 REP 活动页
function showSignActivity(url) {
  openRep({ url })
}

注意事项

1. 插件包含 TapTap SDK 全部原生 Framework（xcframework），仅支持 iOS 12.0+，必须使用云打包或自定义基座运行。
2. 上架前务必将 utssdk/app-ios/Info.plist 中的 URL Scheme 替换为 tt + 您自己的 Client ID，否则授权后无法回跳。
3. initSDK、login、submitScores 等异步接口的真实结果在回调函数中返回，Promise resolve 仅代表调用已发起，请勿在 Promise 后直接读取业务结果。
4. 合规事件回调为持久回调，注册一次即可，注意不要重复注册。
5. 排行榜批量上报单次上限为 5 条。
6. 国内游戏上架均需合规认证，建议在登录成功后、进入游戏主逻辑前完成实名/防沉迷流程。