Skip to content

Getting Started

Add RoadSaveKit to your iOS app and start detecting crashes and trips in minutes.

Overview

RoadSaveKit gives your app crash detection, trip detection, and activity recognition powered by the RoadSave platform. This article walks you from installation to your first crash-detection callback in four steps.

Requirements

Requirement Minimum
iOS deployment target 17.0
Xcode 16.0
Swift 5.9
Distribution Swift Package Manager only (see note below)

CocoaPods is not supported. The legacy 3.x SDK was only exposed via CocoaPods as a transitive dev dependency for AFNetworking; version 4.0 distributes exclusively through Swift Package Manager. Consumers migrating from 3.x should remove their Podfile entry and follow Step 1 below.

Step 1 — Add the Package (Swift Package Manager)

In Xcode, choose File → Add Package Dependencies and enter the repository URL:

https://github.com/Dynamus-Technologies/roadsave-ios-sdk

Select a version starting from 4.0.0 and add RoadSaveKit to your app target.

Alternatively, add it to Package.swift:

dependencies: [
    .package(url: "https://github.com/Dynamus-Technologies/roadsave-ios-sdk", from: "4.0.0")
],
targets: [
    .target(name: "MyApp", dependencies: ["RoadSaveKit"])
]

Step 2 — Add Required Permissions

RoadSaveKit uses location and motion hardware. Add the following keys to your Info.plist:

Key Purpose
NSLocationAlwaysAndWhenInUseUsageDescription Required for background trip and crash detection
NSMotionUsageDescription Required for activity recognition and crash detection

Important: Always-on location permission is mandatory. Trip and crash detection cannot function with "When In Use" permission alone.

Background Modes entitlement

The SDK monitors location while the app is in the background. Add location to UIBackgroundModes in your Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

Or via Xcode's Signing & Capabilities tab: add the Background Modes capability and enable Location updates.

Note: The SDK cannot declare background modes on your app's behalf — this entitlement must be added to the host app target directly. Without it, the system will suspend location updates when the app backgrounds, and trip detection will not function correctly.

Step 3 — Configure at Startup

Call RoadSaveSDK/configure(with:) once, before any other SDK calls. Place this in application(_:didFinishLaunchingWithOptions:) or your SwiftUI App.init:

import RoadSaveKit

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    Task {
        let config = RoadSaveConfiguration(
            applicationID: "your-app-id",
            clientUserID: currentUser.id
        )
        do {
            try await RoadSaveSDK.shared.configure(with: config)
        } catch {
            print("SDK configuration failed: \(error)")
        }
    }
    return true
}

Step 4 — Set a Delegate and Start Monitoring

await RoadSaveSDK.shared.setDelegate(self)
try await RoadSaveSDK.shared.startMonitoring()

Implement RoadSaveDelegate to receive events:

extension AppDelegate: RoadSaveDelegate {
    func tripDidStart(_ tripInfo: TripStartInfo) {
        print("Trip started: \(tripInfo.tripID)")
    }

    func tripDidEnd(_ tripInfo: TripInfo) {
        print("Trip ended. Distance: \(tripInfo.distanceMetres)m")
    }

    /// Fired once per crash, only after the server evaluation round-trip completes.
    /// `crashInfo.confidence` reflects the server's verdict. If the server returns
    /// "None", this callback is suppressed entirely.
    func crashDetected(_ crashInfo: CrashInfo) {
        if crashInfo.confidence == .unknown {
            // Server unreachable — show a softer "possible crash" message.
            presentCrashAlert(for: crashInfo)
        } else {
            // Server-confirmed crash.
            presentCrashAlert(for: crashInfo)
            uploadCrashReport(crashInfo)
        }
    }
}

Next Steps