Ravensight.gd
One autoload script. It owns device identification, session
creation, batching, retries, and the offline queue, so your game code
only ever needs to call track_event().
Code samples scroll horizontally when needed. Focus a sample and use the arrow keys, or swipe to read a long line.
Options
Set these before Ravensight's _ready() runs: edit the
defaults at the top of Ravensight.gd, or set them from an
autoload listed above Ravensight.
| Property | Type | Default | Notes |
|---|---|---|---|
api_url | String | 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 | String | gt_live_your_ingest_key_here | The publishable key from your game's confirmation screen. |
game_version | String | 1.0.0 | Sent with every session. |
enabled | bool | 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 | int | 500 | Unsent events kept. The oldest are dropped first; a queued game_started is kept. |
flush_interval | float | 5.0 | Seconds an event waits so it can go out with others. 50 waiting events go at once. |
handle_quit | bool | true | The SDK sets auto_accept_quit to false, flushes on a close request (and the Android back button when quit_on_go_back is on), then calls get_tree().quit() itself within 1.5 seconds. Set false if your game has its own "really quit?" dialog; the SDK then only flushes on a close request, and your dialog calls Ravensight.quit(). |
session_timeout | float | 1800.0 | Android and iOS only: seconds in the background after which the session counts as over. See Automatic events. |
Public functions
| Function | Description |
|---|---|
track_event(event_name: String, data: Dictionary = {}) | Queue an event. It only queues: events go out in batches of up to 50, flush_interval seconds after the first waiting event, at once when 50 are waiting, on flush(), when the app goes to the background, and on quit. Safe to call from any autoload, even before Ravensight's own _ready(). |
flush() | Send what is queued now instead of waiting for the timer. Cuts a backoff wait short; a server's Retry-After wait still holds. |
quit(exit_code = 0) | Send game_exited and the queue, then quit. Call it from your own Quit button instead of get_tree().quit(). |
submit_feedback(message: String, category: String = "", rating: int = 0) | Send player feedback. category is optional and one of FEEDBACK_CATEGORIES: bug, suggestion, complaint, praise, playtest, other. rating is 0 to leave it out, or a whole number from 1 to 5. Anything else fails at once with invalid_category or invalid_rating and no request is made. Needs an open session; unlike track_event(), a call made before one exists fails immediately rather than queueing. |
set_tracking_enabled(on: bool) | The player's opt-out, saved across launches. See Player privacy below. |
is_tracking_enabled() | true while events are collected: enabled, not opted out, kill switch on. |
reset_device_id() | Start a fresh analytics identity for this install. Returns the new id. |
set_enabled(on: bool) | The game's own switch for this run (see enabled). |
get_status_reason() | Why nothing is being sent, or "". See Startup and failures. |
api_base() | The API root requests go to, for example https://api.ravensight.io/api/v1. |
is_playtest() | true in a run driven by the Ravensight playtest runner. |
set_playtest_context(ctx) | Puts a running game into playtest mode. The SDK already does this from the playtest runner's variables, so a game never needs to call it by hand. |
track_ad(network, format, result, options = {}) | Queue an ad lifecycle step as an ad typed event. Returns false and sends nothing when a field is malformed. |
track_ad_revenue(network, format, placement, revenue_micros, currency) | Queue a paid impression (result shown). Revenue is a digit string of whole micros. |
micros_from_decimal_string(text), micros_from_revenue(value) | Revenue as a micros digit string, without multiplying a float. |
set_attribution(attribution) | Queue where this install was acquired, once per install. |
get_device_id() | This install's random device id, for an attribution partner's customer user id. |
get_delivery_stats() | Events let go of since launch: dropped_overflow, dropped_too_old and dropped_refused. |
fetch_suggestions() | Experimental. Answers on suggestions_received; while tracking is off nothing is requested and it answers with an empty list. |
Ravensight.tracking_enabled is read-only and gives the
same answer as is_tracking_enabled().
Ravensight.session_token is the open session's token, or
"" until one opens. If your game server should report
into the player's session, hand it this token and have it send it as
joinToken when it opens its own session (see the
HTTP API). The SDK never computes a session id
itself.
Signals
| Signal | Fires when |
|---|---|
session_ready | A session is open. |
session_failed(reason: String) | Opening a session failed: "invalid_key" for a refused key, otherwise the server's error code or "offline". Retried for you unless the key was refused. |
tracking_disabled(source: String) | "server" for the kill switch, "player" after an opt-out, "init" when enabled is false or after set_enabled(false). |
status_changed(reason: String) | get_status_reason() changed. |
events_flushed(count: int) | A batch was accepted. count is the number sent, which can be more than the server stored: an event timestamped more than 90 days ago is dropped (see HTTP API). |
flush_failed(reason: String) | A batch failed. It is retried for you, except events the server refuses with a 400, or one event refused with a 413, which are dropped. "event_too_large" for an event whose data is over 8,192 bytes as JSON, dropped before it was queued. |
feedback_submitted | Feedback was accepted. |
feedback_failed(reason: String) | Feedback failed: "disabled", "empty_message", "invalid_category", "invalid_rating" or "no_session" before sending (no request is made), or the server's error code. |
suggestions_received(suggestions: Array) | Experimental. Carries the result of fetch_suggestions(). |
event_tracked(event_name: String, data: Dictionary) | Every time track_event() queues an event, with the data actually queued (playtest tags included in a playtest run). Use it to mirror tracked events elsewhere in the running game. |
func _ready():
Ravensight.session_ready.connect(func(): print("ready"))
Ravensight.session_failed.connect(func(reason): print("session failed: ", reason))
Ravensight.tracking_disabled.connect(func(source): print("tracking off: ", source))
Ravensight.status_changed.connect(func(reason): print("status: ", reason))
Ravensight.events_flushed.connect(func(count): print("sent ", count, " events"))
Automatic events
The SDK sends exactly two events by itself:
game_started, once per session. It is queued at launch, first in the queue with the launch time, and sent once the kill switch check allows it. It is never queued while the SDK is disabled or the player has opted out; a game enabled later in the run queues it then, once.game_exited, once, when the game quits throughRavensight.quit(), or through the window close or the Android back button when the SDK handles that quit (handle_quit). Losing focus on a desktop is not an exit: it only sends what is queued.
Android and iOS. Going to the background tries to
send what is queued and saves a small marker
(user://ravensight_bg.save); no event is sent. Back in the
foreground within 30 minutes (session_timeout), nothing
happens. After 30 minutes or more, the old session gets
game_exited stamped with the moment the app went to the
background, and a new session starts with game_started.
If the player swipes the app away while it is in the background, the
next launch sends that game_exited from the marker (one
attempt, before anything else) and deletes the marker.
Web export. The browser gives a Godot web game no
close notification, so a web build never sends
game_exited. game_started and everything you
track are sent as usual.
From your own Quit button, call Ravensight.quit() instead
of get_tree().quit(), which quits at once and sends no
game_exited:
func _on_quit_pressed() -> void:
Ravensight.quit()
Startup and failures
get_status_reason() says why nothing is being sent, and
status_changed fires when that changes.
| Reason | Meaning |
|---|---|
"" | Nothing is wrong: a session is open, or opening normally. |
disabled | enabled is false, or the player opted out. |
invalid_key | The server refused the ingest key (401, or a 403 that is not one of the codes below). Logged once as Ravensight: ingest key refused (invalid_key), sending stopped for this run. Check your gt_live_ key. Nothing more is sent or retried this run; the queued events stay on disk for the next launch. A 401 on a batch is an expired session instead: the SDK opens a new session once, and a second 401 in a row waits for the backoff. |
tracking_disabled | The kill switch is off for your game. Nothing more is sent this run; the queued events stay on disk. |
offline | No answer (no connection, or no reply within 15 seconds). Retried after 10 seconds, doubling up to 5 minutes, each wait multiplied by a random factor from 0.5 up to 1; events are kept. |
rate_limited | The server said slow down (429, or 503 with Retry-After). The SDK waits exactly the Retry-After time. |
session_failed | Opening a session failed for another reason (retried with the same backoff), or a playtest token was refused. |
playtest_job_closed | The playtest job this run belongs to has closed. Nothing more is sent. |
Delivery
- Saved queue. Unsent events are written to
user://ravensight/queue-<16 hex>.json, one file per ingest key, through a temporary file renamed over the old one. The file is read once when sending starts. At most 500 events are kept across launches, oldest dropped first, and events older than 89 days are dropped when it is read. An event leaves the file only after a 2xx answer, or a 400 that refuses it.get_delivery_stats()counts what was let go. - Device backups. Godot gives a script no way to keep a file out of Android and iOS backups, so the game does it. The README gives the export option and backup rules. Desktop builds need nothing.
- Origin. Each session's events are saved with that session's
origin, so events a later launch sends are filed under the session, build and platform they happened in. Timestamps are unix milliseconds, so events in one second keep their order. - Errors behind gameplay. Gameplay events, a game's own
track_errorincluded, go before captured errors, also after the queue is read from disk. A capture evicts only the oldest capture, never a gameplay event, and an error'srs_trailis never written to the file. - Compression and signing. A request body of 1,024 bytes or more is sent gzip compressed; a 415 is sent once more uncompressed. When the session answer has
signing(public keys), every batch carriesX-Ravensight-Timestampand an HMAC-SHA256X-Ravensight-Signature. The secret is never written to disk. - Refusals. A 400 naming one event by
indexdrops that event and resends the rest. Onlybatch_too_largeand 413 halve the batch. Any other 400 drops the request's events, reported onflush_failed.
Kill switch
On boot, the SDK calls GET /api/v1/settings once with
ingest_key. If tracking is off for your game, it goes
idle for that run: no session is created and nothing is sent, and the
tracking_disabled signal fires with source
"server". A 403 tracking_disabled from any
request has the same effect mid-run. Flip trackingEnabled
from the dashboard's game settings and it takes effect on the game's
next launch, no update required.
Levels and deaths
Ravensight builds the level funnel, per-level deaths and journeys from
your event names, with no configuration: names containing
died, destroyed or killed count
as deaths, start, begin or
enter as level starts, and complet,
finish, win or clear as
completions. The level, location or
track field says where. To say what an event means
instead, set rs_kind in its data to
level_start, level_complete,
death or none. It is read before the name,
and none opts an event out. Keys that start with
rs_ are reserved for Ravensight.
Ravensight.track_event("boss_phase_begin", {"level": "castle", "rs_kind": "none"})
Ravensight.track_event("run_over", {"level": "castle", "rs_kind": "death"})
Typed events and performance
Four helpers send the typed events without
you writing the reserved keys. Each builds the rs_
properties and calls track_event(), so queueing, retries
and the player's opt-out are unchanged. Every helper takes an optional
last options dictionary.
| Function | What it does |
|---|---|
track_purchase(item_type, item_id, amount, currency, options) | A purchase. amount is whole minor units and the currency is upper-cased. options takes cart and transaction_id. Event name purchase. |
track_resource(flow, resource, amount, options) | A resource gained ("source") or spent ("sink"). options takes item_type and item_id. Event name resource_source or resource_sink. |
track_progression(status, p1, options) | A progression step: "start", "complete" or "fail". options takes p2, p3 and score. Event name progression_start, progression_complete or progression_fail. |
track_error(severity, message, options) | An error. The message is cut to 200 characters and the stack (options.stack) to 2000. Event name error. |
performance option | Off by default. When on, the SDK samples the frame rate once a second and sends one health event per session, on background (Android, iOS), page hide (web) or quit (desktop). |
options.data adds your own properties (the reserved keys
win if they clash) and options.event_name replaces the
default event name. The helpers never throw: a wrong value becomes an
event the server flags.
Player privacy
The device id is 16 random bytes from the operating system's secure
random source, as hex, plus the OS name, generated on first run and
saved in user://. set_tracking_enabled()
writes the choice at once and can be called at any time, even from an
autoload that runs before Ravensight's _ready(), or while
enabled is false. A saved opt-out wins over
enabled = true: on the next launch nothing is sent, not
even the kill switch check. Turning it off drops the queue and
deletes the saved queue file. reset_device_id() saves a
new random id, drops the queue (and its file), the session and the
attribution flag, and returns the new id. In a playtest run both do
nothing but print one line.
Telling players
You do not need a permission prompt, but saying what the game sends is good manners. A paragraph your game can show, in a settings screen or on its store page:
This game sends anonymous gameplay events (what happens in the game, never who you are) to Ravensight so we can improve it. You can turn this off in Settings at any time.
And the toggle behind "turn this off":
# an "Analytics" switch in your settings screen
func _on_analytics_toggled(on: bool) -> void:
Ravensight.set_tracking_enabled(on) # remembered across launches
# a "Forget me" button: a fresh random identity from now on
func _on_forget_me_pressed() -> void:
Ravensight.reset_device_id()
Player Reports
Add an optional in-game form that captures the current game screen, lets players highlight or hide an area, and sends a short message. Bind the reporting action to a key, controller input or pause-menu button. The dashboard groups reports into issues and tracks fixes through verification.
Download Ravensight.gd, RavensightReports.gd and RavensightReportOverlay.gd. Add the latter two as children of the Ravensight autoload, named RavensightReports and ReportOverlay. Bind ravensight_report in Input Map. The overlay captures only the game viewport and never pauses multiplayer.
Reports draw from your included events and prepaid balance automatically. A text report counts as 1 event on the event meter; a screenshot adds 20,000 events to the meter, covering processing, storage and delivery. There is no separate screenshot budget to configure. Failed or canceled uploads release their reserved usage. Retention and file limits are listed in Settings. Text-only reporting remains available if capture or upload fails. Screenshots are not automatically sent to AI providers.