Skip to main content
Version: v4

iOS SDK 开发指南

本文介绍如何在 iOS 原生项目中接入实名认证和防沉迷服务。

集成前准备​

  1. 参考开发者中心配置创建应用、配置 Bundle ID 与签名证书
  2. 参考功能介绍的准备工作开通合规认证服务
  3. 参考iOS 集成指南完成 TapSDK 基础接入
  4. 参考TapTap 登录 iOS SDK 开发指南完成登录接入

SDK 获取​

CocoaPods​

在 Podfile 中添加：

pod 'TapTapSDK/Compliance', '~> 4.11.0'

执行 pod install，并使用生成的 .xcworkspace 打开工程。

本地文件​

先参考iOS 集成指南和TapTap 登录 iOS SDK 开发指南添加 Core 与登录依赖，再从下载页下载并导入：

  • TapTapComplianceSDK.xcframework
  • TapTapComplianceResource.bundle

添加 xcframework 时将 Embed 设置为 Do Not Embed，并确认 bundle 已加入应用 Target 的 Copy Bundle Resources。

初始化​

合规认证模块可配置是否显示切换账号按钮，以及是否获取年龄段信息：

import TapTapComplianceSDK
import TapTapCoreSDK

let coreOptions = TapTapSdkOptions()
coreOptions.clientId = "your_client_id"
coreOptions.clientToken = "your_client_token"

let complianceOptions = TapTapComplianceOptions()
complianceOptions.showSwitchAccount = true
complianceOptions.useAgeRange = false

TapTapSDK.initWith(coreOptions, otherOptions: [complianceOptions])
配置说明
showSwitchAccount是否显示切换账号按钮，默认为 false。如果游戏支持切换账号，可设置为 true；玩家点击按钮后，SDK 会触发 1001 回调，游戏可根据该回调 code 进行处理
useAgeRange游戏是否需要获取真实年龄段信息，默认为 true。设置为 true 时，使用 Tap 实名需要用户主动授权；设置为 false 时，使用 Tap 实名会进行无 UI 交互的静默授权

切换账号界面

注册回调​

在开始认证前注册回调，并处理所有会影响玩家能否进入游戏的结果：

import TapTapComplianceSDK

extension GameMainController: TapTapComplianceDelegate {
    func complianceCallback(
        with code: TapComplianceResultHandlerCode,
        extra: String?
    ) {
        switch code.rawValue {
        case 500:
            // 认证通过，允许玩家进入游戏
            break
        case 1000, 1001:
            // 退出认证或切换账号，返回登录页
            break
        case 1030, 1050, 1100:
            // 当前玩家不可进入游戏
            break
        case 1200:
            // 检查应用配置和网络，并允许重试
            break
        case 9002:
            // 玩家关闭实名窗口，可重新发起认证
            break
        default:
            break
        }
    }
}

TapTapCompliance.register(self)
回调 code回调类型游戏处理
500LOGIN_SUCCESS玩家未受到限制，允许进入游戏
1000EXITED认证退出或凭证失效，返回登录页
1001SWITCH_ACCOUNT玩家选择切换账号，返回登录页
1030PERIOD_RESTRICT当前时段不可玩，阻止进入游戏
1050DURATION_LIMIT无剩余可玩时长，阻止进入游戏
1100AGE_LIMIT触发开发者中心配置的可玩年龄限制
1200INVALID_CLIENT_OR_NETWORK_ERROR应用配置无效或网络异常
9002REAL_NAME_STOP玩家关闭实名窗口，可重新开始认证

开始认证​

防沉迷开始认证时需传入玩家唯一标识 userIdentifier，建议使用 TapTap 登录 iOS SDK 开发指南中获取的 openId。

玩家唯一标识 userIdentifier 是账号的唯一字符串，长度不能超过 160，只能包含数字、大小写字母、下划线（_）、短横（-）、加号（+）、正斜线（/）、等号（=）、英文句号（.）、英文逗号（,）和英文冒号（:）。

import TapTapComplianceSDK
import TapTapLoginSDK

if let openId = TapTapLogin.getCurrentTapAccount()?.userInfo?.openId {
    TapTapCompliance.startup(openId)
}

不要在前一次认证结果返回前重复调用 startup()。

充值额度限制​

不同年龄段的玩家，充值金额有不同的上限。开发者需在玩家充值前检查是否受限，并在玩家成功充值后上报充值金额，具体流程如下。

检查充值限制​

游戏在收到玩家的充值请求后，调用以下接口检查本次充值行为是否受限。充值金额的单位为分：

import TapTapComplianceSDK

let amount = 100

TapTapCompliance.checkPaymentLimit(amount) { status, title, description in
    if status {
        // 继续支付流程
    }
    // 受限时 SDK 会弹出对应提示窗口，开发者不需要额外处理
} failureHandler: { message in
    // 查询失败，可以继续重试，但建议最多重试三次
}

上报充值金额​

当玩家充值成功后，开发者需调用以下接口上报玩家充值金额。传入金额的单位同样为分：

import TapTapComplianceSDK

let amount = 100

TapTapCompliance.submitPayment(amount) { success in
    // 上报完成
} failureHandler: { message in
    // 上报失败，可以继续重试，但建议最多重试三次
}

不要在支付失败或取消时调用 submitPayment()。

退出认证​

玩家在游戏内退出账号时调用，重置防沉迷状态：

TapTapCompliance.exit()

其他​

获取玩家年龄段​

开发者可调用以下接口获取玩家所处年龄段：

let ageRange = TapTapCompliance.getAgeRange().rawValue

上例中的 ageRange 是一个整数，表示玩家所处年龄段的下限（最低年龄）。

数值含义
-1未知
00 到 7 岁
88 到 15 岁
1616 到 17 岁
18成年玩家

-1 表示“未知”，说明该玩家还未实名或未授予年龄段权限，通常有以下原因：

  1. 在玩家未完成实名时调用该接口。应在收到玩家是否可以进入游戏的回调后（回调 code 为 500、1030 或 1050）再调用
  2. 初始化合规认证模块时将 useAgeRange 设置为 false，需设置为 true
  3. 游戏无版号且在 TapPlay 中运行
  4. 玩家首次进入游戏时，游戏未开启获取年龄段权限；该玩家后续获取年龄段时都会返回 -1

获取剩余时长​

开发者可调用以下接口获取玩家当前剩余时长：

let remainingSeconds = TapTapCompliance.getRemainingTime()

remainingSeconds 为玩家剩余游戏时间，单位为秒。

设置适龄限制​

当应用除了需要满足防沉迷政策外，还需要对玩家年龄进行额外限制时，例如只允许 16 周岁以上的玩家使用，开发者可在开发者中心配置对应的年龄限制。玩家完成实名后，SDK 会先检查玩家是否符合游戏的年龄要求，再根据时长限制规则显示 UI。满足要求时，SDK 会继续进行后续时长业务和回调处理；否则会直接返回 code 为 1100 的年龄限制回调，通知游戏进行处理。

接入验证​

场景预期结果
初始化成功后注册回调并调用 startup()收到明确的合规回调
未实名测试账号开始认证显示实名流程，完成后返回认证结果
成年测试账号认证收到 500，允许进入游戏
未成年人在不可玩时段认证收到限制回调，不能进入游戏
支付前调用 checkPaymentLimit()回调返回是否允许支付
支付成功后调用 submitPayment()收到成功结果
玩家退出账号时调用 exit()收到 1000，游戏返回登录页
真机打包TapTapComplianceResource.bundle 存在，认证 UI 正常显示