GMTapSDK 扩展使用文档

概述

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));
}

2. 网络状态检查:

// 检查网络连接状态
if (os_is_network_connected()) {
    // 网络正常，可以调用网络相关接口
} else {
    show_debug_message("网络连接不可用");
}

3. 状态验证:

// 在调用接口前验证状态
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. 联系技术支持并提供详细的错误日志

---

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