Check your integration before and after you ship
Two layers watch your integration. The dashboard computes implementation health from your game's own live traffic, and a public scanner checks your source tree before you ship. Both feed the same card on your game's Overview page.
Live implementation health
Automatic, no setup. The API already sees what your integration does:
requests rejected for size, event names exploding in cardinality,
payloads brushing the 8KB ceiling, sessions with no end-of-session
marker, and reserved rs_ keys with values Ravensight does
not know. The Implementation health card on Overview summarizes it over
the last 7 days and tells you what to change.
no_game_exited means no session in the window sent
game_exited, the marker for the end of a session. It is
about the missing marker, not lost delivery: the events in those
sessions were stored, and session length is measured to the last
stored event. The JavaScript SDK sends game_exited
automatically in a browser; the native SDKs send it from their quit and
lifecycle hooks; a scripted runner that kills the app never sends it.
The finding is info when every session that started also
sent events after game_started, and a
warning only when some sessions sent nothing at all after
the start, which can mean the queue is not flushed before the app
closes.
A game with public keys gets a
public_keys block on the card: each live key (paused
included; revoked and expired keys are history, not health) with its
label, prefix, state, accepted events this month, its ceiling if one
is set, what remains under it and what its events would cost in
blocks, its refusal counts and its most frequent unlisted names. The
key list in Settings shows the same signals. Its findings, each with
the id public_key:<code>:<prefix>:
needs_funds (error: the included allowance is used and
the balance cannot buy the next block of events, which stops every
key in the account; add funds to keep accepting events),
ceiling_reached (error: the key is at its ceiling or has
refused a batch at it) and ceiling_near (warning: 80
percent of the ceiling), unlisted_names (note: events
refused because their names are not on the allowlist, with the most
frequent names, so you can add the ones you meant),
rejection_spike (warning: at least 100 refusals this
month and at least 20 percent of what the key was sent),
origin_mismatch (sessions from origins not on the key's
list: a warning while enforcement is off, a note when they were
refused), expiring (warning: the key expires within 7
days) and device_concentration (warning: at least 1,000
events under the key and one device id sending at least half of
them). Device concentration reads the key's recent sessions, those
opened in the last 24 hours that are still alive, and a session ends
at its lifetime (one hour by default), so it sees roughly the last
session lifetime of traffic, not a full day.
What this data can answer
Below its findings, the Implementation health card lists four questions and says, from this game's own events, whether the data can answer each one. A question it cannot answer comes with a one-line reason that names what to send.
- Do players come back? (
retention) Needs a real event at least 7 days old, so day 7 retention has a cohort old enough to measure. - Where do players stop progressing? (
levels_funnel) Needs events sent withrs_kind: "level_start"and an end:rs_kind: "level_complete", a terminal event from the detection profile, or, when deaths are outcomes, an event sent withrs_kind: "death". A death matched only by its name does not count here. Without them, a funnel read from event names alone (level_startedandlevel_completedon events that carry a place) still answers, with a note that it is inferred and thatrs_kindmakes it exact. - Which paths do players take between places? (
journeys) Needs events that carry a place. - How do groups of players differ? (
segments) Needs events that carry properties of their own, beyond the reservedrs_keys and the place keyslevel,locationandtrack.
In the API answer the block is answerable_questions: a
boolean per question, reasons, keyed by each question
that is false, and notes, keyed by each question answered
only by inference. Two warnings sit beside it on the card, with their own
title and detail: uuid_like_place_values, when a game has
at least 20 distinct places in the last 7 days and half or more look
like generated ids, which split one place into thousands of rows; and
synthetic_only_traffic, when every session in the last 7
days was synthetic: Ravensight Playtest personas or a
ravensight-doctor --live ping, which every report leaves
out by default. Its title counts each kind.
ravensight doctor
A zero-dependency scanner for your project directory. It detects your engine, finds the SDK, and lints the integration statically: event name length and cardinality, oversized inline payloads, missing track calls, and credentials that must never ship inside a game build (an MCP token or a cloud key in your tree is an error; your publishable gt_live ingest key is fine).
Run it
npx ravensight-doctor # machine readable, with the full inventory npx ravensight-doctor --json # your own track wrapper npx ravensight-doctor --track-fn capture,Analytics.logEvent # send one test event and confirm it was stored RAVENSIGHT_INGEST_KEY=gt_live_xxxx \ npx ravensight-doctor --live # also submit the report to your dashboard RAVENSIGHT_INGEST_KEY=gt_live_xxxx \ npx ravensight-doctor --report
What it recognised
Every report lists an inventory: each track call it found with its
file, line and literal event name (or none when the name is a
variable), the distinct event names with counts, the track functions
it looked for, and how many ingest keys it found in the project and
under test paths. The pretty report prints a summary and
--json prints all of it. A track call counts when the
name right before .track( is exactly rs,
ravensight or Ravensight, with any chain
before it, so this.rs.track( counts and
analytics.track( does not.
If your game tracks through its own wrapper, name it with
--track-fn (comma separated and repeatable) or in a
ravensight.config.json in the directory you scan:
{
"trackFunctions": [
"capture",
"Analytics.logEvent",
{ "name": "track_event", "argIndex": 1 }
],
"ignore": ["vendor/", "*.generated.gd"],
"gitignore": true
}
argIndex says which argument holds the event name.
ignore adds .gitignore style patterns, as
does --ignore, and the root .gitignore is
honoured unless gitignore is false or you
pass --no-gitignore. Ingest keys under test and fixture
paths are listed but never used for --report or
--live.
Status and exit codes
| Status | When |
|---|---|
fail | At least one error finding. |
inconclusive | The doctor could not check your events: it found track calls but none names its event with a string literal, or it found an ingest key but no track call it recognises. Name your wrapper with --track-fn to resolve it. |
warn | Any other warning. |
pass | No errors or warnings. Only a real pass says your integration looks healthy. |
Exit code 1 when any error finding exists, so CI can fail the build,
and 0 for pass, warn and
inconclusive. Add --strict to exit 1 on
anything but pass. An unusable config file exits 2.
Three lines of evidence
From 0.4.2 the report prints three evidence lines: Static
(what the source scan found), Runtime trace (what a
recorded run sent) and Live delivery (the
--live ping). The top-level status is the static
verdict, so a missing live check never turns a clean scan into a
failure.
A wrapper that adds properties to every payload centrally declares
enriches in ravensight.config.json, so the
contract keys it supplies are not reported missing. An undeclared
wrapper is reported as contract_prop_unproven at
info, not as an error. Forwarding closures are resolved
automatically, and forwarders declares the ones the
scan cannot follow.
When the build injects the key (an .xcconfig value or a
CI secret), declare ingestKey: { "source": "build" } and
point the doctor at the built product with --bundle, so
it checks the key that ships rather than one in source.
{
"enriches": ["Analytics.logEvent"],
"forwarders": ["Telemetry.send"],
"ingestKey": { "source": "build" }
}
Check the built bundle
npx ravensight-doctor --bundle path/to/YourGame.app
The live check
--live proves the ingest key can deliver an event end
to end. It reads the kill switch, opens a session with
"platform": "doctor", sends one
ravensight_doctor_ping whose data carries a random
rs_doctor value, then reads it back from
GET /api/v1/doctor/ping/:nonce every 2 seconds, at most
10 times. The server keeps doctor sessions out of your analytics and
your event usage and allows them only that one event. A ping that is
read back is reported as stored, with the time the server accepted
it. One accepted but not read back within 20 seconds is the warning
live_ping_unconfirmed. A bad key, tracking switched off,
or a refused session or event is the error
live_check_failed, with a note saying which step failed.
In CI
GitHub Actions
- uses: Reality-Software-Entertainment/ravensight-doctor@v0
with:
path: .
report: true
api-key: ${'$'}{{ secrets.RAVENSIGHT_INGEST_KEY }}
A GitLab CI snippet ships in the ravensight-doctor repo.
The report API
The doctor submits to POST /api/v1/doctor with your
X-API-Key ingest key: an engine, a summary
(pass, warn or fail with counts), and up to 100 findings. An
inconclusive result is sent as warn, and the
inventory and live result stay on your machine. One report
is kept per game, newest wins, and it appears on the Implementation
health card alongside the live signals.