Echo Nebula Feedback ドキュメント

信頼できるローカル送信

対象読者：オフライン、再起動、添付の部分的な結果を検証する開発者。

Godot SDK は容量に上限のある一つのローカルキューを使います。有効な場合、最初の HTTP リクエストより前に、確定したレポートをアトミックに保存します。ディスクや容量のエラーでは送信を停止し、保存成功とは表示しません。明示的なローカル設定 offline_queue: false、または検証済みのプロジェクト設定 false は新しい内容の保存を禁止します。その場合、スクリーンショットはメモリにのみ置かれ、プロセス終了後に復元できません。

最小例

EchoNebulaFeedback.configure({
  "project_key": "enb_pk_xxx",
  "public_api_base_url": "http://localhost:4000",
  "offline_queue": true,
  "max_offline_queue_items": 100,
  "max_offline_queue_attempts": 3,
  "max_offline_queue_bytes": 67108864
})

初期値は送信待ち100件、デッドレター100件、管理対象の記録と添付の合計64 MiB、レポートまたは添付ごとに3回です。設定の上限は各保存先100件、各段階10回、256 MiBで、バイト予算の下限は8 KiBです。進捗をアトミックに保存するための空きも確保します。満杯の場合は新規投稿を拒否し、送信待ちのレポートを追い出しません。古いデッドレターは削除されることがあります。予算を現在の使用量より小さくすると、空き容量または予算を回復するまで送信が止まる場合があります。

確認と再起動

送信操作はスクリーンショットの待機より前に一度だけロックされ、レポートID、本文、コンテキスト、言語、consents を固定します。撮影中に閉じると未完了の操作を取り消します。保存後にパネルやゲームを閉じても、同じ内容に新しいレポートIDは生成しません。

レポートの feedback_id を受信したら、添付より先に保存します。添付ごとに冪等キー、内容のハッシュ、試行数、確認済みIDを記録します。再起動後は確認済みの段階を飛ばし、未確認のリクエストだけを元の内容とキーで再送します。応答が失われると HTTP リクエストは増えることがありますが、サーバーの冪等性によりレポートや添付は一件に保たれます。ゲーム外の送信サービスはありません。

feedback_payload_ready は準備した内容の通知です。受信の事実には、本文を含まない feedback_delivery_changed(result) を使います。

状態 意味
sending 条件を満たすリクエストを送信する段階で、受信は未確認です。
queued 端末に保存済みで、送信条件または再試行を待ちます。
partial レポートは受信済みですが、一部の添付は未確認です。retryable は自動復元を続けるかを示します。添付のために再投稿しないでください。
succeeded レポートと選択したすべての添付に確認済みの受信IDがあります。
failed 完全な結果を確認できないまま送信が停止しました。サーバーが何も受信していないとは限りません。

結果には client_report_id、feedback_id、state、retryable、reason、attachments_total、attachments_accepted、attachments_failed が含まれます。本文、連絡先、ログ、Key、ローカルパス、署名URLは含まれません。完全な payload やキューJSONをログに出力しないでください。チームの処理状態は new/reviewing/resolved/ignored/archived のままで、Console はサーバーで確認済みの記録と添付だけを表示します。

ネットワークエラー、408、429、5xxは保存済みの予算内で再試行し、秒数と HTTP 日付形式の Retry-After を守ります。他の4xx、ローカルファイルの欠落・空・変更、試行数の上限では停止し、部分的な受信情報は残します。進捗の書き込みに失敗すると、SDKの再設定または再起動まで停止し、最後に保存できた記録を上書きしません。設定取得は最大10回です。継続的な設定障害を解決した後は refresh_sdk_config() を呼べます。送信処理中の更新は false を返す場合があります。

プロジェクトの所属

記録は正規化した endpoint、判明していればサーバーで確認した project ID、不可逆な Project Key の指紋に結び付けます。Key本体は保存しません。所属が既知の記録では、設定取得が同じプロジェクトと endpoint を確認した後にだけ、代替Keyで再開できます。異なるプロジェクトや endpoint に旧内容を自動転送しません。

最初の設定取得がオフラインの場合、最小限の記録を保存するかはローカルのキュー設定に従います。プロジェクトの方針が確認できるまでは任意データの操作を使えません。project ID を推測せず、元のKeyの指紋と endpoint で設定が取得できた場合にだけ所属を確定します。未確認Keyを変更すると、代替Keyが同じプロジェクトでもその記録は移行できません。認証情報を付けて HTTP リダイレクトを追いません。

端末での7日間とファイル

未送信・失敗したローカルレポート、デッドレター、管理対象の添付は、最初の保存から**最長7日（604800秒）**です。先に保存されていた添付がある場合は期限が早くなります。再試行、再登録、Key変更、デッドレターへの移動では延長しません。期限切れはリクエスト前に拒否し、SDKの起動時と実行中に削除します。ゲームツリーの一時停止や時間倍率ゼロでも動作します。ゲーム終了中はコードが動かないため、物理的な削除は次回起動を待ちます。外部のバックグラウンド削除サービスはありません。

無効な時刻や時計の巻き戻りでは、新しい保存期間を与えず保守的に停止します。保存先が削除を拒否すると cleanup_failed を通知し、期限切れデータを再送せず、実行中に削除を再試行します。削除成功とは表示しません。この期限はサーバー受信済みデータを削除・変更しません。サーバーの保存期間は別の方針です。

SDKは user://echo_nebula_feedback/queue/、dead_letter/、attachments/ を管理します。ホストゲームのファイルをここに置かないでください。検証済みの直下ファイルだけを管理し、パス越境やシンボリックリンクを拒否します。起動時に管理対象の孤立ファイルを、実行中にも放置された一時ファイルを削除します。現在のv3形式でも、凍結した送信内容・段階別受領情報・プロジェクトへの結び付き・7日間の上限を維持します。旧v1/v2は検証済みSDK専用パスから削除し、移行も送信もしません。削除が拒否された場合は送信せず cleanup_failed を報告し、ローカル削除が成功するまで再試行します。読めない内容から残すのは、元の本文を含まない有界の診断だけです。

検証

SDKで ./scripts/check-sdk-alpha.sh と GODOT_BIN=/path/to/godot ./scripts/run-godot-headless.sh を実行します。Pythonツールは現在のpayload fixtureだけを作成し、キューとクラッシュ復元は実際のGodotで検証します。

Infraの node scripts/e2e-worktree-isolated.mjs --g2-sdk は専用の一時 API/PostgreSQL/MinIO/Console スタックを作り、実際のAddonで応答の消失、プロセス強制終了、添付復元、所属分離、期限切れ、ディスク障害を試験します。--g2-native を追加するとマウス操作を必要とするネイティブウィンドウも実行します。コミット後のcanonical検証は引き続き ./scripts/e2e-fresh-stack.sh で、clean gateは変更しません。実行証拠は試験したデスクトップエンジンに限られ、全プラットフォームやエクスポート済みゲームの対応を約束しません。

よくある間違い

次のステップ

プライバシーと同意とトラブルシューティングを参照してください。