iOS TripWrapper SDK - scopetech/Mobile-Public GitHub Wiki

TripWrapper is a Swift SDK that acts as the integration layer between your iOS application and the SCPSmartDrive trip-recording framework. It handles the full trip lifecycle — detection, recording, validation, and server upload — so your application code stays clean and focused on user experience.

• Implements SCPSmartDriveManagerDelegate so your app code never needs to
• Automatically detects trip start and stop events
• Validates, packages, and uploads trip data to your server
• Retries failed uploads without any app-side logic
• Delivers trip lifecycle events to your app via a simple delegate
• Routes push notifications through an optional delegate

TripWrapper sits between the SCPSmartDrive SDK and your application, acting as the single owner of all trip-related SDK callbacks.

⚠️ Critical rule: only TripWrapper may register as SCPSmartDriveManagerDelegate. Registering any other class as a delegate for trip lifecycle events will cause missed or duplicate callbacks.

Add the following keys to your Info.plist:

In your Xcode target → Signing & Capabilities, enable:

• Background Modes → Location updates
• Background Modes → Background fetch

Create a single class that implements all required TripWrapper protocols. A coordinator pattern keeps the bridge code isolated from your business logic.

TripWrapper uses a protocol-based design. Each protocol has a single responsibility and must be satisfied at initialisation time unless marked optional.

Bridges TripWrapper's outbound API calls to your networking layer.

Supplies the unique identifier that links each trip to a physical device.

Controls trip recording and upload behaviour. TripWrapper queries these values at runtime so you can change them without re-initialising.

Routes TripWrapper internal events to your app’s logging infrastructure.

Delivers trip lifecycle events to your application. Set TripWrapper.shared.delegate before any trips can start.

All methods are @objc optional. Implement only the notifications your app needs. TripWrapper checks configuration before calling each method.

TripRecord is the read-only data object passed to your delegate and returned by all query methods.

Call once, early in your application lifecycle. Calling initialize() a second time is a no-op.

Call once, early in your application lifecycle. Calling initialize() a second time is a no-op.

If your app previously used SCPSmartDriveManagerDelegate directly, follow this guide to migrate cleanly.

1. Remove all SCPSmartDriveManagerDelegate conformances except TripWrapper’s
2. Remove any addNewDelegateObject() calls that register non-TripWrapper objects for trip events
3. Remove all local trip sending, retry, and lifecycle logic (TripWrapper owns this now)
4. Create your TripCoordinator class implementing all TripWrapper protocols
5. Call TripWrapper.shared.initialize() in AppDelegate
6. Implement TripWrapperDelegate on AppDelegate (or a dedicated class)
7. Replace all SCPSmartDriveManager trip access calls with TripWrapper equivalents

Use this checklist before submitting your integration for review.

Installation

• All Swift packages are added to the project
• Info.plist contains NSLocationAlwaysAndWhenInUseUsageDescription
• Background Modes: Location updates and Background fetch enabled

Initialisation

• TripWrapper.shared.initialize() called in didFinishLaunchingWithOptions
• All four required protocols provided (APIManager, Logger, DeviceID, Config)
• TripWrapper.shared.delegate set before any trip can start

Architecture

• Only TripWrapper implements SCPSmartDriveManagerDelegate
• No addNewDelegateObject() calls for other classes in trip lifecycle
• No local trip sending or retry logic in app code

Notifications (if applicable)

• Notification permission requested at app launch
• TripNotificationDelegate checks application state before scheduling
• cancelTripEndNotification() implemented if scheduleTripEndNotification() is

Testing

• TripWrapper.shared.getDiagnostics().isHealthy returns true
• TripWrapper.shared.getMissingProtocols() returns empty array
• A full trip (start → drive → stop → upload) verified on a real device
• Failed trip retry verified (disable network, complete trip, re-enable)
• Background notification verified with app in background

Logging

• LoggingProtocol implementation routes all events to your log store
• Diagnostic report generation tested and output reviewed