# The Ravensight Swift package for iOS, tvOS and macOS

One Swift package for iOS 15 or newer, tvOS 15 or newer and macOS 12 or newer, with no third party dependencies and a URLSession transport. It owns the device id, sessions, batching, the offline queue, rate limit handling and the server kill switch, and it sends player feedback and Player Reports with a screenshot.

Verified so far: the package's tests on macOS, on the iOS Simulator and on a tvOS simulator. On tvOS the saved queue and pending crash records live in Caches, the only folder a tvOS app may keep files in, so the system can purge them under storage pressure. It has not yet run inside a shipping app or on a physical device, so read the code before a release build. The source and the full README are at [ravensight-ios](https://github.com/Reality-Software-Entertainment/ravensight-ios). Code samples scroll horizontally when needed.

## Install

Swift Package Manager only. In Xcode choose File > Add Package Dependencies, paste the repository URL and add the `Ravensight` library to your app target. Or declare it in `Package.swift`:

```
dependencies: [
    .package(
        url: "https://github.com/Reality-Software-Entertainment/ravensight-ios.git",
        from: "0.6.0"
    ),
],
targets: [
    .target(name: "YourGame", dependencies: ["Ravensight"]),
]
```

## Initialise

Call `start` once, early, from the main thread (your `App` init or `application(_:didFinishLaunchingWithOptions:)`), with the publishable `gt_live_` ingest key from the dashboard. It queues `game_started`, reads the kill switch, opens a session, sends batches every 5 seconds and hooks the app lifecycle so the queue is flushed when the player leaves.

```
import Ravensight

Ravensight.start(ingestKey: "gt_live_your_key")

Ravensight.track("level_completed", data: ["level": 3, "deaths": 2])

// Or the full configuration:
var configuration = RavensightConfiguration(ingestKey: "gt_live_your_key")
configuration.gameVersion = "1.2.0"
configuration.persistQueue = true      // the default; false keeps the queue in memory
Ravensight.start(configuration)
```

On iOS a session ends by time in the background: a player who comes back within `sessionTimeout` (30 minutes by default) carries on the same session, and one who comes back later, or after the app was swiped away, gets the old session's `game_exited` stamped with the time they left, then a new session.

## Xcode configuration

