当前位置： 首页 > backend >正文

GMTapSDK 扩展使用文档

backend 2025/9/1 11:30:14

概述

GMTapSDK 是为 GameMaker Studio 开发的 TapTap SDK 扩展，提供了完整的 TapTap 平台功能集成，包括用户登录、防沉迷、内嵌动态、好友系统、成就系统、云存档和排行榜等功能。

版本信息

  • 扩展版本: 3.29.0
  • 支持的 TapSDK 版本: 3.29.0
  • 支持的 GameMaker 版本: 2023.1+
  • 支持平台: Android

快速开始

1. 安装扩展

  1. 下载 GMTapSDK 扩展包
  2. 在 GameMaker Studio 中导入扩展
  3. 确保扩展在项目中已启用

2. 基础配置

2.1 TapTap 开发者配置
  1. 在 TapTap 开发者中心 注册账号
  2. 创建应用并获取 Client ID 和 Client Token
  3. 配置应用的各项功能（防沉迷、成就、排行榜等）
2.2 Android 配置

扩展已自动配置必要的权限和依赖，无需手动修改 AndroidManifest.xml。

3. 初始化 SDK

// 在游戏启动时调用（通常在第一个房间的控制器对象中）
var client_id = "your_client_id";
var client_token = "your_client_token";
var server_url = "https://your-server.com";
var region_type = 0;  // 0=国内, 1=海外
var game_channel = "your_channel";
var game_version = "1.0.0";taptap_init(client_id, client_token, server_url, region_type, game_channel, game_version);

4. 事件处理

所有 TapSDK 的异步操作结果都通过 EVENT_OTHER_SOCIAL 事件返回：

