# The ravensight folder for LÖVE games

Pure Lua for LÖVE 11.x and 12.x on Windows, macOS and Linux. It owns the device id, sessions, batching, retries and the offline queue, and it sends requests from a background thread, so a slow network never costs a frame. There are no native files to bundle, sign or notarize.

Code samples scroll horizontally when needed. Focus a sample and use the arrow keys, or swipe to read a long line.

## Install

Copy the `ravensight` folder from [ravensight-love](https://github.com/Reality-Software-Entertainment/ravensight-love) into your game, next to `main.lua`. It can live in a subfolder too (`lib/ravensight`); require it by that path. The same files are published here: [init.lua](https://ravensight.io/sdk/love/init.lua), [core.lua](https://ravensight.io/sdk/love/core.lua), [config.lua](https://ravensight.io/sdk/love/config.lua), [errors.lua](https://ravensight.io/sdk/love/errors.lua), [hmac.lua](https://ravensight.io/sdk/love/hmac.lua), [json.lua](https://ravensight.io/sdk/love/json.lua), [reports.lua](https://ravensight.io/sdk/love/reports.lua), [transport.lua](https://ravensight.io/sdk/love/transport.lua), [typed.lua](https://ravensight.io/sdk/love/typed.lua), [web.lua](https://ravensight.io/sdk/love/web.lua) and [worker.lua](https://ravensight.io/sdk/love/worker.lua), the love.js bridge [ravensight-love-bridge.js](https://ravensight.io/sdk/love/ravensight-love-bridge.js) (only for a web build, it goes on the page, not in the game), the [README](https://ravensight.io/sdk/love/README.md) and the [MIT license](https://ravensight.io/sdk/love/LICENSE).

```
my-game/
  main.lua
  conf.lua
  ravensight/
    init.lua
    core.lua
    config.lua
    errors.lua
    hmac.lua
    json.lua
    reports.lua
    transport.lua
    typed.lua
    web.lua
    worker.lua
```

Set an identity in `conf.lua`, so the SDK has a save folder for its device id:

```
function love.conf(t)
  t.identity = "my-game"
end
```

## Use

```
local ravensight = require("ravensight")

function love.load()
  ravensight.init({
    apiUrl = "https://api.ravensight.io",
    ingestKey = "gt_live_...",   -- from your game's page in the dashboard
    gameVersion = "1.0.0",
  })
end

function love.update(dt)
  ravensight.update(dt)
end

function love.quit()
  return ravensight.quit()
end

-- anywhere in your game
ravensight.track("level_start", { level = "forest_1" })
ravensight.track("level_complete", { level = "forest_1", seconds = 74, deaths = 2 })
```

`game_started` is sent for you on launch and `game_exited` on quit. `ravensight.quit()` returns `true` the first time, which tells LÖVE to wait while the last events are sent; the SDK quits again by itself once they are answered, or after 1.5 seconds. If your game already has a `love.quit`, return its answer from your own handler, or pass `handleQuit = false` so the SDK never delays a quit.

```
function love.quit()
  if not saveGame() then return true end
  return ravensight.quit()
end
```

## Options

Pass these to `ravensight.init(options)`.

| Option | Default | Notes |
| --- | --- | --- |
| `ingestKey` | required | Your game's publishable `gt_live_` key. Safe to ship in a build. |
| `apiUrl` | `https://api.ravensight.io` | With or without `/api/v1`. |
| `gameVersion` | `1.0.0` | Sent with every session. |
| `enabled` | `true` | `false` sends and queues nothing for this run, and is not saved. The player's opt out is `setTrackingEnabled`. |
| `maxQueueSize` | `500` | Unsent events kept. The oldest are dropped first. |
| `flushInterval` | `2` | Seconds an event waits so it can go out with others. 50 waiting events go at once. |
| `handleQuit` | `true` | Hold the quit up to 1.5 seconds to send the last events. |
| `transport` | automatic | `"https"`, `"winhttp"`, `"libcurl"` or `"curl"` to try first, or `"web"` for the love.js bridge (chosen for you in a web build). |
| `timeout` | `15` | Seconds per request. |
| `debug` | `false` | Print informational messages too. Warnings always print. |
| `performance` | `false` | Sample the frame rate once a second and send one `health` event per session, on quit. Call `update(dt)` every frame. See [typed events](https://ravensight.io/docs/dashboard/#typed-events). |

## Functions

| Function | What it does |
| --- | --- |
| `track(name, data)` | Queue an event. `data` is a flat table of strings, numbers and booleans. Safe before the session is ready. |
| `purchase(amount, currency, itemType, itemId, opts)` | A typed purchase. `amount` is whole minor units and the currency is upper-cased. `opts` takes `cart`, `transactionId`, `props` and `name`. |
| `resource(flow, resource, amount, opts)` | A resource entering (`"source"`) or leaving (`"sink"`) the economy. `opts` takes `itemType` and `itemId`. |
| `progression(status, p1, opts)` | A progression step: `"start"`, `"complete"` or `"fail"`. `opts` takes `p2`, `p3` and `score`. |
| `error(severity, message, opts)` | An error or warning, with an optional `opts.stack`. The message is cut to 200 characters and the stack to 2000. |
| `trackAd(network, format, result, opts)` | An [`ad` typed event](https://ravensight.io/docs/dashboard/#typed-events). Returns `true`, or `false` and the reason when a field is malformed (nothing is sent). |
| `trackAdRevenue(network, format, placement, revenueMicros, currency, opts)` | A paid impression (result `shown`). |
| `microsFromDecimalString(text)`, `microsFromRevenue(number)` | Revenue in micros as a digit string, without multiplying a float. |
| `setAttribution(attribution)` | Where this install was acquired, sent once per install. |
| `getDeliveryStats()` | Desktop: events let go of since launch, `dropped_overflow`, `dropped_too_old` and `dropped_refused`. |
| `flush()` | Send what is queued now. It cuts a backoff wait short, never a server Retry-After. |
| `submitFeedback(message, category, rating)` | Send player feedback. `category` and `rating` (1 to 5) are optional. Needs an open session. |
| `setTrackingEnabled(enabled)` | The player's opt-out, remembered across launches. `false` drops the queue and sends nothing, not even the startup check. |
| `isTrackingEnabled()` | `false` when the player opted out or tracking is switched off for your game. |
| `resetDeviceId()` | Start a fresh analytics identity for this install. |
| `getDeviceId()` | This install's random id. |
| `getTransport()` | How requests are sent here, or `nil` if nothing works. |
| `on(event, fn)` | Listen for an SDK event. Returns a function that stops listening. |
| `update(dt)` | Call every frame. Delivers answers and runs retries. |
| `quit()` | Return it from `love.quit`. |

## Events

| Event | Arguments | When |
| --- | --- | --- |
| `session_ready` | none | A session is open. |
| `session_failed` | `reason` | Opening a session failed. It is retried for you. |
| `tracking_disabled` | `source` | `"server"` when tracking is switched off for your game, `"player"` after an opt-out. |
| `events_flushed` | `count` | A batch was accepted. |
| `flush_failed` | `reason` | A batch failed. It is retried for you. `"event_too_large"`: one event's data was over 8,192 bytes as JSON and the event was dropped, not retried. |
| `feedback_submitted` | none | Feedback was accepted. |
| `feedback_failed` | `reason` | Feedback failed, including `"no_session"` when sent too early. |
| `event_tracked` | `name, data` | Every queued event, with the data actually queued. |

```
ravensight.on("tracking_disabled", function(source)
  print("analytics off:", source)
end)
```

## How requests are sent

LÖVE 11 has no built-in HTTPS, and the API only accepts HTTPS, so the SDK uses the first of these that works. Nothing native is bundled.

1. **`require("https")`**: built into LÖVE 12, or the lua-https library if you added it to an 11.x game.
2. **WinHTTP** on Windows, the HTTP library every Windows version ships, called through LuaJIT's FFI.
3. **libcurl** on macOS and Linux, the system's own copy, through the FFI.
4. **The `curl` command** on macOS and Linux, if libcurl would not load.

If none of them works, the SDK prints one warning, keeps events queued, saves them when the game quits and tries again next launch. `getTransport()` tells you which one is in use. The libcurl and `curl` paths have been run against the live API on macOS. The WinHTTP path and Linux are written but not yet verified in a shipped build.

## Delivery

On the desktop; a love.js build delivers through the page's JavaScript SDK.

- **Batches of 50.** Up to 50 events per request.
- **Saved queue.** Unsent events are written to `ravensight/queue-.json` in the save folder, one file per ingest key, whenever the queue changes, through a temporary file renamed over the old one. At most 500 events are kept, 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. The 0.5 `ravensight_queue.json` is read once and removed.
- **Device backups.** On macOS the SDK excludes the file from Time Machine itself. On Android and iOS the game does it; the [README](https://github.com/Reality-Software-Entertainment/ravensight-love) says how.
- **Origin.** Each session's events are saved with that session's `origin`, so a later launch sends them under the session, build and platform they happened in. Timestamps are unix milliseconds.
- **Errors behind gameplay.** Gameplay events, a game's own `error()` included, go before captured errors. 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`, computed in `hmac.lua`. The secret stays in memory.
- **Backoff.** A failed request is retried after 10 seconds, doubling up to 5 minutes, each wait multiplied by a random factor from 0.5 up to 1. A `429`, or a `503` with `Retry-After`, waits exactly the server's time. A batch `401` opens a new session once, then waits for the backoff.
- **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. An event whose data is over 8,192 bytes as JSON is dropped before it is queued.
- **Refused key and kill switch.** Either stops the SDK for the rest of the run; the queued events stay on disk for the next launch. Turning tracking off as the player, or `resetDeviceId()`, deletes the saved queue.

## Privacy and the opt-out

The SDK generates a random device id per install: 32 hex characters, a dash and the OS name, from the operating system's random source on first launch, saved in your game's save folder. It is not derived from hardware or an account, and `resetDeviceId()` replaces it. Each event carries a timestamp, your game version and the OS. There is no advertising identifier, and no field for names, emails or accounts, so a game using it needs no tracking permission prompt. The row by row store answers are in [what your privacy label can say](https://ravensight.io/docs/platform-support/#privacy-label).

Ravensight ships no consent screen. If your game shows one, wire it to `setTrackingEnabled(false)`, which is saved and holds across launches, and `resetDeviceId()`.

## Public builds

For a demo, a web build or an open-source game, ship a [public key](https://ravensight.io/docs/public-builds/) with ravensight-love 0.3.0 or later. Without a key, `init` is inert: it writes no files, makes no requests, and `ravensight.enabled()` returns `false`; pass `optional = true` to silence its one warning. With `consent = "opt_in"` nothing happens, no device id, no queue and no settings call, until the player turns analytics on with `setTrackingEnabled(true)`, and that choice is saved. The `distribution` option is sent on the session, and every event carries an `rs_event_id` so a resend is never stored twice. A `401` or `403` on the settings check or the session stops the run instead of retrying a revoked key. On the web, `installRavensightBridge(null, Module)` installs a sink for a page with no key: the game's tagged lines are swallowed and the game never knows, and the bridge's opt-in check defaults to off when storage is missing or blocked.

Keep the key out of your repository. A tracked example file with placeholders sits beside an untracked config file that your ignore list excludes; your release job writes the real config from a CI secret when it builds a release. A clone or a fork has only the example, so its builds run with analytics off.

```
-- analytics.config.example.lua (tracked)
return {
  ingestKey = "",               -- written by the release job, never committed
  distribution = "native-dev",
}

-- main.lua: analytics.config.lua is untracked, and absent in a clone
local file = "analytics.config.lua"
local config = love.filesystem.getInfo(file) and love.filesystem.load(file)() or {}
ravensight.init({
  ingestKey = config.ingestKey ~= "" and config.ingestKey or nil,
  distribution = config.distribution or "native-dev",
  optional = true,
  consent = "opt_in",
  gameVersion = "1.0.0",
})
```

## Shipping to the web

A love.js build cannot make requests from Lua, so the page does the sending. Load the [JavaScript SDK](https://ravensight.io/docs/javascript-sdk/) (0.4.0 or newer; 0.5.1 or newer for the bridge to report experiment exposure, and 0.7.0 for millisecond timestamps) on the page and install `web/ravensight-love-bridge.js` from the repository before `Love(Module)` runs. The Lua SDK notices the web build by itself and hands every `track`, `submitFeedback`, `setTrackingEnabled` and `flush` to the page, whose SDK owns the session, the device id and the two lifecycle events. The snippet and the details are in the README's [shipping to the web](https://github.com/Reality-Software-Entertainment/ravensight-love#shipping-to-the-web-lovejs-itchio) section.

## Not supported yet

Android and iOS are not supported yet. Ravensight Playtest plays a love.js build like any web build, in the cloud or locally with `--build-dir` (see [Which builds play where](https://ravensight.io/docs/playtest/#playtest-engines)); a desktop build driven through the experimental desktop adapter (with an automation server you run yourself) or a custom bridge reads the `RAVENSIGHT_PLAYTEST_TOKEN` and `RAVENSIGHT_PLAYTEST_RUN_ID` variables, so its persona sessions are tagged synthetic.

Where each SDK finds a playtest run: Godot, LÖVE, Unity (desktop), Unreal, C++ and Odin read `RAVENSIGHT_PLAYTEST_TOKEN` and `RAVENSIGHT_PLAYTEST_RUN_ID`; iOS reads them from the launch environment; Android reads the intent extras `ravensight_playtest_token` and `ravensight_playtest_run_id`; the JavaScript SDK reads the page global `__RAVENSIGHT_PLAYTEST__`. The table below has the other sources each one accepts.

## How the SDKs compare

JavaScript SDK 0.7.0, LÖVE 0.7.0, Godot 0.5.0, Unity 0.5.0, Unreal 0.5.0, C++ 0.5.0, Odin 0.6.0, iOS 0.6.0 and Android 0.5.0, side by side on the behaviour that most often differs. A cell that says not yet is a feature that SDK does not have. Unity, Unreal, C++, Odin, iOS and Android are Beta: see [where the SDKs run](https://ravensight.io/docs/platform-support/) for what has been verified.

| Behaviour | JavaScript | LÖVE | Godot | Unity | Unreal | C++ | Odin | iOS | Android |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Automatic events | `game_started` and `game_exited` in a browser only, option `autoEvents` | `game_started` and `game_exited` | `game_started` and `game_exited` | `game_started` and `game_exited`; pause events only with Track Pause Events | `game_started` and `game_exited`; pause events only with Track Pause Events | `game_started` and `game_exited` | `game_started` and `game_exited` | `game_started` and `game_exited`; pause events only with `trackPauseEvents` | `game_started` and `game_exited`; pause events only with `trackPauseEvents` |
| Mobile background | Not applicable | Not applicable, desktop only | 30 minute rule on Android and iOS (`session_timeout`) | 30 minute rule on iOS and Android | 30 minute rule on iOS and Android | Not yet: call `flush()` from your own background handler | Not applicable, desktop only | 30 minute rule (`sessionTimeout`) | 30 minute rule (`sessionTimeoutMs`) |
| `apiUrl` form | With or without `/api/v1` | With or without `/api/v1` | `api_url` with or without `/api/v1` | Api Url with or without `/api/v1` | Api Url with or without `/api/v1` | `api_url` with or without `/api/v1` | `api_url` with or without `/api/v1` | `apiUrl` with or without `/api/v1` | `apiUrl` with or without `/api/v1` |
| Queue cap default | `maxQueueSize` 500 | `maxQueueSize` 500 | `max_queue_size` 500 | Max Queue Size 500 | Max Queue Size 500 | `max_queue_size` 500 | `max_queue_size` 500 | `maxQueueSize` 500 | `maxQueueSize` 500 |
| Option that turns sending off | `enabled` | `enabled` | `enabled` | Enabled On Start | Enabled | `enabled` | `start_disabled` | `enabled` | `enabled` |
| Player opt out | `setEnabled(false)` | `setTrackingEnabled(false)` | `set_tracking_enabled(false)` | `SetTrackingEnabled(false)` | `SetTrackingEnabled(false)` | `set_tracking_enabled(false)` | `set_tracking_enabled(client, false)` | `setTrackingEnabled(false)` | `setTrackingEnabled(context, false)` |
| Opt-out saved | No: keep it in your own settings | Yes, in the save folder | Yes, in `user://` | Yes, in `PlayerPrefs` | Yes, in `GameUserSettings.ini` | Yes, in a state file | Yes, in a JSON file | Yes, in `UserDefaults` | Yes, in `SharedPreferences` |
| Reset call | `resetDeviceId()` | `resetDeviceId()` | `reset_device_id()` | `ResetDeviceId()` | `ResetDeviceId()` | `reset_device_id()` | `reset_device_id(client)` | `resetDeviceId()` | `resetDeviceId()` |
| Batching | On a timer, every 15 seconds by default (`autoFlushMs`), or at 50 queued | 2 seconds after the first waiting event (`flushInterval`), or at 50 queued | 5 seconds after the first waiting event (`flush_interval`), or at 50 queued | Every 15 seconds (Auto Flush Seconds), or at 50 queued | Every 5 seconds (Flush Interval Seconds), or at 50 queued | Every 5 seconds (`flush_interval_seconds`), or at 50 queued | At least every 5 seconds (`flush_interval_ms`), or at 50 queued | Every 5 seconds (`flushInterval`), or at 50 queued | Every 5 seconds (`flushIntervalMs`), or at 50 queued |
| Startup reason | `reason` in the result of `init()` | Not yet | `get_status_reason()`, signal `status_changed` | `Ravensight.StatusReason`, event `StatusChanged` | `GetStatusReason()`, delegate `OnStatusChanged` | `client.status()`, callback `on_status` | `init_reason(client)`, callback `on_reason_changed` | `Ravensight.statusReason`, callback `Ravensight.shared?.onStatusChange` | `Ravensight.statusReason`, listener `onStatusChanged` |
| Playtest token source | Page global `__RAVENSIGHT_PLAYTEST__`, then `localStorage` `ravensight.playtest` | `RAVENSIGHT_PLAYTEST_*` variables, command line arguments, or `setPlaytestContext` | `set_playtest_context`, `RAVENSIGHT_PLAYTEST_*` variables, or command line arguments | `SetPlaytestContext`, then on desktop `RAVENSIGHT_PLAYTEST_*` variables or command line arguments | `SetPlaytestContext`, `RAVENSIGHT_PLAYTEST_*` variables, or command line arguments on desktop | Config fields, `RAVENSIGHT_PLAYTEST_*` variables, then command line arguments through `apply_playtest_args` | Config fields, `RAVENSIGHT_PLAYTEST_*` variables, then command line arguments | Configuration fields, then the launch environment | Config or `setPlaytestContext`, intent extras (debuggable builds, or with a manifest opt-in), then environment variables |
| Session token | `rs.sessionToken` | Not yet | `session_token` | `Ravensight.SessionToken` | `GetSessionToken()` | `client.session_token()` | `session_token(client)` | `Ravensight.sessionToken` | `Ravensight.sessionToken` |
| Web | Native | Through the ravensight-js bridge | Native, on the web export, without `game_exited` | WebGL, not yet verified in a browser | No web target in UE5 | Not applicable | Not applicable | Not applicable | Not applicable |
| Typed event helpers | Yes: `trackPurchase`, `trackResource`, `trackProgression`, `trackError` | Yes: `purchase`, `resource`, `progression`, `error` | Yes: `track_purchase`, `track_resource`, `track_progression`, `track_error` | Yes: `TrackPurchase`, `TrackResource`, `TrackProgression`, `TrackError` | Yes: `TrackPurchase`, `TrackResource`, `TrackProgression`, `TrackError` | Yes: `track_purchase`, `track_resource`, `track_progression`, `track_error` | Yes: `track_purchase`, `track_resource`, `track_progression`, `track_error` | Yes: `trackPurchase`, `trackResource`, `trackProgression`, `trackError` | Yes: `trackPurchase`, `trackResource`, `trackProgression`, `trackError` |
| Performance sampling | Yes: option `performance`, one `health` event when the page is hidden; browser only | Yes: option `performance` with `update(dt)`, one `health` event on quit | Yes: option `performance`, one `health` event on background, page hide or quit | Yes: Performance field, one `health` event on background (iOS, Android) or quit (desktop) | Yes: Performance setting, one `health` event on background (iOS, Android) or quit | Yes: `Config::performance` with `sample_frame(dt)`, one `health` event on shutdown | Yes: `Config.performance` with `tick(client, dt)`, one `health` event from `shutdown`; no memory figure | Yes: `performance`, one `health` event when the app enters the background | Yes: `performance`, one `health` event when the app first goes to the background |

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