# 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](https://ravensight.io/docs/public-builds/) 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::`: `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 with `rs_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 with `rs_kind: "death"`. A death matched only by its name does not count here. Without them, a funnel read from event names alone (`level_started` and `level_completed` on events that carry a place) still answers, with a note that it is inferred and that `rs_kind` makes 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 reserved `rs_` keys and the place keys `level`, `location` and `track`.

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](https://github.com/Reality-Software-Entertainment/ravensight-doctor).

## 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.

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