跳到主要内容
版本：v4

Android SDK 开发指南

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

集成前准备​

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

SDK 获取​

在 app module 的 build.gradle 中添加：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.11.0'
  implementation 'com.taptap.sdk:tap-login:4.11.0'
  implementation 'com.taptap.sdk:tap-compliance:4.11.0'
}

工程配置​

合规认证模块需要以下权限，SDK 会自动合并到应用的 Manifest：

权限使用目的
android.permission.INTERNET访问合规认证服务
android.permission.ACCESS_NETWORK_STATE判断当前网络连接是否可用

如果项目覆盖了 Manifest 合并结果，请确认最终 APK 中仍包含这些权限。

初始化​

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

import com.taptap.sdk.compliance.option.TapTapComplianceOptions;
import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

TapTapSdkOptions sdkOptions = new TapTapSdkOptions(
        "clientId",
        "clientToken",
        TapTapRegion.CN
);

TapTapComplianceOptions complianceOptions = new TapTapComplianceOptions(
        true,  // 是否显示切换账号按钮
        false  // 是否获取真实年龄段信息
);

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

切换账号界面

注册回调​

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

import androidx.annotation.Nullable;
import com.taptap.sdk.compliance.TapTapCompliance;
import com.taptap.sdk.compliance.TapTapComplianceCallback;
import com.taptap.sdk.compliance.constants.ComplianceMessage;
import java.util.Map;

TapTapCompliance.registerComplianceCallback(new TapTapComplianceCallback() {
    @Override
    public void onComplianceResult(int code, @Nullable Map<String, ?> extra) {
        switch (code) {
            case ComplianceMessage.LOGIN_SUCCESS:
                // 认证通过，允许玩家进入游戏
                break;
            case ComplianceMessage.EXITED:
            case ComplianceMessage.SWITCH_ACCOUNT:
                // 退出认证或切换账号，返回登录页
                break;
            case ComplianceMessage.PERIOD_RESTRICT:
            case ComplianceMessage.DURATION_LIMIT:
            case ComplianceMessage.AGE_LIMIT:
                // 当前玩家不可进入游戏
                break;
            case ComplianceMessage.INVALID_CLIENT_OR_NETWORK_ERROR:
                // 检查应用配置和网络，并允许重试
                break;
            case ComplianceMessage.REAL_NAME_STOP:
                // 玩家关闭实名窗口，可重新发起认证
                break;
            default:
                break;
        }
    }
});
回调 code回调类型游戏处理
500LOGIN_SUCCESS玩家未受到限制，允许进入游戏
1000EXITED认证退出或凭证失效，返回登录页
1001SWITCH_ACCOUNT玩家选择切换账号，返回登录页
1030PERIOD_RESTRICT当前时段不可玩，阻止进入游戏
1050DURATION_LIMIT无剩余可玩时长，阻止进入游戏
1100AGE_LIMIT触发开发者中心配置的可玩年龄限制
1200INVALID_CLIENT_OR_NETWORK_ERROR应用配置无效或网络异常
9002REAL_NAME_STOP玩家关闭实名窗口，可重新开始认证

开始认证​

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

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

import com.taptap.sdk.compliance.TapTapCompliance;
import com.taptap.sdk.login.TapTapAccount;
import com.taptap.sdk.login.TapTapLogin;

TapTapAccount account = TapTapLogin.getCurrentTapAccount();
if (account != null) {
    TapTapCompliance.startup(activity, account.getOpenId());
}

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

充值额度限制​

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

检查充值限制​

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

import androidx.annotation.NonNull;
import com.taptap.sdk.compliance.TapTapCompliance;
import com.taptap.sdk.compliance.bean.CheckPaymentResult;
import com.taptap.sdk.kit.internal.callback.TapTapCallback;
import com.taptap.sdk.kit.internal.exception.TapTapException;

int amount = 100;

TapTapCompliance.checkPaymentLimit(
        activity,
        amount,
        new TapTapCallback<CheckPaymentResult>() {
            @Override
            public void onSuccess(CheckPaymentResult result) {
                if (result.getStatus()) {
                    // 继续支付流程
                }
                // 受限时 SDK 会弹出对应提示窗口，开发者不需要额外处理
            }

            @Override
            public void onFail(@NonNull TapTapException exception) {
                // 查询失败，可以继续重试，但建议最多重试三次
            }

            @Override
            public void onCancel() {}
        });

上报充值金额​

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

import androidx.annotation.NonNull;
import com.google.gson.JsonElement;
import com.taptap.sdk.compliance.TapTapCompliance;
import com.taptap.sdk.kit.internal.callback.TapTapCallback;
import com.taptap.sdk.kit.internal.exception.TapTapException;

int amount = 100;

TapTapCompliance.submitPayment(amount, new TapTapCallback<JsonElement>() {
    @Override
    public void onSuccess(JsonElement result) {
        // 上报成功
    }

    @Override
    public void onFail(@NonNull TapTapException exception) {
        // 上报失败，可以继续重试，但建议最多重试三次
    }

    @Override
    public void onCancel() {}
});

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

退出认证​

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

TapTapCompliance.exit();

其他​

获取玩家年龄段​

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

int ageRange = TapTapCompliance.getAgeRange();

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

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

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

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

获取剩余时长​

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

int remainingSeconds = TapTapCompliance.getRemainingTime();

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

设置适龄限制​

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

接入验证​

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