须知

介绍使用 PlayNANOO REST API 时必须了解的重要事项。

示例代码说明

本文档中包含的示例代码仅供参考，旨在帮助理解 PlayNANOO API 的集成方式。 在实际项目中应用时，请根据项目的架构和编码规范自由修改后使用。

必需请求头

所有 API 调用时必须包含以下请求头。

请求头	说明	必需
X-Playnanoo-Key	在控制台中获取的 Service Key	O
X-Playnanoo-Id	在控制台中获取的 Game ID	O
Authorization	Bearer {access_token} 格式（需要认证的 API）	△
Content-Type	application/json	O

认证信息获取

请在控制台 > 频道 > 设置 > API & 平台管理中获取 Game ID、Service Key、Secret Key。

公共请求参数

大多数 API 都需要以下设备信息。为了避免每次请求都手动输入，建议继承基础环境设置中提供的 DeviceInfo 类来使用。

参数	类型	说明
uuid	string	玩家唯一 ID（登录后获取）
nickname	string	玩家昵称
device_id	string	设备唯一 ID
version	string	应用版本
platform	string	平台（aos、ios）
device_model	string	设备型号
device_os	string	设备 OS 版本
device_language	string	设备语言（KO、EN 等）
device_country	string	国家代码（KR、US 等）
device_timeoffset	string	UTC 时间偏移量（秒）

认证令牌管理

Access Token

• 登录成功时签发
• API 请求时包含在 Authorization 请求头中
• 过期时使用 Refresh Token 刷新

Refresh Token

• 用于刷新 Access Token
• 有效期比 Access Token 更长
• 过期时需要重新登录

令牌刷新流程

1. API 调用 → 401 Unauthorized 响应
2. 使用 Refresh Token 调用 /token/refresh
3. 获取新的 Access Token
4. 重新调用原始 API

错误响应格式

API 调用失败时将以以下格式返回响应。

{
  "ErrorCode": "에러 코드",
  "Message": "에러 메시지"
}

主要 HTTP 状态码：

• 400 - 错误请求（参数错误）
• 401 - 认证失败（令牌过期/无效）
• 403 - 无权限
• 404 - 资源不存在
• 500 - 服务器错误

注意事项

Secret Key 安全

Secret Key 绝对不要硬编码在客户端代码中。请仅在服务器端使用，或通过环境变量进行管理。

速率限制

过度调用 API 时可能会被暂时封锁。请保持适当的调用间隔。

下一步

• Unity 基础环境设置 - Unity 项目设置方法
• Unreal 基础环境设置 - Unreal 项目设置方法