Ravensight

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.

CallSavedNormal sessionSynthetic (playtest) session
setTrackingEnabled(false)YesQueue cleared, no request of any kind, now and on every later launch.Ignored, with one console line. The run carries on.
stopAllTelemetry()NoEverything stops for this run. The next launch starts normally. resumeTelemetry() undoes it, and a saved opt-out still wins.The run stops sending.
resetDeviceId()YesA 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.

SDKFeedback textReports with screenshotPlaytest taggingPlayer opt-outPersisted queueJourneys
JavaScriptsubmitFeedbacksubmitReport, from 0.5.1, with captureScreenshot for a canvasYessetEnabled(false), not saved by the SDKpersistQueue, on by default, from 0.7.0Not in this SDK
Godotsubmit_feedbacksubmit_report and an optional capture overlay, from 0.3.1Yesset_tracking_enabled(false), savedAlways on, from 0.5.0Not in this SDK
LÖVEsubmitFeedbacksubmitReport with PNG bytes, from 0.5.0YessetTrackingEnabled(false), savedAlways on, desktop, written on every change from 0.7.0Not in this SDK
UnitySubmitFeedbackSubmitReport, from 0.3.1YesSetTrackingEnabled(false), savedPersist Queue, on by default, from 0.5.0Not in this SDK
UnrealSubmitFeedbackPrepareReport and SubmitReport, from 0.3.1YesSetTrackingEnabled(false), savedAlways on, from 0.5.0Not in this SDK
C++submit_feedbacksubmit_report, from 0.3.1Yesset_tracking_enabled(false), savedpersist_queue, on by default, from 0.5.0Not in this SDK
Odinsubmit_feedbacksubmit_report with PNG bytes, from 0.4.0Yesset_tracking_enabled(client, false), savedAlways on, from 0.6.0Not in this SDK
iOSsubmitFeedbacksubmitReport, from 0.3.0YessetTrackingEnabled(false), saved, plus stopAllTelemetry()persistQueue, on by default from 0.6.0Not in this SDK
AndroidsubmitFeedbacksubmitReport, from 0.3.1YessetTrackingEnabled(context, false), savedpersistQueue, on by default, from 0.5.0Not in this SDK

Where each SDK finds a playtest run is in the SDK comparison table.