Ravensight

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.

PropertyTypeDefaultNotes
api_urlStringhttps://api.ravensight.ioWith or without /api/v1, with or without a trailing slash. Empty means the default. api_base() returns the normalised root.
ingest_keyStringgt_live_your_ingest_key_hereThe publishable key from your game's confirmation screen.
game_versionString1.0.0Sent with every session.
enabledbooltruefalse 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_sizeint500Unsent events kept. The oldest are dropped first; a queued game_started is kept.
flush_intervalfloat5.0Seconds an event waits so it can go out with others. 50 waiting events go at once.
handle_quitbooltrueThe 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_timeoutfloat1800.0Android and iOS only: seconds in the background after which the session counts as over. See Automatic events.

Public functions

FunctionDescription
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

SignalFires when
session_readyA 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_submittedFeedback 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.

ReasonMeaning
""Nothing is wrong: a session is open, or opening normally.
disabledenabled is false, or the player opted out.
invalid_keyThe 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_disabledThe kill switch is off for your game. Nothing more is sent this run; the queued events stay on disk.
offlineNo 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_limitedThe server said slow down (429, or 503 with Retry-After). The SDK waits exactly the Retry-After time.
session_failedOpening a session failed for another reason (retried with the same backoff), or a playtest token was refused.
playtest_job_closedThe 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_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), 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 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.

FunctionWhat 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 optionOff 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.