版本：v7

TapSDK Unity 接口

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

依赖与入口

Unity 工程请先参考 Unity 接入配置集成 XDSDK。XDSDK 会在初始化时完成 TapSDK 相关配置，游戏侧只需要在 XDGCommon.InitSDK 成功后调用下列业务接口。

能力	依赖模块	入口类
TapSDK 登录	`com.xd.sdk.account` + `com.xd.sdk.tap`	`XDGAccount`
实名和防沉迷	`com.xd.sdk.account` + `com.xd.sdk.tap`	无
TapDB 数据分析	`com.xd.sdk.tap`	`XDGTapSDK`
内嵌动态	`com.xd.sdk.tap`	`XDGTapSDK`
正版验证、DLC	`com.xd.sdk.tap`	`XDGTapSDK`
TapTap 评价	`com.xd.sdk.tap`	`XDGTapSDK`
更新唤起	`com.xd.sdk.tap`	`XDGTapSDK`
成就系统	`com.xd.sdk.tap.plus`	`XDGTapPlusSDK`
云存档	`com.xd.sdk.tap.plus`	`XDGTapPlusSDK`

using XD.SDK.Tap;
using XD.SDK.Tap.Plus;

TapTap 登录

请使用 XDSDK 的登录接口。

实名和防沉迷

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

TapDB 数据分析

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

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

以下接口请使用 XDGTapSDK。

using XD.SDK.Tap;

方法	说明
`DeviceInitialize(...)`	初始化设备属性，只在字段为空时写入。
`DeviceUpdate(...)`	更新设备属性，新值会覆盖旧值。
`DeviceAdd(...)`	累加设备数值属性。
`UserInitialize(...)`	初始化账号属性，只在字段为空时写入。
`UserUpdate(...)`	更新账号属性。
`UserAdd(...)`	累加账号数值属性。
`AddCommonProperty(string key, string value)`	添加单个静态通用事件属性。
`AddCommon(...)`	批量添加静态通用事件属性。
`ClearCommonProperty(string key)`	清除单个静态通用事件属性。
`ClearCommonProperties(string[] keys)`	批量清除静态通用事件属性。
`ClearAllCommonProperties()`	清除全部静态通用事件属性。
`RegisterDynamicProperties(IDynamicProperties properties)`	注册动态通用事件属性，每次上报事件时由 TapSDK 拉取最新值。

properties 支持 JSON 字符串或 Dictionary<string, object>。建议优先使用 Dictionary<string, object>，避免 JSON 格式错误。动态属性回调可能不在 Unity 主线程执行，回调里不要访问 GameObject、PlayerPrefs、Time、SceneManager 等 Unity API。需要上报的动态值应提前缓存成普通 C# 数据。

using System.Collections.Generic;
using XD.SDK.Tap;
using XD.SDK.Tap.Public;

XDGTapSDK.DeviceInitialize(new Dictionary<string, object>
{
    { "first_server", "server_1" }
});

XDGTapSDK.UserUpdate(new Dictionary<string, object>
{
    { "current_server", "server_2" },
    { "level", 18 }
});

XDGTapSDK.AddCommon(new Dictionary<string, object>
{
    { "build_type", "release" }
});

public class CachedDynamicProperties : IDynamicProperties
{
    private readonly Dictionary<string, object> snapshot;

    public CachedDynamicProperties(Dictionary<string, object> snapshot)
    {
        this.snapshot = snapshot;
    }

    public Dictionary<string, object> GetDynamicProperties()
    {
        return snapshot;
    }
}

XDGTapSDK.RegisterDynamicProperties(
    new CachedDynamicProperties(new Dictionary<string, object>
    {
        { "battle_mode", "pve" }
    }));

内嵌动态

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

方法	说明
`SetMomentCallback(Action<int, string> callback)`	设置动态回调。
`MomentOpen()`	打开 TapTap 动态页面。
`MomentOpenScene(string sceneId)`	打开指定场景动态页面。
`MomentPublish(PublishMetaData metaData)`	发布动态，`PublishMetaData` 包含内容、图片路径和视频路径。
`MomentClose(string title, string content)`	关闭动态页面，并展示标题和内容提示。
`MomentClose()`	直接关闭动态页面。
`MomentFetchNotification()`	拉取动态通知，结果通过动态回调返回。

using System.Collections.Generic;
using TapSDK.Moment;
using XD.SDK.Tap;

XDGTapSDK.SetMomentCallback((code, message) =>
{
    // 根据 code 和 message 处理动态状态
});

XDGTapSDK.MomentOpen();
XDGTapSDK.MomentOpenScene("scene_id");
XDGTapSDK.MomentFetchNotification();

var metaData = new PublishMetaData(
    content: "动态文字内容",
    imagePaths: new List<string> { "file:///path/to/image.png" });
XDGTapSDK.MomentPublish(metaData);

正版验证和 DLC

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

方法	说明
`RegisterLicenseCallback(ITapLicenseCallback callback)`	注册正版验证回调。
`CheckLicense(bool force = false)`	检查当前用户是否拥有游戏授权，`force` 为 `true` 时强制重新校验。
`RegisterDLCCallback(ITapDlcCallback callback)`	注册 DLC 查询和购买回调。
`QueryDLC(string[] dlcList)`	查询 DLC 购买状态。
`PurchaseDLC(string dlc)`	发起 DLC 购买。

