项目组接入指南

游戏项目接入、联调、验证和上线前检查的实际操作说明。

Entries

实际入口

用途 入口 说明
主入口analytics.gamezipper.com项目组日常从这里进入。
事件采集collect.gamezipper.com/v1/batch客户端和服务端统一批量上报。
管理后台admin.gamezipper.com/admin创建 API Key、看最近事件和事件字典。
BI 看板bi.gamezipper.com查看 DAU、留存、收入、广告和 LTV。
行为分析posthog.gamezipper.com查看漏斗、路径、分群、用户详情和实验。

管理员登录凭据

Admin 后台使用 Admin Token 登录，不是账号密码。Metabase 和 PostHog 使用邮箱和密码登录。

X-Admin-Token 是接口请求头名称，不是实际 Token 值；不要把它输入到 Admin 页面。

优先由平台负责人在服务器生成 Admin 自动登录链接，项目负责人打开链接后，页面会自动保存 Token、完成登录，并清理地址栏里的 Token。

cd /home/msdn/gamezipper/app/deploy
bash scripts/show_credentials.sh --admin-login-link

自动登录链接包含 Admin Token，只能通过受控私有渠道发送。手动复制 Token 仅作为备用方案，真实默认凭据保存在服务器私有文档：

/home/msdn/gamezipper/private/PROJECT_TEAM_ADMIN_CREDENTIALS_ZH.md

该文件权限为 600，只应通过受控渠道给项目负责人或平台管理员，不应提交到 GitHub、公开文档、聊天群截图或客户端工程。

Before Integration

接入前准备

项目信息

准备游戏名称、game_id、app_id、环境、平台、负责人和预计事件量。

API Key

测试包使用 test Key，正式包使用 prod Key。Key 泄露后立即撤销并重新创建。

隐私字段

不要上报手机号、邮箱、身份证、登录 Token、支付凭证等敏感明文。

Workflow

实战接入流程

  1. 创建 API Key在 Admin 后台按游戏、应用和环境创建独立 Key。
  2. 验证配置用 /v1/config 确认 Key 对应的 game_id/app_id/env 正确。
  3. 接入 SDK 或 Batch API客户端和服务端统一上报到 collect.gamezipper.com/v1/batch。
  4. 跑真实游戏流程覆盖安装、打开、会话、关卡、广告、内购、货币和道具事件。
  5. 三处验收Admin 看最近事件，Metabase 看经营指标，PostHog 看行为分析。

Batch API 最小示例

curl -X POST https://collect.gamezipper.com/v1/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "events": [{
      "event_name": "level_complete",
      "event_id": "2f56ed4d-e8a0-4b29-9b46-ef6bc25f8d30",
      "player_id": "player_10001",
      "install_id": "install_abcd",
      "session_id": "session_001",
      "platform": "ios",
      "app_version": "1.0.0",
      "properties": {"level_index": 3}
    }]
  }'

Acceptance

项目组验收清单

检查项入口通过标准
Key 配置/v1/config返回正确 game_id/app_id/env。
事件上报/v1/batch返回 accepted=1，重复事件能去重。
最近事件Admin5 分钟内能看到测试事件和身份字段。
经营指标Metabase当天数据能进入看板查询范围。
行为分析PostHog测试流程能进入漏斗、路径和事件查询。