GMTapSDK API 参考文档

原创已于 2025-08-31 12:29:55 修改 · 1k 阅读

18 ·

CC 4.0 BY-SA版权

文章标签：

#数据库 #java #linux

于 2025-08-31 12:27:18 首次发布

概述

本文档提供 GMTapSDK 扩展所有 API 接口的详细参考信息，包括函数签名、参数说明、返回值和使用示例。

文章目录

基础 SDK 接口

taptap_init

初始化 TapSDK。

语法:

taptap_init(clientId, clientToken, serverUrl, regionType, gameChannel, gameVersion)

参数:

clientId (string): TapTap 应用的 Client ID
clientToken (string): TapTap 应用的 Client Token
serverUrl (string): 服务器地址
regionType (real): 地区类型，0=国内，1=海外
gameChannel (string): 游戏渠道标识
gameVersion (string): 游戏版本号

返回值:

real: 调用结果，通常返回 0

事件回调:

事件类型: "INIT"
成功状态: status = "OK"
失败状态: status = "ERROR", 包含 message 字段

示例:

taptap_init("your_client_id", "your_client_token", "https://your-server.com", 0, "gamemaker", "1.0.0");

taptap_login

启动 TapTap 用户登录流程。

语法:

taptap_login()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "LOGIN"
成功时包含 userData 字段（JSON 格式的用户信息）
失败时包含 message 字段

用户数据结构:

{
    "name": "用户昵称",
    "avatar": "头像URL",
    "openid": "用户OpenID", 
    "unionid": "用户UnionID",
    "accessToken": "访问令牌"
}

示例:

if (global.tapsdk_initialized) {
    taptap_login();
}

taptap_login_status

检查当前用户登录状态。

语法:

taptap_login_status()

参数: 无

返回值:

string: 登录状态
- "logged_in": 用户已登录
- "not_logged_in": 用户未登录

示例:

var status = taptap_login_status();
if (status == "logged_in") {
    show_debug_message("用户已登录");
}

taptap_logout

登出当前用户。

语法:

taptap_logout()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "LOGOUT"
成功状态: status = "OK"

示例:

taptap_logout();

防沉迷系统接口

taptap_anti_addiction_init

初始化防沉迷系统。

语法:

taptap_anti_addiction_init(clientId, enableTapLogin, showSwitchAccount)

参数:

clientId (string): TapTap 应用的 Client ID
enableTapLogin (real): 是否启用 TapTap 快速认证，1=启用，0=禁用
showSwitchAccount (real): 是否显示切换账号按钮，1=显示，0=隐藏

返回值:

real: 调用结果

事件回调:

事件类型: "ANTI_ADDICTION_INIT"
后续会收到 "ANTI_ADDICTION_CALLBACK" 回调事件

示例:

taptap_anti_addiction_init(global.client_id, 1, 0);

taptap_anti_addiction_startup

启动防沉迷认证流程。

语法:

taptap_anti_addiction_startup(userIdentifier)

参数:

userIdentifier (string): 用户唯一标识符

返回值:

real: 调用结果

事件回调:

事件类型: "ANTI_ADDICTION_STARTUP"
认证过程中会收到多个 "ANTI_ADDICTION_CALLBACK" 事件

回调状态码:

"LOGIN_SUCCESS": 防沉迷登录成功
"EXITED": 用户退出账号
"DURATION_LIMIT": 游戏时长限制
"PERIOD_RESTRICT": 时段限制
"REAL_NAME_STOP": 实名认证中断
"SWITCH_ACCOUNT": 切换账号

示例:

taptap_anti_addiction_startup("user_" + string(global.user_id));

taptap_anti_addiction_get_age_range

获取用户年龄段信息。

语法:

taptap_anti_addiction_get_age_range()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "ANTI_ADDICTION_AGE_RANGE"
成功时包含 ageRange (数值) 和 ageDescription (描述) 字段

年龄段描述:

“未知用户类型”
“8岁以下儿童”
“8-16岁未成年人”
“16-18岁未成年人”
“18岁以上成年人”