Keep the ingest key out of source and give each build configuration its own: an ignored `.xcconfig` with per-configuration keys, an explicit `Info.plist` template that substitutes `$(RAVENSIGHT_INGEST_KEY)`, suppression under XCTest and SwiftUI previews so tests and canvases send nothing, and a check of the built bundle before you ship. The steps are in the SDK repo's [`docs/XCODE_SETUP.md`](https://github.com/Reality-Software-Entertainment/ravensight-ios/blob/main/docs/XCODE_SETUP.md). To confirm which environment a build's key reaches, see [Which environment does this key hit?](https://ravensight.io/docs/quickstart/#which-environment)

## Timing and privacy

The SDK stamps events with wall clock time. If your app reads `systemUptime` (or another boot-relative clock) for its own timing, Apple treats that as a required-reason API, so your app needs its own privacy manifest declaration for it. Send elapsed in-app intervals, such as seconds spent in a level, as event data, and never raw uptime, which can be used to tell devices apart.

## Privacy: two controls that do different things

`setTrackingEnabled(false)` is the player's choice. It is saved in `UserDefaults` before the call returns, works before `start`, clears the queue and stops every request on this launch and every later one. `stopAllTelemetry()` is a stop for this run only: nothing is saved, the queue and the persisted queue file are cleared, `track` returns false, and feedback and reports are refused. The difference that matters is the playtest run: a synthetic session is driven by an agent on a test build, not by a player, so it ignores the saved opt-out, and only `stopAllTelemetry()` silences it.

| Call | Saved | Normal session | Synthetic (playtest) session |
| --- | --- | --- | --- |
| `setTrackingEnabled(false)` | Yes | Queue cleared, no request of any kind, now and on every later launch. | Ignored, with one console line. The run carries on. |
| `stopAllTelemetry()` | No | Everything stops for this run. The next launch starts normally. `resumeTelemetry()` undoes it, and a saved opt-out still wins. | The run stops sending. |
| `resetDeviceId()` | Yes | A new durable id is saved and returned, the queue is cleared and the session ends. | A new durable id is saved for the next normal launch. The run keeps its playtest id. |

An analytics switch in your settings screen uses both:

```
func setAnalytics(_ on: Bool) {
    Ravensight.setTrackingEnabled(on)     // saved: holds on every later launch
    if on {
        Ravensight.resumeTelemetry()
    } else {
        Ravensight.stopAllTelemetry()     // also stops a playtest run, right now
    }
}
```

## Playtest tagging, and why a synthetic id is never mirrored

A Ravensight Playtest run identifies itself with a token and a run id, from `RavensightConfiguration.playtestToken` and `playtestRunId`, or else from the `RAVENSIGHT_PLAYTEST_TOKEN` and `RAVENSIGHT_PLAYTEST_RUN_ID` launch environment variables (on the Simulator, `xcrun simctl launch` passes a variable through when you prefix it with `SIMCTL_CHILD_`). With a token, every request carries the `X-Ravensight-Playtest` header and the run sends the device id `pt-`, held in memory only and exposed as `playtestDeviceId`. The persisted queue is not used. A token without a run id never runs as a real player: nothing is sent.

`Ravensight.deviceId` always returns the durable id, never the synthetic one, and `resetDeviceId()` never returns a synthetic id either, so an app that copies the id into its own storage or its own server is safe. Never copy `playtestDeviceId` anywhere that outlives the run. A mirrored `pt-` id would come back on a later launch: a real player's events would then be filed under a persona's run and left out of every report that hides playtest sessions, and your own records would count a persona as a player. `Ravensight.isSynthetic` tells you which kind of run this is. Leave the token and run id unset in a build for real players.

## Player Reports with a screenshot

`submitReport` sends what a player wrote about a problem, with your own metadata and, only if you pass one, a screenshot. The SDK never captures the screen: capture it yourself after the player chose to attach it, with anything private hidden. On macOS pass `screenshotData:` with JPEG, PNG or WebP bytes. Reports land in the dashboard's Player Reports inbox.

```
// A failed report kept for a retry, with the session it was sent under.
var pendingReport: (report: RavensightReport, session: String?)?

// Build the report once: its clientId, capture time and screenshot bytes
// are fixed here, so resubmitting this value sends the same submission.
let report = RavensightReport(
    category: "bug",
    message: "The ferry never arrives",
    screenshot: capturedImage,          // UIImage?, nil for a text report
    metadata: ["zone": "harbour", "attempt": 3]
)
let session = Ravensight.sessionToken

Ravensight.submitReport(report) { result in
    switch result {
    case .success(let receipt):
        print("report \(receipt.reportId ?? receipt.id) saved")
    case .failure(let error)
        where error.code == "upload_failed" || error.code == "report_processing" || error.status == 0:
        // Retry later with the same value, and only while the session is the same one.
        pendingReport = (report, session)
    case .failure(let error):
        print("report refused: \(error.code)")
    }
}

// Later:
if let pending = pendingReport, pending.session != nil, pending.session == Ravensight.sessionToken {
    Ravensight.submitReport(pending.report) { _ in }
}
```

**What it costs.** A text report counts as 1 event on the shared event meter. A screenshot adds 20,000 events, reserved when the report is accepted, which is about $0.01 once the included events are spent. The SDK makes one attempt per step and never retries a report on its own, because a screenshot reserves usage.

**When to retry.** The server recognises a resubmission by the report's `clientId` within one session only. Retry only after `upload_failed`, `report_processing` or a status of 0, with the same `RavensightReport` value and the same session token as the failed attempt: the server finds the existing submission and the SDK carries on from where it stopped. A retry under a different session (after a session expiry, a timeout in the background, `resetDeviceId` or a relaunch) is a new submission, stored again, and a screenshot reserves its events again. The server allows two upload attempts per submission and releases an unfinished screenshot report after 15 minutes. Limits are checked on the device first: a message of 1 to 500 characters, a screenshot of at most 1,000,000 bytes and 4,000,000 pixels, scaled to fit 1600 by 1600. `submitFeedback` stays as the lighter text only call.

## The persisted queue

By default (`persistQueue`; set it to `false` to keep the queue in memory only) the queue is mirrored to one JSON file under Application Support, excluded from backups: at most the newest 500 events, written atomically through one temporary file, coalesced over a quarter of a second, and read right after the client is created. Restored events go out under the current session, each with the `origin` of the session it was tracked in and its original timestamp, and events older than 89 days are not restored. Session tokens, signing secrets and an error's `rs_trail` are never written. The file is deleted on an opt-out, on `stopAllTelemetry`, on `resetDeviceId`, on the kill switch and when the queue drains, and a playtest run never reads or writes it. It narrows the window in which events can be lost; an event tracked a moment before a crash may not have been written yet.

From 0.6.0 timestamps are unix milliseconds, a request body of 1,024 bytes or more is sent gzip compressed, a session that answers with `signing` signs every batch with an HMAC-SHA256 whose secret stays in memory, and `trackAd`, `trackAdRevenue` and `setAttribution` send the [ad and attribution events](https://ravensight.io/docs/dashboard/#typed-events). `sendDeviceInfo` (on by default) sends the model and OS version on the session.

## Queued, accepted and delivered

`track` returning `true` means the event is in the queue on the device, nothing more. Delivery is reported separately: `Ravensight.stats` counts `queued`, `delivered` (events in batches the server answered `202` for), `pending`, `droppedEvents` and `restored`; `lastDelivery` is `.accepted`, `.failed(status:)` or `.offline`; and `onFlush` is called on the main queue after every request that carried events. The server's own `accepted` count in that `202` answer can be lower than the batch the SDK counts as delivered, because an event timestamped more than 90 days ago is dropped without failing the request (see the [HTTP API](https://ravensight.io/docs/http-api/)). Accepted events reach your reports after the server's insert buffer flushes, which takes a few seconds.

```
Ravensight.shared?.onFlush = { outcome in
    if outcome.succeeded {
        print("delivered \(outcome.sent), \(outcome.pending) still queued")
    } else {
        print("not delivered (status \(outcome.status)), will retry")
    }
}
```

## What each SDK supports

Read from each SDK's own source. A cell that says not in this SDK is a feature that SDK does not have. No SDK has a journeys call: journeys are built by the server from the place on the level events you track, with any SDK, on deployments with journey graphs configured.

| SDK | Feedback text | Reports with screenshot | Playtest tagging | Player opt-out | Persisted queue | Journeys |
| --- | --- | --- | --- | --- | --- | --- |
| JavaScript | `submitFeedback` | `submitReport`, from 0.5.1, with `captureScreenshot` for a canvas | Yes | `setEnabled(false)`, not saved by the SDK | `persistQueue`, on by default, from 0.7.0 | Not in this SDK |
| Godot | `submit_feedback` | `submit_report` and an optional capture overlay, from 0.3.1 | Yes | `set_tracking_enabled(false)`, saved | Always on, from 0.5.0 | Not in this SDK |
| LÖVE | `submitFeedback` | `submitReport` with PNG bytes, from 0.5.0 | Yes | `setTrackingEnabled(false)`, saved | Always on, desktop, written on every change from 0.7.0 | Not in this SDK |
| Unity | `SubmitFeedback` | `SubmitReport`, from 0.3.1 | Yes | `SetTrackingEnabled(false)`, saved | Persist Queue, on by default, from 0.5.0 | Not in this SDK |
| Unreal | `SubmitFeedback` | `PrepareReport` and `SubmitReport`, from 0.3.1 | Yes | `SetTrackingEnabled(false)`, saved | Always on, from 0.5.0 | Not in this SDK |
| C++ | `submit_feedback` | `submit_report`, from 0.3.1 | Yes | `set_tracking_enabled(false)`, saved | `persist_queue`, on by default, from 0.5.0 | Not in this SDK |
| Odin | `submit_feedback` | `submit_report` with PNG bytes, from 0.4.0 | Yes | `set_tracking_enabled(client, false)`, saved | Always on, from 0.6.0 | Not in this SDK |
| iOS | `submitFeedback` | `submitReport`, from 0.3.0 | Yes | `setTrackingEnabled(false)`, saved, plus `stopAllTelemetry()` | `persistQueue`, on by default from 0.6.0 | Not in this SDK |
| Android | `submitFeedback` | `submitReport`, from 0.3.1 | Yes | `setTrackingEnabled(context, false)`, saved | `persistQueue`, on by default, from 0.5.0 | Not in this SDK |

Where each SDK finds a playtest run is in the [SDK comparison table](https://ravensight.io/docs/love-sdk/#sdk-compare).

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