# 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](https://ravensight.io/docs/dashboard/#typed-events). 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](https://ravensight.io/docs/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](https://ravensight.io/docs/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 through `Ravensight.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-.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](https://github.com/Reality-Software-Entertainment/ravensight-godot) 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_error` included, 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's `rs_trail` is 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](https://ravensight.io/docs/public-builds/)), every batch carries `X-Ravensight-Timestamp` and an HMAC-SHA256 `X-Ravensight-Signature`. The secret is never written to disk.
- **Refusals.** A 400 naming one event by `index` drops that event and resends the rest. Only `batch_too_large` and 413 halve the batch. Any other 400 drops the request's events, reported on `flush_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](https://ravensight.io/docs/dashboard/#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](https://ravensight.io/sdk/godot/Ravensight.gd), [RavensightReports.gd](https://ravensight.io/sdk/godot/RavensightReports.gd) and [RavensightReportOverlay.gd](https://ravensight.io/sdk/godot/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.

Source: https://ravensight.io/docs/godot-sdk/
Last updated: 2026-11-15