示例:

taptap_anti_addiction_get_age_range();

taptap_anti_addiction_logout

防沉迷系统登出。

语法:

taptap_anti_addiction_logout()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "ANTI_ADDICTION_LOGOUT"

示例:

taptap_anti_addiction_logout();

内嵌动态系统接口

taptap_moment_fetch_notification

获取新消息通知。

语法:

taptap_moment_fetch_notification()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "MOMENT_FETCH_NOTIFICATION"
可能收到 "MOMENT_GET_NOTICE_SUCCESS" 或 "MOMENT_GET_NOTICE_FAIL" 回调

示例:

taptap_moment_fetch_notification();

taptap_moment_open

打开动态页面。

语法:

taptap_moment_open(orientation)

参数:

orientation (real): 屏幕方向，0=竖屏，1=横屏

返回值:

real: 调用结果

事件回调:

事件类型: "MOMENT_OPEN"

示例:

// 竖屏模式打开
taptap_moment_open(0);

// 横屏模式打开  
taptap_moment_open(1);

taptap_moment_open_with_scene

通过场景化入口打开动态页面。

语法:

taptap_moment_open_with_scene(sceneId, orientation)

参数:

sceneId (string): 场景标识符
orientation (real): 屏幕方向，0=竖屏，1=横屏

返回值:

real: 调用结果

事件回调:

事件类型: "MOMENT_OPEN_WITH_SCENE"

常用场景ID:

"achievement_unlock": 成就解锁场景
"level_complete": 关卡完成场景
"high_score": 高分场景

示例:

taptap_moment_open_with_scene("achievement_unlock", 0);

taptap_moment_close

关闭动态页面。

语法:

taptap_moment_close()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "MOMENT_CLOSE"

示例:

taptap_moment_close();

taptap_moment_publish

发布动态内容。

语法:

taptap_moment_publish(content, imagePath)

参数:

content (string): 动态文本内容（必填）
imagePath (string): 图片文件路径（可选，传空字符串表示无图片）

返回值:

real: 调用结果

事件回调:

事件类型: "MOMENT_PUBLISH"
可能收到 "MOMENT_PUBLISH_SUCCESS" 或 "MOMENT_PUBLISH_FAIL" 回调

示例:

// 发布纯文本动态
taptap_moment_publish("刚刚完成了困难关卡！", "");

// 发布带图片的动态
taptap_moment_publish("看我的新装备！", "/sdcard/screenshot.png");

好友系统接口

taptap_friends_register_listener

注册好友状态监听器。

语法:

taptap_friends_register_listener()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_LISTENER_REGISTERED"
注册成功后会收到好友状态变化事件：
- "FRIENDS_ONLINE": 好友上线
- "FRIENDS_OFFLINE": 好友下线
- "FRIENDS_RICH_PRESENCE_CHANGED": 好友状态变化

示例:

// 通常在用户登录成功后调用一次
taptap_friends_register_listener();

taptap_friends_add

申请添加好友。

语法:

taptap_friends_add(userId, attributes)

参数:

userId (string): 目标用户ID
attributes (string): 附加属性，JSON 格式字符串（可为空）

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_ADD"
成功时包含 requestId 字段

示例:

var target_user = "target_user_id";
var message = json_stringify({"message": "想加你为好友"});
taptap_friends_add(target_user, message);

taptap_friends_get_request_list

获取好友申请列表。

语法:

taptap_friends_get_request_list()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_GET_REQUEST_LIST"
成功时包含 requestCount 和 requestsList 字段

申请列表数据结构:

[
    {
        "requestId": "申请ID",
        "fromUserId": "申请人用户ID",
        "fromUserName": "申请人用户名",
        "status": "申请状态",
        "createdAt": "创建时间",
        "attributes": "附加属性"
    }
]

示例:

taptap_friends_get_request_list();

taptap_friends_accept_request

同意好友申请。

语法:

taptap_friends_accept_request(requestId)

参数:

