# Using the SDK

A few general notes:

* Customers should avoid using `TripDetector` directly; to ensure proper functionality, customers should only use the public class `TripDetectionManager`;
* `TripDetectionManager` can be accidentally initialized multiple times; this got fixed and we print a warning for this now.
* Show thread name in log file (“main” or “other”).
* Log current thread on `Common.initialize` and `TripDetectionManager.enable`; initializing the SDK and enabling trip detection outside of main thread may cause issues for trip detection.

## Device Activation (aka Phone Registration)

The user's phone must be registered through the `Portal` before trips recorded on that phone can be uploaded. Depending on the activation method, as selected by the host app, the device may only require one activation.

**There is currently a limit of one registered phone per user account.** If the same user logs in and registers a second phone, trips from the first phone will no longer get uploaded to the server.

Use the DeviceService to activate the device (register the phone) **before** you start recording trips.

```swift
let deviceService = DeviceService(identity: identity)
deviceService.activate(then: { result in
    guard let device = result.value else {
        print("Something went wrong.")
        return
    }
    // Additional activation for the device.
})
```

## Control Trip Detection and Recording

To utilize trip detection, recording, and uploading features, it is essential to initialize the trip detection manager. We highly advise performing this initialization process upon application launch. Once the trip detection manager is initialized, you will have access to `enable` and `disable` functionalities.

To activate trip detection, recording, and file upload, utilize the `enable` function. Additionally, there is a callback function available: \`tripStateHandler\` , which triggers when a potential trip starts, trip is confirmed and trip is ended.

Use the `disable` function to stop, such as when the user logs out.

Note that once trip detection is enabled, it remains enabled even if the application restarts or the phone reboots. You only need to explicitly re-enable it if you previously disabled it.

```swift
// Enable Trip Detection
tripDetectionManager?.enable(tripStateHandler: { (state, date) in
        switch state {
        case .potentialTrip:
            // Potential trip
        case .confirmedTrip:
            // Confirmed trip
        case .endedTrip:
            // Trip ended
        @unknown default:
            // Error fetching trip states with date!
        }
})

// Disable Trip Detection
tripDetectionManager?.disable()
```

## Manual Trip Recording and Uploading

Trip detecting, recording, and uploading will be performed automatically once the `enable` function is called. If you prefer manual control over recording and uploading trips, you can use the following functions:

* Use `beginTripRecording` to start trip recording

```
// Start recording the trip manually
tripDetectionManager?.beginTripRecording()
```

* Use `endTripRecording` to stop trip recording

```
// Stop recording the trip manually
tripDetectionManager?.endTripRecording()
```

* Use `uploaAll` to upload all the trip data

```
// Upload all trip data
tripDetectionManager?.uploadAll()
```

* Use `tripsToUplaod` to see the number of trips that are ready to upload. Note the this number will be increased when a trip is recorded without a network connection.

```
// see the number of trips that are ready to upload
tripDetectionManager?.tripsToUplaod()
```

* Use `deleteAll()` to remove all persisted trip data and logs from the device. This can be useful when a user logs out.

```
// Delete all persisted trip data and logs
tripDetectionManager?.deleteAll()
```

## Controlling how the files are uploaded

At the time of SDK initialization, if the host app wants it can select the upload route for uploading the trip files to the DriveSync server.

SDK has two upload routes host app can choose:

* **`.wifiOnly:`** Upload data only when connected to a WiFi network.
* **`.anyNetwork:`** Upload data when connected to any network.

If the host app doesn't pass the upload route, the SDK will choose `.anyNetwork` by default for uploading the trip files.

See below example for passing the upload route:

```swift
let manager = TripDetectionManager(identity: Identity,
                                    uploadRoute: .wifiOnly,
                                    telemetryEvents: Set,TelemetryEvent>,
                                    externalRecordProviders: [Factory<ExternalRecordProvider>],
                                    features: [Feature])
```

Also, after initialization the upload route settings can be changed.

See below example:

```swift
manager.uploadRoute = .wifiOnly
```

## Logging the message

The log function will log the message into SDK log file. Please make sure to import the `Common` framework. There are 4 levels for the log message, which are debug, info, warning and error.

```swift
import Common

// Debug level
log.d("Debug message")

// Info level
log.i("Info message")

// Warning level
log.w("Warning message")

// Error level
log.e("Error message")
```

The format of the log message will be:

```
[Local Time] [Log Level] [Thread] [File Name] [Function Name]:[Line] - [Message]
```

Here is an example of the log

```
2023-11-02T15:30:42.508-04:00 [INFO] <0x700380 (MAIN)> ContentView.swift - logMessageFunction():26 -message
```

All the logs will be stored in the `log` directory under the app directory. You can use the app directory, which from initializing sdk, to get the log directory.

```swift
// this directory is created when initializing the sdk
let sdkDirectory = Directories(root:
                                try! FileManager.default.url(
                                    for: .documentDirectory,
                                    in: .userDomainMask,
                                    appropriateFor: nil,
                                    create: true).appendingPathComponent("SDK"))

// get the log directory path using the sdk directory
let logURL = sdkDirectory.logs

do {
    // get all files from log directory
    let logFiles = try FileManager.default.contentsOfDirectory(at: logUrl, includingPropertiesForKeys: nil)
    for file in logFiles {
        // do something with log files
    }
} catch {
    print("Error")
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdk.ims.tech/readme/ios/using-the-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.