Godot 快速接入

目标读者：需要在 Godot 4.x 项目中接入反馈面板的开发者。

本快速接入假设 addon 已复制到 res://addons/echo_nebula_feedback/，并已在 Godot 插件面板启用。插件会注册名为 EchoNebulaFeedback 的 autoload 单例。

启用插件后，先在游戏根目录把 quickstart.gd.txt 复制为 quickstart.gd，再配置并挂载。文本模板不会在 autoload 尚未注册时被引擎解析。

完整配置示例

稳定的最小示例只包含 canonical 核心；下面的完整示例额外展示可选运行时上下文和功能控制。

以下扩展调用应放入已有游戏函数。需要可以直接挂到新 Node 的完整脚本时，使用固定 ZIP 的 quickstart.gd 和主 Quickstart。

EchoNebulaFeedback.configure({
  "project_key": "enb_pk_xxx",
  "public_api_base_url": "http://localhost:4000",
  "environment": "local",
  "release": "0.1.0",
  "build_id": "dev-build-001",
  "locale": "auto",
  "enable_screenshot": true,
  "enable_recent_logs": true,
  "enable_breadcrumbs": true,
  "offline_queue": true,
  "hotkey": KEY_F8
})

EchoNebulaFeedback.set_player({
  "player_id_hash": "sha256:337180dda29405211bf7a37ea531367110370dc54db2298fcf4450f1749badb3"
})

EchoNebulaFeedback.set_context({
  "scene": "res://scenes/main.tscn",
  "level": "demo"
})

EchoNebulaFeedback.open_feedback_panel({ "trigger_source": "button" })

enable_screenshot 和 enable_recent_logs 只表示面板中开放这些选项，不代表默认勾选同意。玩家仍必须手动勾选后，SDK 才会上传截图或最近日志。

SDK 会在 configure() 后使用 Project Key 通过 GET /v1/sdk/config 读取 SDK config，也可以通过 refresh_sdk_config() 主动刷新。玩家提交后，SDK 会生成 feedback_report payload，提交到 Public API 的 POST /v1/feedback/reports；如果玩家主动勾选了附件，SDK 会使用返回的 feedback_id 上传到 /v1/feedback/reports/{feedback_id}/attachments。API 不可用时，offline_queue 会保留 payload 以便稍后刷新。管理操作仍在 /admin/v1/* 下，必须使用开发者登录态。

常见错误

• Project Key 可以读取 Public API SDK 配置，并提交反馈或经 consent 授权的附件；它绝不能读取 Admin API 反馈数据或执行管理操作。
• 如果玩家未勾选截图，SDK 不应上传截图附件。
• 如果玩家未填写联系方式，payload 不应包含联系方式。
• 不要把 feedback_payload_ready 事件当作已送达证明；需要通过 Admin API 或 Developer Console 确认 report 和附件已经到达。

下一步

阅读 安装 Godot addon。