requestId (string): 好友申请ID

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_ACCEPT_REQUEST"

示例:

taptap_friends_accept_request("request_id_123");

taptap_friends_decline_request

拒绝好友申请。

语法:

taptap_friends_decline_request(requestId)

参数:

requestId (string): 好友申请ID

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_DECLINE_REQUEST"

示例:

taptap_friends_decline_request("request_id_123");

taptap_friends_delete_request

删除好友申请。

语法:

taptap_friends_delete_request(requestId)

参数:

requestId (string): 好友申请ID

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_DELETE_REQUEST"

示例:

taptap_friends_delete_request("request_id_123");

taptap_friends_get_list

获取好友列表。

语法:

taptap_friends_get_list()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_GET_LIST"
成功时包含 friendCount 和 friendsList 字段

好友列表数据结构:

[
    {
        "friendId": "好友用户ID",
        "friendName": "好友用户名",
        "online": true,
        "avatar": "头像URL",
        "richPresence": "富状态信息"
    }
]

示例:

taptap_friends_get_list();

taptap_friends_delete

删除好友。

语法:

taptap_friends_delete(friendshipId)

参数:

friendshipId (string): 好友关系ID

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_DELETE"

示例:

taptap_friends_delete("friendship_id_123");

taptap_friends_query_friendship

查询好友关系。

语法:

taptap_friends_query_friendship(userId)

参数:

userId (string): 目标用户ID

返回值:

real: 调用结果

事件回调:

事件类型: "FRIENDS_QUERY_FRIENDSHIP"
成功时包含 friendshipStatus 字段（“FRIENDS” 或 “NOT_FRIENDS”）

示例:

taptap_friends_query_friendship("target_user_id");

成就系统接口

taptap_achievement_register_callback

注册成就回调监听器。

语法:

taptap_achievement_register_callback()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "ACHIEVEMENT_CALLBACK_REGISTERED"
后续会收到成就相关的回调事件

示例:

// 通常在游戏启动时调用一次
taptap_achievement_register_callback();

taptap_achievement_init

初始化成就数据。

语法:

taptap_achievement_init()

参数: 无

返回值:

real: 调用结果

事件回调:

成功: "ACHIEVEMENT_INIT_SUCCESS"
失败: "ACHIEVEMENT_INIT_FAIL"

示例:

// 在注册回调成功后调用
taptap_achievement_init();

taptap_achievement_fetch_all

获取所有成就配置。

语法:

taptap_achievement_fetch_all()

参数: 无

返回值:

real: 调用结果

事件回调:

成功: "ACHIEVEMENT_FETCH_ALL_SUCCESS"
失败: "ACHIEVEMENT_FETCH_ALL_FAIL"
成功时包含 achievementsList 和 achievementsCount 字段

成就数据结构:

[
    {
        "achievementId": "成就ID",
        "title": "成就标题",
        "description": "成就描述",
        "type": "成就类型",
        "totalSteps": 100
    }
]

示例:

taptap_achievement_fetch_all();

taptap_achievement_fetch_user

获取用户成就进度。

语法:

taptap_achievement_fetch_user()

参数: 无

返回值:

real: 调用结果

事件回调:

成功: "ACHIEVEMENT_FETCH_USER_SUCCESS"
失败: "ACHIEVEMENT_FETCH_USER_FAIL"
成功时包含 userAchievements 和 unlockedCount 字段

用户成就数据结构:

[
    {
        "achievementId": "成就ID",
        "isUnlocked": true,
        "currentSteps": 75,
        "unlockedAt": "解锁时间"
    }
]

示例:

taptap_achievement_fetch_user();

taptap_achievement_reach

达成成就。

语法:

taptap_achievement_reach(achievementId)

参数:

achievementId (string): 成就ID

返回值:

real: 调用结果

事件回调:

事件类型: "ACHIEVEMENT_REACH_STARTED"
可能收到 "ACHIEVEMENT_STATUS_UPDATE" 回调

示例:

taptap_achievement_reach("first_victory");

