跳到主要内容
版本：v7

TapSDK Android 接口

XDSDK v7 已经内置并初始化 TapSDK v4，游戏侧不需要自行初始化 TapSDK。需要使用 TapSDK 能力时，可以参考 TapSDK 官方文档对接口的说明，但使用的时候请调用 com.xd.sdk.taptap 包下的封装类。

依赖与入口​

Native Android 工程请先参考 Android 接入配置 集成 XDSDK。如需启用某个 TapSDK 能力，需要同时确认对应 TapSDK 模块已经被集成。

能力入口类
TapSDK 登录XDGAccount
实名和防沉迷无
TapDB 数据分析XDTapEvent
内嵌动态XDTapMoment
成就系统XDTapAchievement
云存档XDTapCloudSave
正版验证、DLCXDTapLicense
TapTap 评价XDTapReview
更新唤起XDTapUpdate

TapSDK 封装入口类均在 com.xd.sdk.taptap 包下。

import com.xd.sdk.taptap.XDTapAchievement
import com.xd.sdk.taptap.XDTapCloudSave
import com.xd.sdk.taptap.XDTapEvent
import com.xd.sdk.taptap.XDTapLicense
import com.xd.sdk.taptap.XDTapMoment
import com.xd.sdk.taptap.XDTapReview
import com.xd.sdk.taptap.XDTapUpdate

TapTap 登录​

请使用 XDSDK 的登录接口。

实名和防沉迷​

XDSDK 在国内登录流程中已包含实名和防沉迷流程，游戏不需要自行处理相关内容。

TapDB 数据分析​

对应 TapSDK 文档：TapDB 客户端接入。

发送普通事件请使用 XDSDK 的事件上报接口。

以下接口请使用 XDTapEvent。

方法说明
XDTapEvent.deviceInitialize(properties)初始化设备属性，只在字段为空时写入。
XDTapEvent.deviceUpdate(properties)更新设备属性，新值会覆盖旧值。
XDTapEvent.deviceAdd(properties)累加设备数值属性。
XDTapEvent.userInitialize(properties)初始化账号属性，只在字段为空时写入。
XDTapEvent.userUpdate(properties)更新账号属性。
XDTapEvent.userAdd(properties)累加账号数值属性。
XDTapEvent.addCommonProperty(name, value)添加单个静态通用事件属性。
XDTapEvent.addCommon(properties)批量添加静态通用事件属性。
XDTapEvent.clearCommonProperty(name)清除单个静态通用事件属性。
XDTapEvent.clearCommonProperties(vararg names)批量清除静态通用事件属性。
XDTapEvent.clearAllCommonProperties()清除全部静态通用事件属性。
XDTapEvent.registerDynamicProperties(dynamicProperties)注册动态通用事件属性；传 null 可清除注册。

deviceAdd 和 userAdd 仅支持数值属性。动态属性回调中应返回普通 JSON 数据，避免执行耗时逻辑。

import com.xd.sdk.taptap.XDTapEvent
import com.xd.sdk.taptap.XDTapEventDynamicProperties
import org.json.JSONObject

XDTapEvent.deviceInitialize(JSONObject().put("first_server", "server_1"))
XDTapEvent.userUpdate(
    JSONObject()
        .put("current_server", "server_2")
        .put("level", 18)
)

XDTapEvent.addCommon(JSONObject().put("build_type", "release"))
XDTapEvent.registerDynamicProperties(object : XDTapEventDynamicProperties {
    override fun getDynamicProperties(): JSONObject {
        return JSONObject().put("battle_mode", "pve")
    }
})

内嵌动态​

对应 TapSDK 文档：内嵌动态开发指南。

方法说明
XDTapMoment.setCallback(callback)设置动态回调。
XDTapMoment.open()打开 TapTap 动态页面。
XDTapMoment.openScene(sceneId)打开指定场景动态页面。
XDTapMoment.publish(publishMetaData)发布动态，PublishMetaData 包含内容、图片路径和视频路径。
XDTapMoment.closeWithTitle(title, content)关闭动态页面前展示二次确认弹窗。
XDTapMoment.close()直接关闭动态页面。
XDTapMoment.fetchNotification()获取新动态通知数量，结果通过动态回调返回。

常用回调码：

