iOS TripWrapper SDK

1. Overview

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.

1.1. What TripWrapper Does

• 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

1.2. Architecture

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.

2. Requirements

2.1 Required Entitlements & Permissions

Add the following keys to your Info.plist:

In your Xcode target → Signing & Capabilities, enable:

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

3. Quick Start

Step 1 — Create a coordinator class

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

Step 2 — Initialise in AppDelegate

Step 3 — Handle trip events

4. Protocol Reference

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

4.1 APIManagerProtocol

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

4.2 DeviceIDProvider

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

4.3 TripConfigProvider

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

4.4 LoggingProtocol

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

4.5 TripWrapperDelegate

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

4.6 TripNotificationDelegate (Optional)

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

5. TripRecord Data Model

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

6. TripWrapper API Reference

6.1 Initialisation

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

6.2 Trip Access

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

6.3 Trip Actions

6.4 Diagnostics

7. Migrating from Direct SCPSmartDrive Integration

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

7.1 Key Rule

7.2 Migration Steps

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

7.3 API Mapping

8. Integration Checklist

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