// 在需要处理 TapSDK 事件的对象中添加 Other -> Async - Social 事件
if (ds_map_exists(async_load, "taptapType")) {var event_type = ds_map_find_value(async_load, "taptapType");var status = ds_map_find_value(async_load, "status");var message = ds_map_find_value(async_load, "message");switch (event_type) {case "INIT":if (status == "OK") {show_debug_message("TapSDK 初始化成功");// 可以开始登录流程} else {show_debug_message("TapSDK 初始化失败: " + message);}break;// 处理其他事件...}
}

功能模块详解

1. 用户登录系统

1.1 用户登录
// 启动 TapTap 登录流程
taptap_login();

返回事件:

  • taptapType: “LOGIN”
  • status: “OK” 或 “ERROR”
  • userData: 用户信息 JSON 字符串（成功时）

用户数据结构:

{"name": "用户昵称","avatar": "头像URL","openid": "用户OpenID","unionid": "用户UnionID","accessToken": "访问令牌"
}
1.2 检查登录状态
// 检查当前登录状态
var login_status = taptap_login_status();
// 返回值: "logged_in" 或 "not_logged_in"
1.3 用户登出
// 登出当前用户
taptap_logout();

返回事件:

  • taptapType: “LOGOUT”
  • status: “OK” 或 “ERROR”

2. 防沉迷系统

2.1 初始化防沉迷
// 初始化防沉迷系统
var client_id = "your_client_id";
var enable_tap_login = 1;  // 1=启用TapTap快速认证, 0=禁用
var show_switch_account = 0;  // 1=显示切换账号按钮, 0=隐藏taptap_anti_addiction_init(client_id, enable_tap_login, show_switch_account);

返回事件:

  • taptapType: “ANTI_ADDICTION_INIT”
  • status: “OK” 或 “ERROR”
2.2 启动防沉迷认证
// 启动用户认证流程
var user_identifier = "unique_user_id";
taptap_anti_addiction_startup(user_identifier);

返回事件:

  • taptapType: “ANTI_ADDICTION_STARTUP”
  • status: “OK” 或 “ERROR”
2.3 防沉迷回调处理
// 在事件处理中监听防沉迷回调
case "ANTI_ADDICTION_CALLBACK":var code = ds_map_find_value(async_load, "code");switch (code) {case "LOGIN_SUCCESS":show_debug_message("防沉迷登录成功");break;case "EXITED":show_debug_message("用户退出账号");break;case "DURATION_LIMIT":show_debug_message("游戏时长限制");break;case "PERIOD_RESTRICT":show_debug_message("时段限制");break;case "REAL_NAME_STOP":show_debug_message("实名认证中断");break;}break;
2.4 获取用户年龄段
// 查询用户年龄段信息
taptap_anti_addiction_get_age_range();

返回事件:

  • taptapType: “ANTI_ADDICTION_AGE_RANGE”
  • status: “OK” 或 “ERROR”
  • ageRange: 年龄段数值
  • ageDescription: 年龄段描述

3. 内嵌动态系统

3.1 获取新消息通知
// 获取用户的新消息通知
taptap_moment_fetch_notification();

返回事件:

  • taptapType: “MOMENT_FETCH_NOTIFICATION”
  • 可能收到 “MOMENT_GET_NOTICE_SUCCESS” 回调
3.2 打开动态页面
// 打开动态页面
var orientation = 0;  // 0=竖屏, 1=横屏
taptap_moment_open(orientation);
3.3 场景化入口
// 通过场景ID打开动态页面
var scene_id = "achievement_unlock";  // 场景标识
var orientation = 0;
taptap_moment_open_with_scene(scene_id, orientation);
3.4 发布动态
// 发布纯文本动态
var content = "刚刚完成了困难关卡！";
taptap_moment_publish(content, "");// 发布带图片的动态
var content = "看我的新装备！";
var image_path = "/sdcard/screenshot.png";
taptap_moment_publish(content, image_path);

返回事件:

  • taptapType: “MOMENT_PUBLISH”
  • 可能收到 “MOMENT_PUBLISH_SUCCESS” 或 “MOMENT_PUBLISH_FAIL” 回调
3.5 关闭动态页面
// 关闭当前显示的动态页面
taptap_moment_close();

4. 好友系统

4.1 注册好友状态监听器
// 注册好友状态变化监听器（游戏启动时调用一次）
taptap_friends_register_listener();

返回事件:

  • taptapType: “FRIENDS_LISTENER_REGISTERED”
  • 后续会收到好友状态变化事件：
    • “FRIENDS_ONLINE”: 好友上线
    • “FRIENDS_OFFLINE”: 好友下线
    • “FRIENDS_RICH_PRESENCE_CHANGED”: 好友状态变化
4.2 添加好友
// 申请添加好友
var user_id = "target_user_id";
var attributes = "{\"message\":\"想加你为好友\"}";  // JSON格式的附加信息
taptap_friends_add(user_id, attributes);

返回事件:

  • taptapType: “FRIENDS_ADD”
  • status: “OK” 或 “ERROR”
  • requestId: 好友申请ID（成功时）
4.3 好友申请管理
// 获取好友申请列表
taptap_friends_get_request_list();// 同意好友申请
var request_id = "申请ID";
taptap_friends_accept_request(request_id);// 拒绝好友申请
taptap_friends_decline_request(request_id);// 删除好友申请
taptap_friends_delete_request(request_id);
4.4 好友列表管理
// 获取好友列表
taptap_friends_get_list();// 删除好友
var friendship_id = "好友关系ID";
taptap_friends_delete(friendship_id);// 查询好友关系
var user_id = "用户ID";
taptap_friends_query_friendship(user_id);

好友列表数据结构:

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

5. 成就系统

5.1 初始化成就系统
// 注册成就回调监听器
taptap_achievement_register_callback();// 初始化成就数据
taptap_achievement_init();
5.2 获取成就数据
// 获取所有成就配置
taptap_achievement_fetch_all();// 获取用户成就进度
taptap_achievement_fetch_user();

返回事件:

  • taptapType: “ACHIEVEMENT_FETCH_ALL_SUCCESS” 或 “ACHIEVEMENT_FETCH_USER_SUCCESS”
  • achievementsList: 成就列表 JSON
  • achievementsCount: 成就总数
  • unlockedCount: 已解锁数量（用户成就）
5.3 成就解锁和进度
// 达成成就
var achievement_id = "first_victory";
taptap_achievement_reach(achievement_id);// 增长成就进度
var achievement_id = "kill_100_enemies";
var steps = 5;  // 增长步数
taptap_achievement_grow(achievement_id, steps);
5.4 成就界面
// 设置成就解锁提示
var show_toast = 1;  // 1=显示, 0=隐藏
taptap_achievement_set_show_toast(show_toast);// 显示成就界面
taptap_achievement_show_ui();

6. 云存档系统

6.1 创建和保存存档
// 创建存档对象
var summary = "第5关存档";
var description = "困难模式，进度75%";
var played_time = 3600;  // 游戏时长（秒）
var progress_value = 75;  // 进度百分比
taptap_gamesave_create(summary, description, played_time, progress_value);// 保存存档数据
var save_data = json_stringify({level: 5,score: 12345,items: ["sword", "shield", "potion"],player_position: {x: 100, y: 200}
});
taptap_gamesave_save(save_data);
6.2 查询存档
// 查询所有存档
taptap_gamesave_query_all();// 条件查询存档
var limit = 10;  // 限制数量
var skip = 0;    // 跳过数量
taptap_gamesave_query_by_condition(limit, skip);
6.3 加载和删除存档
// 加载指定存档
var save_id = "存档ID";
taptap_gamesave_load(save_id);// 删除存档
taptap_gamesave_delete(save_id);

存档数据结构:

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

7. 排行榜系统

7.1 提交成绩
// 提交成绩到排行榜
var leaderboard_name = "high_score";
var score = 12345;
var metadata = json_stringify({level: "hard",character: "warrior",timestamp: current_time
});
taptap_leaderboard_submit_score(leaderboard_name, score, metadata);
7.2 获取排名
// 获取用户在排行榜中的排名
var leaderboard_name = "high_score";
var user_id = "用户ID";
taptap_leaderboard_get_rank(leaderboard_name, user_id);
7.3 统计数据管理
// 更新用户统计数据
var statistic_name = "total_kills";
var value = 100;
var overwrite = 0;  // 0=累加, 1=覆盖
taptap_leaderboard_update_statistic(statistic_name, value, overwrite);// 获取用户统计数据
var user_id = "用户ID";
var statistic_names = "total_kills,total_deaths,play_time";
taptap_leaderboard_get_user_statistic(user_id, statistic_names);
7.4 获取排行榜结果
// 获取排行榜结果
var leaderboard_name = "high_score";
var skip = 0;     // 跳过数量
var limit = 10;   // 获取数量
var select_user_ids = "";  // 指定用户ID（可选）
taptap_leaderboard_get_results(leaderboard_name, skip, limit, select_user_ids);

完整示例

游戏启动流程示例

// obj_game_controller - Create 事件// 游戏状态
global.game_initialized = false;
global.user_logged_in = false;
global.systems_ready = false;// TapSDK 配置
global.client_id = "your_client_id";
global.client_token = "your_client_token";// 初始化 TapSDK
show_debug_message("初始化 TapSDK...");
taptap_init(global.client_id, global.client_token, "https://your-server.com", 0, "gm_channel", "1.0.0");// obj_game_controller - Other -> Async - Social 事件if (ds_map_exists(async_load, "taptapType")) {var event_type = ds_map_find_value(async_load, "taptapType");var status = ds_map_find_value(async_load, "status");switch (event_type) {case "INIT":if (status == "OK") {global.game_initialized = true;show_debug_message("TapSDK 初始化成功，开始登录流程");taptap_login();}break;case "LOGIN":if (status == "OK") {global.user_logged_in = true;var user_data = json_parse(ds_map_find_value(async_load, "userData"));show_debug_message("用户登录成功: " + user_data.name);// 初始化各个系统taptap_anti_addiction_init(global.client_id, 1, 0);taptap_friends_register_listener();taptap_achievement_register_callback();}break;case "ANTI_ADDICTION_INIT":if (status == "OK") {show_debug_message("防沉迷系统初始化成功");taptap_anti_addiction_startup("user_" + string(global.current_user_info.openid));}break;case "FRIENDS_LISTENER_REGISTERED":if (status == "OK") {show_debug_message("好友监听器注册成功");taptap_friends_get_list();}break;case "ACHIEVEMENT_CALLBACK_REGISTERED":if (status == "OK") {show_debug_message("成就回调注册成功");taptap_achievement_init();}break;case "ACHIEVEMENT_INIT_SUCCESS":show_debug_message("成就系统初始化成功");global.systems_ready = true;// 可以开始游戏主流程room_goto(rm_main_menu);break;}
}

游戏内功能使用示例

// 玩家完成关卡时
function on_level_complete(level_id, score, time_spent) {// 解锁成就if (level_id == 1) {taptap_achievement_reach("first_level_complete");}// 更新进度型成就taptap_achievement_grow("complete_levels", 1);// 提交成绩到排行榜taptap_leaderboard_submit_score("level_" + string(level_id), score, json_stringify({time: time_spent, difficulty: global.difficulty}));// 保存游戏进度save_game_progress();
}// 保存游戏进度
function save_game_progress() {var save_data = {current_level: global.current_level,total_score: global.total_score,unlocked_items: global.unlocked_items,player_stats: global.player_stats,save_time: date_current_datetime()};taptap_gamesave_create("关卡 " + string(global.current_level), "总分: " + string(global.total_score), global.total_play_time, (global.current_level / global.max_levels) * 100);taptap_gamesave_save(json_stringify(save_data));
}// 分享成就到动态
function share_achievement_to_moment(achievement_name) {var content = "我在游戏中解锁了成就：" + achievement_name + "！";taptap_moment_publish(content, "");
}

错误处理和调试

常见错误处理

// 在事件处理中添加错误处理
if (status == "ERROR") {var message = ds_map_find_value(async_load, "message");switch (event_type) {case "INIT":show_debug_message("SDK初始化失败: " + message);// 可以尝试重新初始化alarm[0] = 300;  // 5秒后重试break;case "LOGIN":show_debug_message("登录失败: " + message);// 显示登录失败提示，允许用户重试break;case "FRIENDS_ADD":show_debug_message("添加好友失败: " + message);// 可能是用户ID无效或网络问题break;default:show_debug_message("操作失败 [" + event_type + "]: " + message);break;}
}

调试技巧

  1. 启用详细日志:
// 在游戏开始时启用调试模式
global.debug_mode = true;// 在事件处理中记录详细信息
if (global.debug_mode) {show_debug_message("收到事件: " + event_type);show_debug_message("事件数据: " + json_stringify(async_load));
}
  1. 网络状态检查:
// 检查网络连接状态
if (os_is_network_connected()) {// 网络正常，可以调用网络相关接口
} else {show_debug_message("网络连接不可用");
}
  1. 状态验证:
// 在调用接口前验证状态
function safe_call_tapsdk_function() {if (!global.game_initialized) {show_debug_message("错误：TapSDK 未初始化");return false;}if (!global.user_logged_in) {show_debug_message("错误：用户未登录");return false;}return true;
}

性能优化建议

1. 事件处理优化

// 避免在事件处理中进行复杂计算
// 使用异步处理大量数据
if (event_type == "FRIENDS_GET_LIST" && status == "OK") {var friends_list = ds_map_find_value(async_load, "friendsList");// 将数据处理放到下一帧global.pending_friends_data = friends_list;alarm[1] = 1;  // 下一帧处理
}// Alarm 1 事件
if (global.pending_friends_data != "") {process_friends_data(global.pending_friends_data);global.pending_friends_data = "";
}

2. 内存管理

// 及时清理不需要的数据
function cleanup_tapsdk_data() {// 清理临时数据if (ds_exists(global.temp_achievement_data, ds_type_list)) {ds_list_destroy(global.temp_achievement_data);}// 清理过期的缓存数据if (current_time - global.last_friends_update > 300000) {  // 5分钟global.cached_friends_list = "";}
}

3. 网络请求优化

// 避免频繁的网络请求
global.last_notification_check = 0;function check_moment_notifications() {if (current_time - global.last_notification_check > 60000) {  // 1分钟间隔taptap_moment_fetch_notification();global.last_notification_check = current_time;}
}

常见问题解答

Q: 如何处理用户拒绝登录？

A: 在 LOGIN 事件的错误处理中，可以显示友好的提示信息，并提供重试选项。某些功能可以在未登录状态下使用。

Q: 防沉迷系统如何影响游戏流程？

A: 监听防沉迷回调事件，根据不同的状态码采取相应措施，如暂停游戏、显示提示信息或强制退出。

Q: 如何处理网络连接问题？

A: 实现重试机制，检查网络状态，并向用户显示适当的错误信息。可以缓存一些数据以支持离线模式。

Q: 成就系统的成就ID从哪里获取？

A: 成就ID需要在 TapTap 开发者后台配置，然后在游戏中使用相同的ID来解锁成就。

Q: 云存档有大小限制吗？

A: 是的，云存档有大小限制。建议只保存关键的游戏进度数据，避免保存大量的资源文件。

更新日志

版本 3.29.0

  • 支持最新的 TapSDK 3.29.0
  • 新增排行榜系统完整支持
  • 优化事件系统性能
  • 修复已知问题

版本 3.28.0

  • 新增云存档功能
  • 完善成就系统
  • 优化好友系统稳定性

技术支持

如果在使用过程中遇到问题，请：

  1. 检查本文档的常见问题部分
  2. 确认 TapTap 开发者后台配置正确
  3. 查看 GameMaker 输出窗口的错误信息
  4. 联系技术支持并提供详细的错误日志

本文档持续更新中，请关注最新版本。

http://www.xdnf.cn/news/19389.html

相关文章：

  • 【开题答辩全过程】以 基于springboot的垃圾分类管理系统为例，包含答辩的问题和答案
  • LSTM原理理解
  • 8.29学习总结
  • 大语言模型（LLM）简介与应用分享
  • Linux-数据库
  • 旅游景点库系统的设计与实现（代码+数据库+LW）
  • 力扣hot100:轮转数组（常规思路与三步反转讲解）（189）
  • mmaction安装的详细说明帖
  • 王立群《读史记-刘邦》读书笔记
  • 嵌入式C学习笔记之编码规范
  • 数学分析原理答案——第七章 习题12
  • AI大模型实战解析-RAG知识库+LangChain项目实战
  • Linux系统的进程管理
  • Unity3D Gizmos 调试可视化
  • Qt中UDP回显服务器和客户端
  • 第二十七天-ADC模数转换实验
  • python反转字符串
  • 三维重建模型、3DGS、nerf、 mip-nerf
  • 《WINDOWS 环境下32位汇编语言程序设计》第9章 通用控件（2）
  • 点接触混合润滑完整数值解
  • 免税商品优选购物商城系统|java技术开发
  • MATLAB R2010b系统环境（三）MATLAB操作界面
  • JavaWeb01
  • 【Linux】创建线程
  • 基于K8s部署Redis高可用
  • mit6.031软件构造 笔记 Testing
  • Redis进阶（上）
  • Win11输入法异常解决方案
  • 智能合约安全全解析：常见漏洞、真实案例与防范实践
  • 机器视觉学习-day14-绘制图像轮廓