安然游戏盾

准备游戏盾配置

创建有效套餐，配置启用的 TCP 转发规则，确认源站地址和端口，并确认套餐已分配可用节点、源站防火墙允许节点回源。

在 SDK 开发集成页面获取套餐编号和 SDK 密钥，再下载对应平台 SDK。sdk-settings.json 已绑定当前游戏盾但不包含 SDK 密钥，不要混用不同游戏盾的配置文件。

统一客户端启动流程

1. 从应用资源读取 sdk-settings.json，运行时取得套餐编号和 SDK 密钥。
2. 初始化 SDK；需要自动换端口时，在启动前开启该选项。
3. 在后台线程启动 SDK，等待就绪后枚举全部本地虚拟端点。
4. 让游戏连接 SDK 返回的主机、端口和协议，不要连接旧源站或旧入口。
5. 网络切换、休眠恢复或规则变化后检查状态，必要时重启 SDK 并重新读取端点。

不要写死 127.0.0.1:25566 或其他本地端口。启用自动换端口后，以 SDK 实际返回值为准。

Windows · C/C++

#include "GameShieldSDK.h"

GS_Endpoint endpoint{};
endpoint.struct_size = sizeof(endpoint);
if (GS_Initialize("sdk-settings.json", subscriptionId, sdkKey) == GS_OK) {
    GS_SetAutoChangePort(1);
    if (GS_Start() == GS_OK && GS_GetEndpointCount() > 0) {
        GS_GetEndpoint(0, &endpoint);
        // 业务连接 endpoint.host / endpoint.port / endpoint.protocol
    }
}

GS_Start 不要放在 UI 主线程。失败时用 GS_GetLastError 记录错误类别，日志中不得写入 SDK 密钥。

Android · Kotlin

把 GameShieldSDK.aar 放入 app/libs/，把配置文件放入 app/src/main/assets/，并声明 INTERNET 和 ACCESS_NETWORK_STATE 权限。

val settings = context.assets.open("sdk-settings.json")
    .bufferedReader().use { it.readText() }
val client = GameShieldClient.create(context, settings, subscriptionId, sdkKey)
client.setAutoChangePort(true)
client.start() // Dispatchers.IO
val endpoint = client.endpoints().first()
// 业务连接 endpoint.host / endpoint.port / endpoint.protocol

应用回到前台时检查 isReady()；网络切换后可调用 restart() 并重新读取端点。

iOS · Swift

将 GameShieldSDK.xcframework 加入 Target，把 sdk-settings.json 加入 Copy Bundle Resources，并确认 Target Membership。

let client = try GameShieldClient(
    serialNumber: subscriptionId,
    sdkKey: sdkKey
)
try client.setAutoChangePort(true)
try await Task.detached { try client.start() }.value
guard let endpoint = try client.endpoints().first else {
    throw ProtectedConnectionError.noEndpoint
}
// endpoint.virtualIp / virtualPort / protocol

回到前台后检查 isReady，异常时调用 restart() 并重新获取端点。

安全与上线验收

• 不要把 SDK 密钥写入源码、EXE/APK/IPA 明文资源、命令行或日志，推荐运行时由受保护会话下发。
• 不要关闭证书、指纹或路由签名校验；重新生成密钥后旧密钥会失效。
• 验证登录、选服、进服、重连、多业务端口、端口占用自动换端口、网络切换和规则更新。
• 确认业务连接目标是 SDK 返回的本地端点，并在控制台查看在线终端与连接记录。