code说明
10000动态发布成功
10100动态发布失败
10200关闭动态发布页面
20000获取新消息成功
20100获取新消息失败
30000动态页面打开
30100动态页面关闭
50000取消关闭所有动态界面
50100确认关闭所有动态界面
60000动态页面内登录成功
70000场景化入口回调
import com.taptap.sdk.moment.TapTapMoment
import com.taptap.sdk.moment.model.PublishMetaData
import com.xd.sdk.taptap.XDTapMoment

XDTapMoment.setCallback(TapTapMoment.TapTapMomentCallback { code, message ->
    // 根据 code 和 message 处理动态状态
})

XDTapMoment.open()
XDTapMoment.openScene("scene_id")
XDTapMoment.fetchNotification()

val publishMetaData = PublishMetaData(
    "动态文字内容",
    listOf("file:///path/to/image.png"),
    emptyList()
)
XDTapMoment.publish(publishMetaData)

正版验证和 DLC​

对应 TapSDK 文档：正版验证开发指南。

方法说明
XDTapLicense.registerLicenseCallback(callback)注册正版验证回调，可注册多个。
XDTapLicense.checkLicense(activity, forceCheck)检查当前用户是否拥有游戏授权，forceCheck 默认为 false。
XDTapLicense.registerDLCCallback(callback)注册 DLC 查询和购买回调。
XDTapLicense.queryDLC(activity, skuList)查询 DLC 购买状态。
XDTapLicense.purchaseDLC(activity, skuId)发起 DLC 购买。

DLC 查询结果中，商品状态 0 表示未购买，1 表示已购买。查询回调结果码 0 表示查询成功，1 表示未安装 TapTap 客户端，2 表示查询失败，80000 表示未知错误。购买回调结果中，0 表示未完成支付，1 表示支付成功，-1 表示支付异常。

import com.taptap.sdk.license.TapTapDLCCallback
import com.taptap.sdk.license.TapTapLicenseCallback
import com.xd.sdk.taptap.XDTapLicense

XDTapLicense.registerLicenseCallback(object : TapTapLicenseCallback {
    override fun onLicenseSuccess() {
        // 正版验证成功
    }
})

XDTapLicense.checkLicense(activity)
XDTapLicense.checkLicense(activity, forceCheck = true)

XDTapLicense.registerDLCCallback(object : TapTapDLCCallback {
    override fun onQueryResult(code: Int, resultList: HashMap<String, Int>?) {
        // DLC 查询结果
    }

    override fun onPurchaseResult(sku: String, code: Int) {
        // DLC 购买结果
    }
})

XDTapLicense.queryDLC(activity, listOf("dlc_sku_id"))
XDTapLicense.purchaseDLC(activity, "dlc_sku_id")

TapTap 评价​

对应 TapSDK 文档：评价开发指南。

方法说明
XDTapReview.openReview(context, appId)跳转到当前游戏的 TapTap 评价页面。

appId 不能为空。国内包会优先唤起 TapTap 国内客户端，海外包会优先唤起 TapTap Global 客户端；客户端不可用时会降级打开对应 Web 页面。

import com.xd.sdk.taptap.XDTapReview

XDTapReview.openReview(context, "tap_app_id")

更新唤起​

对应 TapSDK 文档：更新唤起开发指南。

方法说明
XDTapUpdate.updateGame(activity, appId, callback)游戏自行判断需要更新时调用，玩家取消更新时触发 callback.onCancel()。
XDTapUpdate.checkForceUpdate()使用 TapTap 开发者中心配置的更新规则检查强更。

checkForceUpdate() 仅支持国内包。海外包调用 updateGame() 时必须传入 appId，XDSDK 会优先唤起 TapTap Global 客户端，失败后打开下载页。

import com.xd.sdk.taptap.XDTapUpdate

XDTapUpdate.checkForceUpdate()

XDTapUpdate.updateGame(activity, "tap_app_id") {
    // 玩家取消更新
}

成就系统​

对应 TapSDK 文档：成就系统开发指南。

方法说明
XDTapAchievement.registerCallback(callback)注册成就回调。
XDTapAchievement.unregisterCallback(callback)注销成就回调。
XDTapAchievement.unlock(achievementId)解锁指定成就。
XDTapAchievement.increment(achievementId, steps)增加分步成就步数。
XDTapAchievement.setToastEnable(enable)设置是否展示成就达成提示。
XDTapAchievement.showAchievements()打开成就展示页。

TapAchievementCallback 需要实现：

方法说明
onAchievementSuccess(code, result)成就操作成功。result 包含成就 ID、成就名称、成就类型和当前步数。
onAchievementFailure(achievementId, errorCode, errorMsg)成就操作失败。