taptap_achievement_grow

增长成就进度。

语法:

taptap_achievement_grow(achievementId, steps)

参数:

achievementId (string): 成就ID
steps (real): 增长的步数

返回值:

real: 调用结果

事件回调:

事件类型: "ACHIEVEMENT_GROW_STARTED"
可能收到 "ACHIEVEMENT_STATUS_UPDATE" 回调

示例:

// 击杀敌人成就增长5步
taptap_achievement_grow("kill_enemies", 5);

taptap_achievement_set_show_toast

设置成就解锁提示。

语法:

taptap_achievement_set_show_toast(show)

参数:

show (real): 是否显示提示，1=显示，0=隐藏

返回值:

real: 调用结果

事件回调:

事件类型: "ACHIEVEMENT_SET_TOAST_SUCCESS"

示例:

// 启用成就解锁提示
taptap_achievement_set_show_toast(1);

taptap_achievement_show_ui

显示成就界面。

语法:

taptap_achievement_show_ui()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "ACHIEVEMENT_SHOW_UI_SUCCESS"

示例:

taptap_achievement_show_ui();

云存档系统接口

taptap_gamesave_create

创建云存档对象。

语法:

taptap_gamesave_create(summary, description, playedTime, progressValue)

参数:

summary (string): 存档摘要
description (string): 存档描述
playedTime (real): 游戏时长（秒）
progressValue (real): 进度百分比（0-100）

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_CREATE"
成功时包含 saveId 字段

示例:

taptap_gamesave_create("第5关存档", "困难模式，进度75%", 3600, 75);

taptap_gamesave_save

保存存档数据。

语法:

taptap_gamesave_save(saveData)

参数:

saveData (string): 存档数据，通常为 JSON 字符串

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_SAVE"

示例:

var save_data = json_stringify({
    level: 5,
    score: 12345,
    items: ["sword", "shield", "potion"]
});
taptap_gamesave_save(save_data);

taptap_gamesave_query_all

查询所有存档。

语法:

taptap_gamesave_query_all()

参数: 无

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_QUERY_ALL"
成功时包含 savesList 字段

示例:

taptap_gamesave_query_all();

taptap_gamesave_query_by_condition

条件查询存档。

语法:

taptap_gamesave_query_by_condition(limit, skip)

参数:

limit (real): 限制返回数量
skip (real): 跳过数量

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_QUERY_BY_CONDITION"
成功时包含 savesList 字段

示例:

// 获取最新的10个存档
taptap_gamesave_query_by_condition(10, 0);

taptap_gamesave_load

加载指定存档。

语法:

taptap_gamesave_load(saveId)

参数:

saveId (string): 存档ID

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_LOAD"
成功时包含 saveData 和 metadata 字段

示例:

taptap_gamesave_load("save_id_123");

taptap_gamesave_delete

删除存档。

语法:

taptap_gamesave_delete(saveId)

参数:

saveId (string): 存档ID

返回值:

real: 调用结果

事件回调:

事件类型: "GAMESAVE_DELETE"

示例:

taptap_gamesave_delete("save_id_123");

排行榜系统接口

taptap_leaderboard_submit_score

提交成绩到排行榜。

语法:

taptap_leaderboard_submit_score(leaderboardName, score, metadata)

参数:

leaderboardName (string): 排行榜名称
score (real): 成绩分数
metadata (string): 元数据，JSON 格式字符串（可选）

返回值:

real: 调用结果

事件回调:

事件类型: "LEADERBOARD_SUBMIT_SCORE"

示例:

var metadata = json_stringify({
    level: "hard",
    character: "warrior",
    timestamp: current_time
});
taptap_leaderboard_submit_score("high_score", 12345, metadata);

taptap_leaderboard_get_rank

获取用户排名。

语法:

taptap_leaderboard_get_rank(leaderboardName, userId)

参数:

leaderboardName (string): 排行榜名称
userId (string): 用户ID

返回值:

real: 调用结果

事件回调:

事件类型: "LEADERBOARD_GET_RANK"
成功时包含 userRank 字段

