Integrate an iOS app with Logister.

Before you start

Create the project with the iOS integration type.

What is supported

The iOS SDK starts with explicit, app-controlled telemetry.

Install

Add the package from GitHub with Swift Package Manager.

The current public iOS package version is 0.1.1. In Xcode, add the package URL https://github.com/taimoorq/logister-ios.git, choose the version rule your app prefers, and add the Logister product to your app target.

dependencies: [
    .package(url: "https://github.com/taimoorq/logister-ios.git", from: "0.1.1")
]

.product(name: "Logister", package: "logister-ios")

• Use the Swift Package repository for source, Package.swift, tests, and release metadata.
• Open the v0.1.1 GitHub Release for the current tagged package release.
• Swift Package Manager resolves versions from Git tags, so there is no separate iOS package registry account or package page.

Configure

Create one client with app and release defaults.

Use the app bundle ID as service, include the app version/build in release, and attach safe default context that helps investigation.

import Foundation
import Logister

let client = LogisterClient(
    apiKey: "your-project-api-token",
    baseURL: URL(string: "https://your-logister-host.example")!,
    environment: "production",
    release: "1.4.0+42",
    repository: "acme/ios-app",
    commitSHA: "4f8c2d1",
    branch: "main",
    service: Bundle.main.bundleIdentifier,
    defaultContext: [
        "app_version": .string("1.4.0"),
        "build_number": .string("42"),
        "device_model": .string("iPhone")
    ]
)

Keep real project API tokens out of source control. Prefer configuration, build-time secrets, or another runtime source that matches your app's security model. Use a build setting or generated file for commitSHA and branch so shipped events point at the source that produced the app build.

Source and deployments

Attach source context in the app, and record deployments from CI/CD.

The Swift client adds repository, commit_sha, and branch to event context when you set repository, commitSHA, and branch on LogisterClient. If the project is connected to the GitHub App, Logister can use those values to resolve stack frames and link to source.

Deployment records should be sent from CI/CD, not from the mobile app. After an App Store, TestFlight, Firebase App Distribution, internal, or enterprise deploy succeeds, POST a deployment envelope to /api/v1/deployments with the release, environment, repository, commit SHA, branch, and workflow URL.

{
  "deployment": {
    "release": "1.4.0+42",
    "environment": "production",
    "repository": "acme/ios-app",
    "commit_sha": "4f8c2d1a9b7e6c5d4a3b2c1d0e9f8a7b6c5d4e3f",
    "branch": "main",
    "release_tag": "ios-v1.4.0",
    "workflow_run_url": "https://github.com/acme/ios-app/actions/runs/123"
  }
}

Events

Send errors, logs, metrics, and transactions with async Swift.

try await client.captureMessage(
    "Checkout opened",
    options: LogisterEventOptions(
        sessionID: "session-123",
        context: ["screen_name": .string("Checkout")]
    )
)

try await client.captureMetric("cart.item_count", value: 3, unit: "count")

try await client.captureTransaction(
    "screen.load",
    durationMs: 142.7,
    options: LogisterEventOptions(context: ["screen_name": .string("Checkout")])
)

do {
    try await runCheckout()
} catch {
    try await client.captureException(error)
}

Captured errors include structured exception context and call stack symbols. Metric values should use stable names and units, and transactions should describe app work such as screen loads, local processing, sync jobs, or API calls.

Spans and check-ins

Use spans for waterfalls and check-ins for recurring iOS work.

try await client.captureSpan(
    LogisterSpan(
        traceID: "trace-123",
        spanID: "span-456",
        parentSpanID: "span-root",
        name: "GET /checkout",
        kind: "http",
        status: "ok",
        durationMs: 42.5,
        context: ["screen_name": .string("Checkout")]
    )
)

try await client.checkIn(
    "daily-sync",
    status: "ok",
    options: LogisterEventOptions(
        durationMs: 812.4,
        context: ["expected_interval_seconds": .number(86_400)]
    )
)

Use shared trace IDs when a screen action triggers multiple spans. Check-ins are useful for recurring sync, cleanup, cache refresh, background fetch, or other scheduled app work where a missed run should be visible.

Mobile context

Send safe iOS metadata that helps debugging without collecting secrets.

Privacy defaults

Keep iOS instrumentation explicit.

The iOS add-on starts with manual capture methods. Automatic crash breadcrumbs, screen timing, URLSession timing, retry, and offline-queue instrumentation should stay opt-in so each app can decide what data is collected, retained, and sent over the network.

• Do not send API tokens, authorization headers, cookies, payment data, medical data, or raw request/response bodies.
• Prefer stable, low-cardinality values such as screen names, feature names, build metadata, status codes, and safe session IDs.
• Use the app's privacy review before sending device identifiers, user identifiers, query text, or raw URLs.

Verification

Confirm one event from the app before widening instrumentation.

Swift Package Manager resolves the Logister product
client can send one captureMessage call
Activity page shows the iOS log event
Inbox shows a test exception when captureException is called
Insights can filter by environment, release, service, or screen_name
Performance shows transactions or spans after timing events arrive
Event detail shows source context when repository and commitSHA are configured
Event detail shows deployment context after CI posts /api/v1/deployments

Package releases

iOS SDK releases are versioned separately from the Rails app.

Swift Package Manager distribution resolves from the public Git repository and semantic version tags. The iOS release workflow verifies the package and creates the matching GitHub Release, so app teams can update through Xcode or SwiftPM when a new tag is available.

• SDK source and SwiftPM URL: github.com/taimoorq/logister-ios
• Current release: v0.1.1
• Package product: Logister