using System.Collections.Generic;
using TapSDK.License;
using XD.SDK.Tap;

public class LicenseCallback : ITapLicenseCallback
{
    public void OnLicenseSuccess()
    {
        // 正版验证成功
    }

    public void OnLicenseFailed()
    {
        // 正版验证失败
    }
}

public class DlcCallback : ITapDlcCallback
{
    public void OnQueryCallBack(TapLicenseQueryCode code, Dictionary<string, object> queryList)
    {
        // DLC 查询结果
    }

    public void OnOrderCallBack(string sku, TapLicensePurchasedCode status)
    {
        // DLC 购买结果
    }
}

XDGTapSDK.RegisterLicenseCallback(new LicenseCallback());
XDGTapSDK.CheckLicense();

XDGTapSDK.RegisterDLCCallback(new DlcCallback());
XDGTapSDK.QueryDLC(new[] { "dlc_sku_id" });
XDGTapSDK.PurchaseDLC("dlc_sku_id");

TapTap 评价

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

方法	说明
`OpenReview(string appId)`	跳转到当前游戏的 TapTap 评价页面。移动端会把 `appId` 传给原生桥接；PC 端使用 TapSDK 的评价入口。

using XD.SDK.Tap;

XDGTapSDK.OpenReview("tap_app_id");

更新唤起

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

方法	说明
`CheckForceUpdate()`	使用 TapTap 开发者中心配置的更新规则检查强更。
`UpdateGame(string appId, Action onCancel)`	游戏自行判断需要更新时调用，`onCancel` 在玩家取消更新时触发。

using XD.SDK.Tap;

// 使用 TapTap 开发者中心的强更配置
XDGTapSDK.CheckForceUpdate();

// 游戏自己判断有新版本后触发
XDGTapSDK.UpdateGame("tap_app_id", () =>
{
    // 玩家取消更新
});

成就系统

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

以下接口请使用 XDGTapPlusSDK。

using XD.SDK.Tap.Plus;

方法	说明
`RegisterAchievementCallback(ITapAchievementCallback callback)`	注册成就回调。
`Unlock(string achievementId)`	解锁指定成就。
`Increment(string achievementId, int count)`	增加分步成就步数。
`AchievementSetToastEnable(bool bEnable)`	设置是否展示成就达成提示。
`ShowAchievements()`	打开成就展示页。

ITapAchievementCallback 需要实现：

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

using TapSDK.Achievement;
using XD.SDK.Tap.Plus;

public class AchievementCallback : ITapAchievementCallback
{
    public void OnAchievementSuccess(int code, TapAchievementResult result)
    {
        // 成就操作成功
    }

    public void OnAchievementFailure(string achievementId, int errorCode, string errorMsg)
    {
        // 成就操作失败
    }
}

XDGTapPlusSDK.RegisterAchievementCallback(new AchievementCallback());
XDGTapPlusSDK.Unlock("achievement_id");
XDGTapPlusSDK.Increment("step_achievement_id", 1);
XDGTapPlusSDK.AchievementSetToastEnable(true);
XDGTapPlusSDK.ShowAchievements();

云存档

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

方法	说明
`RegisterCloudSaveCallback(ITapCloudSaveCallback callback)`	注册 CloudSave 统一状态回调，返回 TapSDK 的 resultCode。
`CreateArchive(ArchiveMetadata metadata, string archiveFilePath, string archiveCoverPath)`	创建存档并上传云端，返回 `Task<ArchiveData>`。
`UpdateArchive(string archiveUuid, ArchiveMetadata metadata, string archiveFilePath, string archiveCoverPath)`	更新指定存档。
`DeleteArchive(string archiveUuid)`	删除指定存档。
`GetArchiveList()`	获取当前用户的存档列表。
`GetArchiveData(string archiveUuid, string archiveFileId)`	下载指定存档文件，返回 `byte[]`。
`GetArchiveCover(string archiveUuid, string archiveFileId)`	获取指定存档封面，返回 `byte[]`。

ArchiveMetadata 用于创建和更新存档，包含存档名称、存档描述、额外信息和游戏时长。ArchiveData 为服务端返回的存档数据。

云存档接口返回 Task，请在 async 方法中调用，并处理异常。官方限制仍然适用：单个存档文件不超过 10 MB，封面文件不超过 512 KB。

using System.Collections.Generic;
using TapSDK.CloudSave;
using XD.SDK.Tap.Plus;

var metadata = new ArchiveMetadata(
    archiveName: "存档名称",
    archiveSummary: "存档描述",
    archiveExtra: "额外信息",
    archivePlaytime: 3600);

string archiveFilePath = "path/to/archive/file";
string archiveCoverPath = "path/to/cover/image";

ArchiveData archive = await XDGTapPlusSDK.CreateArchive(
    metadata,
    archiveFilePath,
    archiveCoverPath);

List<ArchiveData> archives = await XDGTapPlusSDK.GetArchiveList();
byte[] archiveBytes = await XDGTapPlusSDK.GetArchiveData(
    archive.Uuid,
    archive.FileId);

依赖与入口​

TapTap 登录​

实名和防沉迷​

TapDB 数据分析​

内嵌动态​

正版验证和 DLC​

TapTap 评价​

更新唤起​

成就系统​

云存档​