常见错误码：

code说明
80000未初始化
80001区域不支持，目前仅支持国内区域
80002当前未登录
80010当前登录失效
80020参数无效
80030网络异常
80100网络异常或需要联系技术支持
import com.taptap.sdk.achievement.TapAchievementCallback
import com.taptap.sdk.achievement.TapTapAchievementResult
import com.xd.sdk.taptap.XDTapAchievement

val achievementCallback = object : TapAchievementCallback {
    override fun onAchievementSuccess(code: Int, result: TapTapAchievementResult?) {
        // 成就操作成功
    }

    override fun onAchievementFailure(achievementId: String, errorCode: Int, errorMsg: String) {
        // 成就操作失败
    }
}

XDTapAchievement.registerCallback(achievementCallback)
XDTapAchievement.unlock("achievement_id")
XDTapAchievement.increment("achievement_id", 1)
XDTapAchievement.setToastEnable(true)
XDTapAchievement.showAchievements()

云存档​

对应 TapSDK 文档：云存档开发指南。

方法说明
XDTapCloudSave.registerCallback(callback)注册 CloudSave 统一状态回调。
XDTapCloudSave.unregisterCallback(callback)注销 CloudSave 统一状态回调。
XDTapCloudSave.createArchive(metadata, archiveFilePath, archiveCoverPath, callback)创建存档并上传云端。
XDTapCloudSave.updateArchive(archiveUUID, metadata, archiveFilePath, archiveCoverPath, callback)更新指定存档。
XDTapCloudSave.deleteArchive(archiveUUID, callback)删除指定存档。
XDTapCloudSave.getArchiveList(callback)获取当前用户的存档列表。
XDTapCloudSave.getArchiveData(archiveUUID, archiveFileID, callback)下载指定存档文件。
XDTapCloudSave.getArchiveCover(archiveUUID, archiveFileID, callback)获取指定存档封面。

ArchiveMetadata 用于创建和更新存档，包含 name、summary、extra、playtime。ArchiveData 为服务端返回的存档数据。

回调接口：

接口方法说明
TapCloudSaveCallbackonResult(resultCode)云存档统一状态结果。
TapCloudSaveRequestCallbackonArchiveCreated(archive)创建成功。
TapCloudSaveRequestCallbackonArchiveUpdated(archive)更新成功。
TapCloudSaveRequestCallbackonArchiveDeleted(archive)删除成功。
TapCloudSaveRequestCallbackonArchiveListResult(archiveList)存档列表结果。
TapCloudSaveRequestCallbackonArchiveDataResult(archiveUUID, archiveFileID, data)存档数据下载结果。
TapCloudSaveRequestCallbackonArchiveCoverResult(archiveUUID, archiveFileID, coverData)存档封面下载结果。
TapCloudSaveRequestCallbackonRequestError(errorCode, errorMessage)请求失败。

限制和错误码：

项目说明
统一状态码 300001需要登录
统一状态码 300002初始化失败，需要重新初始化
存档名称仅支持英文、数字、下划线和中划线
存档文件单个文件不超过 10 MB
存档封面可选，大小不超过 512 KB
调用频率创建和更新存档共享一分钟冷却时间
请求错误 400000存档文件或封面大小非法
请求错误 400001存档上传频率超限
请求错误 400002指定存档不存在
请求错误 400003单个应用下存档数量超限
请求错误 400004单个应用下使用存储空间超限
请求错误 400005总使用存储空间超限
请求错误 400006操作令牌非法
请求错误 400007不允许并发调用
请求错误 400008找不到可用的 OSS 供应商
请求错误 400009存档名称不合法
import com.taptap.sdk.cloudsave.ArchiveMetadata
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
import com.xd.sdk.taptap.XDTapCloudSave

val metadata = ArchiveMetadata.Builder()
    .setName("save_001")
    .setSummary("第一章")
    .setExtra("{}")
    .setPlaytime(3600)
    .build()

XDTapCloudSave.createArchive(
    metadata,
    "path/to/archive/file",
    "path/to/cover/image",
    object : TapCloudSaveRequestCallback {
        override fun onRequestError(errorCode: Int, errorMessage: String) {
            // 请求失败
        }

        override fun onArchiveCreated(archive: com.taptap.sdk.cloudsave.ArchiveData) {
            // 创建成功
        }
    }
)