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. 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.
To confirm which environment a build's key reaches, see
Which environment does this key hit?
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-<runId>,
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.
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). 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.