Ravensight Godot SDK

Official Godot 4 SDK for Ravensight: player analytics for indie games. One autoload script gives your game:

• Batched event tracking with an offline queue and automatic retry. It keeps up to 500 events queued while offline.
• Session management: a random device id, a publishable ingest key, token refresh
• Rate-limit aware: honours 429 and Retry-After, backs off when offline
• Server kill switch: disable tracking remotely without shipping a patch
• Player privacy: a random per-install device id, no advertising identifier, set_tracking_enabled(false) (saved) and reset_device_id() for games that show their own consent or settings screen; no tracking permission prompt needed. What your store label can say: https://ravensight.io/docs/#privacy-label
• In-game player feedback: bug reports and ratings straight from players
• Suggestions API (experimental): machine-readable tuning hints derived from Ravensight's weekly AI analysis

Version 0.3.0. See CHANGELOG.md for what changed. Shipping a build anyone can download? Read "Public builds" below.

Install

1. Copy Ravensight.gd into your project (e.g. res://addons/ravensight/).
2. Project > Project Settings > Autoload: add it, named Ravensight.
3. Set your game's ingest_key (gt_live_..., from the Ravensight dashboard) before Ravensight's _ready() runs: edit the default at the top of Ravensight.gd, set it from an autoload listed above Ravensight, or set the project setting ravensight/ingest_key. The same goes for every option below. With no key the SDK is inert (see "Public builds").

The ingest key is publishable and safe to ship in your binary: it can open sessions, read the tracking kill switch and read this game's design suggestions. It cannot read analytics or feedback, or manage your account.

Use

Ravensight.track_event("level_start", {"level": "level_3"})
Ravensight.track_event("player_died", {"level": "level_3", "cause": "spikes"})
Ravensight.submit_feedback("The boss feels unfair", "complaint", 2)

track_event() only queues. Events go out in batches of up to 50: 5 seconds (flush_interval) after the first waiting event, at once when 50 are waiting, on flush(), when the app goes to the background, and on quit. It is safe to call from any autoload, even before Ravensight's own _ready(): such events wait for the opt-out and kill switch checks.

Options

Option	Default	Notes
api_url	https://api.ravensight.io	With or without /api/v1, with or without a trailing slash. Empty means the default. api_base() returns the normalised root.
ingest_key	""	Your game's publishable gt_live_ key, or a public gt_pub_ key. Empty falls back to the project setting ravensight/ingest_key; empty there too, the SDK is inert for the run.
optional	false	true silences the one warning an inert start (no key) prints.
consent	"opt_out"	"opt_in" sends nothing, and makes no device id, until set_tracking_enabled(true). See Public builds.
distribution	""	A short label for this build, such as "native-demo" or "web-itch", sent on the session. At most 40 characters, no control characters, otherwise not sent.
game_version	1.0.0	Sent with every session.
enabled	true	false turns the SDK off for this run: no request of any kind, nothing queued, no game_started, until set_enabled(true). Never saved. set_tracking_enabled() still saves the player's choice while it is false.
max_queue_size	500	Unsent events kept, in memory and on disk, at most 500. The oldest are dropped first; this run's game_started is kept.
flush_interval	5.0	Seconds an event waits so it can go out with others. 50 waiting events go at once.
handle_quit	true	Take over the window close (and the Android back button when it quits) to send the last events, holding the quit at most 1.5 seconds. See Quitting.
performance	false

This is the beginning of the README. Read the rest at the original. Read the full README ↗