Public builds and open-source games
A free demo, a web build anyone can open, or a game whose source is
public all ship the key in a place anyone can read. A public key
(gt_pub_) is made for that case: it can only send the
events you list, at the rates you set, into one environment, and you
can pause or revoke it without shipping a new build.
The trust model
- A shipped identifier is public. Anything inside a build, a page or a download can be read by whoever has it. A Ravensight ingest key is a key to write events, never to read them: no ingest key can read your analytics, your settings beyond its own game's tracking switch, name and environment, or your account.
- A key injected at build time is not a secret. Injecting it from CI keeps it out of your repository, which is what stops a fork from reporting into your account. It does not hide it from anyone who downloads the build.
- CORS is not a gate. The ingest endpoints answer every web origin with
Access-Control-Allow-Origin: *. That is what lets a browser game on any host send events; it decides nothing about who may send them. - No token proves where an event came from. Nothing a client sends can prove which build, which site or which fork sent it. What bounds someone who copies your key is the event allowlist and the rest of the key's policy, the rate limits, the optional ceiling and your ability to pause or revoke it.
| Control | What it stops | What it does not stop |
|---|---|---|
| Event allowlist | Every event name you did not list. An empty list refuses every event. | Fake events that use a listed name with plausible values. |
| Payload rules | Large, deep, wide or malformed payloads, and reserved rs_ keys Ravensight does not read. | Small, well formed payloads with invented values. |
| Rate limits | A flood from one key, one session or one device id. | A slow, patient sender who stays under every limit, or one that makes many device ids. The per-device limits apply only when the client sends a device id. |
| Monthly ceiling (optional) | Accepted events on that key past the number you set, for the rest of the month. | Spending on your other games, keys, MCP calls or AI work. It is not a cap on your bill. |
| Origin hint | With enforcement on, a browser page on a site you did not list. Browsers set Origin and a page cannot change it. | A native build, a script or a bot, which can send any Origin header or none. |
| Version list | Sessions that declare a game version you did not list, or none. | A client that declares a listed version string. The version is whatever the client says. |
| Pause and revoke | Every new session and every event on the key, at once, including the key's live sessions. | Nothing on another key or on your live key. |
The public key
Create one in Settings > Projects, on the game card for the environment it should report into, beside the detection settings. A demo usually gets its own environment, so its traffic never mixes with a released game's. The full key is shown once; after that the dashboard shows its prefix and your label. A game can have at most two live public keys; a paused key still holds its place, and a revoked or expired one gives it back.
A public key can call:
POST /api/v1/session, for an ordinary player session.GET /api/v1/settings, for its own game's tracking switch and name, withkey.kindset topublicandkey.labelto your label.- With the session token it gets:
POST /api/v1/trackandPOST /api/v1/track/batch;POST /api/v1/feedbackonly when the policy setsallow_feedback, and Player Reports only when it setsallow_reports.
It is refused everywhere else. The agent suggestions feed, the
doctor's report and ping read-back, a doctor session
("platform": "doctor"), a playtest run and the legacy
/api/track answer 403 public_key_forbidden.
Every dashboard, billing, organization and MCP path answers
401, because an ingest key is not a credential there.
Like every ingest key, it never reads another game's settings: the
game comes from the key, never from the request.
The dashboard manages keys through the signed-in API, under
/api/v1/games/:gameId/public-keys.
GET lists every key of the game, revoked ones included,
as { publicKeys, maxLive }; each key carries its policy,
this month's accepted, ceiling,
remaining and what the ceiling's events would cost, and
its signals. POST creates one and answers
201 { publicKey, key }, the only time the full key is
returned, or 409 public_key_limit at two live keys.
PUT .../:keyId/policy changes only the fields you send
(400 invalid_policy names the field), and
POST .../:keyId/pause, .../unpause and
.../revoke answer { publicKey }.
GET .../suggested-events lists
game_started and game_exited, which every
SDK sends on its own, then the game's most frequent event names of the
last 30 days, 50 names in all, which is what prefills a new key's
allowlist. GET .../suggested-policy suggests a policy
from the last 7 days of the game's real events and answers
{ policy, basis }: allowed_events (the two
SDK events, then the names it saw, most frequent first, at most 100),
max_properties (the most seen plus 25 percent, at least
the default), max_event_bytes (the 99th percentile times
1.5, rounded up to 256), max_depth,
max_string_length, and the two per-minute rates (twice
the busiest minute seen), each kept inside the allowed values, with
the figures behind them in basis. It saves nothing, and
a game with no recent events gets the defaults. Creating and revoking need the role that may
rotate the game's key; editing, pausing and unpausing need the role
that may change the game's settings.
The policy
Each public key carries its own policy, stored on the key when it is
created, so a later change to a default never changes a key that
already shipped. The one exception is capture_errors,
which arrived later and is on for every key unless you turn it off.
Edit it on the key's card. The limits every key
already has still apply on top of it, so a policy can only make a key
stricter than a live key.
| Field | Default | What it does | Allowed values |
|---|---|---|---|
allowed_events | empty | Event names the key may send. Empty refuses every event; the dashboard prefills the list from the game's recent names. | Up to 100 names. A name is any name live ingest accepts: 1 to 200 characters, no surrounding spaces, no control characters. Names starting ravensight_ or rs_ are reserved and refused. |
max_batch | 20 | Events in one /track/batch call. | 1 to 50 |
max_event_bytes | 2,048 | One event's data, serialized. | 256 to 8,192 |
max_properties | 40 | Keys in one event's data, counted at every level. | 1 to 50 |
max_depth | 2 | How deeply objects and lists may nest. Each object or list adds a level. | 1 to 4 |
max_string_length | 256 | Characters in one string value or key. | 1 to 1,024 |
| Finite numbers | always | A number must be finite. | Always on |
max_past_seconds | 2,592,000 (30 days) | How old an event's timestamp may be. A game that saves its queue offline sends late events, so keep this at days. A key created before November 2026 keeps the 86,400 it was created with until you change it. | 60 to 7,689,600 (89 days) |
sessions_per_minute | 30 | New sessions on this key. | 1 to 60 |
events_per_minute | 300 | Events on this key. | 1 to 600 |
events_per_session_per_minute | 60 | Events from one session. | 1 to 600 |
events_per_device_per_minute | 120 | Events from one device id, when the client sends one. | 1 to 600 |
sessions_per_device_per_hour | 12 | New sessions for one device id, when the client sends one. | 1 to 120 |
session_ttl_seconds | 3,600 | How long a session token from this key lives. A key with an expiry date never mints a session that outlives it: the session lives the shorter of the two. | 300 to 86,400 (24 hours) |
monthly_event_ceiling | none | Optional and off by default. Accepted events on this key in a calendar month (UTC). The dashboard suggests 250,000 when you turn it on. | None, or 1,000 to 500,000,000 |
dedupe_window_seconds | 86,400 (24 hours) | How long, at least, an rs_event_id is remembered. 0 turns it off. A key created before November 2026 keeps the 600 it was created with until you change it. | 0 to 604,800 (7 days) |
allowed_origins | empty | Web origins you expect, such as https://your-studio.example. | Up to 20, each scheme://host[:port] in lower case with no path, at most 200 characters |
enforce_origin | false | Off: an unlisted origin is counted and shown as a signal. On: a session from an unlisted origin is refused. | Needs at least one origin on the list |
require_origin | false | On: a session with no Origin header is refused too. Native builds send none, so turn it on only for a key used by web builds alone. | Needs enforce_origin |
allowed_versions | empty | Game versions a session may declare. Empty accepts any; once set, a session with no version is refused too. | Up to 50, each 1 to 64 characters |
allow_feedback | false | Allow player feedback on this key. | true or false |
allow_reports | false | Allow Player Reports on this key. | true or false |
capture_errors | true | Error events (rs_kind: "error" with a severity of warning, error or critical, or none) pass the event allowlist under any name, and may carry a 200 character message, a 2,000 character stack and a 1,500 character log trail, even where the key's own limits are smaller. The event may grow past max_event_bytes by the size of its message, stack and trail only, up to 6,144 bytes. A session may send 10 a minute that need this room. The rest, and any error event larger than its room, are dropped, counted as error_capture_limited, and never stored or charged. A key with an empty event allowlist stays shut to error events too. On for keys created before this field existed. | true or false; false holds error events to the key's own limits |
require_steam_ticket | false | Require Steam verification before opening a session. | true or false; needs a Steamworks connection and app id |
steam_app_id | null | The Steam app whose tickets are accepted. | Positive decimal app id, or null when the requirement is off |
Numbers are whole numbers. A change outside these values, an unknown
field or a wrong type answers 400 invalid_policy with the
field it refused. A batch that breaks a payload rule
answers 400 with the error and the index of
the first event that broke it, so every SDK's batch splitting isolates
and drops that event and keeps the rest. A batch longer than
max_batch is refused whole, with no index. The codes are
in the HTTP API.
Rate limits, in layers
A request on a public key passes every layer, and the first one that
is full answers 429 rate_limited with a
Retry-After header. The layers run narrowest first: on
/track the session, then the device id, then the key,
then the game; on /session the device id, then the key,
then the game. A request one layer refuses has spent only the
narrower layers, so one noisy session or device cannot use up the
key's or the game's minute.
- Per key:
sessions_per_minuteandevents_per_minute. - Per session:
events_per_session_per_minute. - Per device id:
events_per_device_per_minuteandsessions_per_device_per_hour, only when the client sends a device id. The id is the client's own choice, so these bound a buggy or honest client; the key's limits and the ceiling bound one that invents ids. A public/sessionrefuses a device id over 256 characters with400 invalid_device_id. - Per game: 60 sessions and 600 events a minute, shared with every other key on the game.
- Per IP address: 100 requests a minute. Players who share one address, such as a LAN party, a school, a venue's network or a mobile carrier, share this budget, so a busy room can see
429sooner than one player would.
A rate limited request counts once per window on the key's usage, not once per retry. Each limit is counted on the API server that answers the request; see Usage, billing and limits.
Timestamps, duplicates and retries
An event whose timestamp is older than max_past_seconds
is dropped the way a live key drops one older than 90 days: it is not
stored or charged, the call still answers 202, and
accepted is lower than the number you sent.
Give every event a unique rs_event_id string in its data
and a resend is never stored twice. For at least
dedupe_window_seconds (it can run a little longer, never
shorter), an id the same device already sent on this game is skipped, even under a new session: it is not
stored, not counted and not charged, and the answer counts it in
duplicates instead of accepted. An id is 1
to 64 letters, digits, _ or -; anything else
answers 400 invalid_event_id. The game's live key
dedupes the same way, with a 24 hour window, for events that carry
an id. A resend later than the window can be stored twice; the Data
quality card counts those as the same event stored twice. A refused or failed request gives its ids back, so the resend
is accepted. The public-build SDK releases add the id for you; see SDK behavior.
| Answer | What the client does |
|---|---|
202 | Done. Remove the events from the queue, including any counted as duplicates. |
400 | Drop the event at index and never retry it. Send the rest of the batch again. A batch_too_large answer has no index: split the batch. |
401 | Authenticate again: open a new session, then send. public_key_inactive means the key that opened the session was paused, revoked or expired, and the new session meets its real state. A 401 on /session itself means the key is unknown or revoked, so stop. |
403 | Stop for this run. The key is paused or expired, its policy refused this origin, a missing origin, this version or this endpoint, or tracking is off for the game. |
429 | Wait for Retry-After, then resend the same events with the same rs_event_id values. |
5xx | Back off, then resend the same events with the same ids. |
Rotation, pause and revocation
A game can have two live public keys, so you can rotate without a gap:
create the second key, ship builds with it, and revoke the first once
the old builds no longer matter. Public keys are revoke only: a
revoked key never comes back, and revoking one ends its live sessions
at once: their next request answers 401. Rotating the game's live key leaves public keys and their
sessions alone.
Pause is the reversible stop. A paused key answers
403 key_paused on every new session and its live sessions
end; unpause it and the same builds report again. A key can also carry
an optional expiry date, after which it answers
403 key_expired; no session it mints outlives that
date. A change made in the dashboard can take up to a minute to reach
every server. Above every key, the game's own
kill switch still stops every session with
403 tracking_disabled.
What it costs
- Enabling it is free. Creating, pausing and revoking keys costs nothing.
- Accepted events are ordinary events. They draw the account's included monthly allowance first. Past it, each started block of 100,000 events is bought from your prepaid balance at 5 cents. A block that is only partly used is still paid for.
- An empty balance stops ingestion. When the next block cannot be bought, the account's ingestion answers
429 quota_exceededwithreason: "needs_funds"on every key, live and public, and nothing is charged for the refused events. The key's card and the Implementation card say "Add funds to keep accepting events." - The ceiling is optional, and off by default. Without one, the card reads "No ceiling, buys blocks while funded". Turn it on and the dashboard suggests 250,000; the key then "stops accepting at this many events for the month even when funds remain", answering
429 public_key_ceiling. A batch that would cross it is refused whole. The card prices it in the same blocks, for example "A ceiling of 250,000 events is 3 blocks of 100,000, $0.15 at the current block price, for this key's events past the included allowance." It limits one key; your other keys, your live key and MCP calls draw the same balance, so it is not a cap on your bill. - Refused traffic is free. Rejected, invalid, duplicate, rate limited, over the ceiling and origin refused events are never charged.
- Usage emails are information. The game's owner gets one email at 80 percent of a key's ceiling and one at 100 percent, or when a batch would cross it. They do not stop anything themselves, and each lists every way a public key stops: its ceiling, an empty balance, a pause, a revoke, its expiry, and its rate limits for the moment they are exceeded.
- The billing page shows the share. It says how many of the month's player events came through public keys, and from how many keys. Those events are already inside the player events figure, never added on top.
Forks and source releases
Never commit the key. Keep it in your CI's secret store and inject it when you build a release, so the repository, the source archive and a fork's builds have none. A fork's own CI has no access to your secrets, so its builds come out keyless, and a keyless build cannot open a session, so it sends nothing. The public-build SDK releases start inert without a key, so the game still runs. If a key does reach a public repository, pause it, create a second key, and revoke the first once your builds use the new one.
Through your own server
If your game already has accounts, keep the live ingest key on your
server. After authenticating the player, your server can open
POST /api/v1/session with X-API-Key, using
a device or player identifier it has verified. Return only that
player's session token to the client over HTTPS. The client can
then send events with X-Session-Token; it never needs
your live key. Renew an expired session through the same authenticated
route. Rate limit that route and never accept an arbitrary player id
from the browser.
This is an HTTP integration pattern. The SDKs do not all provide a method to adopt a server-minted token. Use the HTTP API for that client, or keep tracking on your server. A relay can be a temporary bridge for an existing client, but it must authenticate players, validate events and apply limits. An open relay simply moves the same abuse problem to your server. For games without accounts, use a public key with an allowlist and limits instead.
Require a Steam ticket
For a Steam build, connect Steamworks in your studio, then enable
require_steam_ticket on its public key and set
steam_app_id to your app's decimal id. The flag defaults
to false and the app id to null. Turning it on without a Steamworks
connection is refused with 400 steam_connection_missing.
This setting applies to new sessions, so use a separate key for
builds distributed elsewhere.
Your Steam integration obtains a hex ticket with
GetAuthTicketForWebApi("ravensight") and sends it as
steamTicket in the session request. Ravensight checks it
with Steam using your stored Steamworks connection. The SDKs do not
currently obtain or attach this ticket automatically: wire it into
your session transport before enabling the requirement. See
Steam's ticket verification API.
A missing ticket answers 403 steam_ticket_required; a
refused ticket answers 403 steam_ticket_invalid. An
unusable connection answers 403 steam_connection_missing.
If Steam cannot be reached, the answer is
503 steam_unavailable with Retry-After: 30.
None opens a session or charges for verification. Successful checks
are cached for ten minutes per key and app. A joined session can
reuse its parent's verification only for the same Steam app.
Sessions store a keyed hash of the Steam id and the verified app id,
never the raw Steam id. A valid ticket verifies access to the app;
it does not prove that subsequent client event values are truthful.
If you enable Steam verification or use your own account identifier, review your game's privacy disclosures for that configuration. The default random-device-id guidance below does not describe account-linked sessions; hashing a Steam id does not make it an anonymous identifier.
SDK behavior in public builds
The SDK versions listed under platform support support keyless
builds that send nothing, an optional opt-in consent mode, a
distribution label, and event ids that remain stable on retries.
Include game_started and game_exited in
your allowlist. Option names and supported transports vary by SDK;
follow the SDK comparison and linked repositories.
The doctor can warn about a live key in source or a shipped bundle;
a scan that skips an unreadable file is not proof that no key exists.
Keep public keys bounded and live keys on your own server when possible.
What the server keeps, and what it cannot tell
Per key and month, Ravensight keeps the number of accepted events,
counts of each refusal reason, and short, bounded lists of the
origins that opened sessions and the most frequent event names that
were refused for not being on the allowlist. It never stores a raw
IP address: for traffic sources it keeps a
keyed hash and a masked form of each connecting address for 30 days,
or for as long as you keep that address blocked. A session records
the distribution the client declared, and each of its
events carries it as a distribution property unless the
event sends its own. It also records the player's country and the
device fields the SDK sent; see
country and device.
The honest limit: a native build, a script or a bot can send any
Origin, any version string and any
distribution. Treat all three as hints that sort honest
traffic, never as proof.