示例:

taptap_leaderboard_get_rank("high_score", global.current_user_id);

taptap_leaderboard_update_statistic

更新用户统计数据。

语法:

taptap_leaderboard_update_statistic(statisticName, value, overwrite)

参数:

statisticName (string): 统计项名称
value (real): 统计值
overwrite (real): 是否覆盖，1=覆盖，0=累加

返回值:

real: 调用结果

事件回调:

事件类型: "LEADERBOARD_UPDATE_STATISTIC"

示例:

// 累加击杀数
taptap_leaderboard_update_statistic("total_kills", 10, 0);

// 覆盖最高分
taptap_leaderboard_update_statistic("best_score", 9999, 1);

taptap_leaderboard_get_user_statistic

获取用户统计数据。

语法:

taptap_leaderboard_get_user_statistic(userId, statisticNames)

参数:

userId (string): 用户ID
statisticNames (string): 统计项名称，多个用逗号分隔

返回值:

real: 调用结果

事件回调:

事件类型: "LEADERBOARD_GET_USER_STATISTIC"
成功时包含 statistics 字段

示例:

taptap_leaderboard_get_user_statistic(global.current_user_id, "total_kills,total_deaths,play_time");

taptap_leaderboard_get_results

获取排行榜结果。

语法:

taptap_leaderboard_get_results(leaderboardName, skip, limit, selectUserIds)

参数:

leaderboardName (string): 排行榜名称
skip (real): 跳过数量
limit (real): 获取数量
selectUserIds (string): 指定用户ID列表，逗号分隔（可选）

返回值:

real: 调用结果

事件回调:

事件类型: "LEADERBOARD_GET_RESULTS"
成功时包含 rankings 字段

排名数据结构:

[
    {
        "rank": 1,
        "userId": "用户ID",
        "userName": "用户名",
        "score": 12345,
        "metadata": "元数据"
    }
]

示例:

// 获取前10名
taptap_leaderboard_get_results("high_score", 0, 10, "");

// 获取指定用户的排名
taptap_leaderboard_get_results("high_score", 0, 100, "user1,user2,user3");

事件类型参考

基础事件

"INIT": SDK 初始化结果
"LOGIN": 用户登录结果
"LOGOUT": 用户登出结果

防沉迷事件

"ANTI_ADDICTION_INIT": 防沉迷初始化结果
"ANTI_ADDICTION_CALLBACK": 防沉迷回调事件
"ANTI_ADDICTION_STARTUP": 防沉迷认证启动结果
"ANTI_ADDICTION_AGE_RANGE": 年龄段查询结果
"ANTI_ADDICTION_LOGOUT": 防沉迷登出结果

内嵌动态事件

"MOMENT_FETCH_NOTIFICATION": 获取通知结果
"MOMENT_GET_NOTICE_SUCCESS": 获取通知成功回调
"MOMENT_GET_NOTICE_FAIL": 获取通知失败回调
"MOMENT_OPEN": 打开动态页面结果
"MOMENT_OPEN_WITH_SCENE": 场景化打开结果
"MOMENT_CLOSE": 关闭动态页面结果
"MOMENT_PUBLISH": 发布动态结果
"MOMENT_PUBLISH_SUCCESS": 发布成功回调
"MOMENT_PUBLISH_FAIL": 发布失败回调
"MOMENT_LOGIN_SUCCESS": 动态内登录成功

好友系统事件

"FRIENDS_LISTENER_REGISTERED": 监听器注册结果
"FRIENDS_ONLINE": 好友上线通知
"FRIENDS_OFFLINE": 好友下线通知
"FRIENDS_RICH_PRESENCE_CHANGED": 好友状态变化
"FRIENDS_ADD": 添加好友结果
"FRIENDS_GET_REQUEST_LIST": 获取申请列表结果
"FRIENDS_ACCEPT_REQUEST": 同意申请结果
"FRIENDS_DECLINE_REQUEST": 拒绝申请结果
"FRIENDS_DELETE_REQUEST": 删除申请结果
"FRIENDS_GET_LIST": 获取好友列表结果
"FRIENDS_DELETE": 删除好友结果
"FRIENDS_QUERY_FRIENDSHIP": 查询好友关系结果

成就系统事件

"ACHIEVEMENT_CALLBACK_REGISTERED": 回调注册结果
"ACHIEVEMENT_INIT_SUCCESS": 初始化成功
"ACHIEVEMENT_INIT_FAIL": 初始化失败
"ACHIEVEMENT_STATUS_UPDATE": 成就状态更新
"ACHIEVEMENT_STATUS_UPDATE_FAIL": 状态更新失败
"ACHIEVEMENT_FETCH_ALL_SUCCESS": 获取所有成就成功
"ACHIEVEMENT_FETCH_ALL_FAIL": 获取所有成就失败
"ACHIEVEMENT_FETCH_USER_SUCCESS": 获取用户成就成功
"ACHIEVEMENT_FETCH_USER_FAIL": 获取用户成就失败
"ACHIEVEMENT_REACH_STARTED": 开始达成成就
"ACHIEVEMENT_GROW_STARTED": 开始增长进度
"ACHIEVEMENT_SET_TOAST_SUCCESS": 设置提示成功
"ACHIEVEMENT_SHOW_UI_SUCCESS": 显示界面成功

云存档事件

"GAMESAVE_CREATE": 创建存档结果
"GAMESAVE_SAVE": 保存存档结果
"GAMESAVE_QUERY_ALL": 查询所有存档结果
"GAMESAVE_QUERY_BY_CONDITION": 条件查询结果
"GAMESAVE_LOAD": 加载存档结果
"GAMESAVE_DELETE": 删除存档结果

排行榜事件

"LEADERBOARD_SUBMIT_SCORE": 提交成绩结果
"LEADERBOARD_GET_RANK": 获取排名结果
"LEADERBOARD_UPDATE_STATISTIC": 更新统计结果
"LEADERBOARD_GET_USER_STATISTIC": 获取用户统计结果
"LEADERBOARD_GET_RESULTS": 获取排行榜结果

数据结构参考

通用事件数据结构

{
    "taptapType": "事件类型",
    "status": "OK|ERROR",
    "message": "错误信息（失败时）"
}

用户信息结构

{
    "name": "用户昵称",
    "avatar": "头像URL",
    "openid": "用户OpenID",
    "unionid": "用户UnionID", 
    "accessToken": "访问令牌"
}

好友信息结构

{
    "friendId": "好友用户ID",
    "friendName": "好友用户名",
    "online": true,
    "avatar": "头像URL",
    "richPresence": "富状态信息"
}

成就信息结构

{
    "achievementId": "成就ID",
    "title": "成就标题",
    "description": "成就描述",
    "type": "成就类型",
    "totalSteps": 100,
    "isUnlocked": false,
    "currentSteps": 0
}

存档信息结构

{
    "saveId": "存档ID",
    "summary": "存档摘要",
    "description": "存档描述", 
    "playedTime": 3600,
    "progressValue": 75,
    "saveData": "存档数据JSON",
    "createdAt": "创建时间",
    "updatedAt": "更新时间"
}

排名信息结构

{
    "rank": 1,
    "userId": "用户ID",
    "userName": "用户名",
    "score": 12345,
    "metadata": "元数据JSON"
}

使用注意事项

异步操作: 所有 API 调用都是异步的，结果通过事件系统返回
事件处理: 必须在 Other -> Async - Social 事件中处理回调
初始化顺序: 必须先初始化 SDK，再调用其他功能
登录状态: 大部分功能需要用户已登录
网络依赖: 所有功能都需要网络连接
错误处理: 务必处理 status = "ERROR" 的情况
数据格式: JSON 数据需要正确解析和验证
资源管理: 及时清理不需要的数据结构

本 API 参考文档基于 GMTapSDK 3.0.0 版本编写，如有更新请参考最新版本文档。