# Using the SDK

## 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.

```dart
final identity = Identity(
        apiKey: 'apiKey',
        externalReferenceId: 'externalReferenceId');
await DeviceService.instance.initialize(identity: identity);
await DeviceService.instance.activate();
```

## Control Trip Detection and Recording

The trip detection manager must be initialized when the application starts. To initialize the TripDetectionManager you need to provide the `Identity` and various platform specific trip detection parameters, which you can learn more about in the Flutter SDK API reference(link) or platform specific documentation for iOS(link) and Android(link).

```dart
    await TripDetectionManager.instance.initialize(
        identity: identity,
        iosTelemetryEvents: [
          GpsIosTelemetryEvent(),
          SpeedIosTelemetryEvent(),
          GyroscopeIosTelemetryEvent(SamplingRate.oneHz),
          GravityIosTelemetryEvent(SamplingRate.oneHz),
          AccelerometerIosTelemetryEvent(SamplingRate.oneHz),
          UserAccelerationIosTelemetryEvent(SamplingRate.oneHz),
          MagnetometerIosTelemetryEvent(SamplingRate.oneHz)
        ],
        iosFeatures: [IosFeature.geofence, IosFeature.phoneOnlyValidation],
        iosUploadRoute: IosUploadRoute.anyNetwork,
        iosExternalRecordProviders: [
          IosExternalRecordProvider.distracredDriving
        ],
        androidTripDetectors: [
          AndroidTripDetector.activity,
          AndroidTripDetector.geofence,
        ],
        androidTripValidators: [
          AndroidTripValidator.phone,
        ],
        androidTripTelemetry: [
          LocationAndroidTripTelemetry(),
          SpeedAndroidTripTelemetry(),
          DistractedDrivingAndroidTripTelemetry()
        ]);
```

Additionally to inititialize the trip detection manager it is required to pass a [Notification factory class](/readme/android/using-the-sdk/trip-detection-and-recording/trip-manager-configuration.md#notification-factory) to in Android platform code.

```kotlin
TripDetectionManager.notificationFactory = MyNotificationFactory::class.java
```

## Enable Trip Detection and Recording

But trip detection and recording does not happen until you explicitly enable it at least once. Use the `enableTripDetection` method to enable trip detection, recording, and trip file upload. Use the `disableTripDetection` method to stop, such as when the user logs out.

```dart
await TripDetectionManager.instance.enableTripDetection();
```

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

## Programmatically Starting and Stopping Trips

The trip detection manager must be enabled before the trip recorder can be started or stopped programmatically (see previous section).

```dart
await TripDetectionManager.instance.beginTripRecording();

// ...

await TripDetectionManager.instance.endTripRecording();
```

The start command has no effect if the recorder is already started (or if trip detection is disabled), and the stop command has no effect if the recorder's not already running.

* If you have specified no validator on Android (`TripValidator.PHONE` and/or `TripValidator.DEVICE`), then, once started, the trip recorder will continue recording indefinitely until you issue the stop command.
* If you have specified at least one validator on Android, trip recording will stop automatically using the validator, or when you issue the stop command, whichever comes first.

## Trip Recording Status

The app can get a `Stream` that emits an event each time a trip starts or ends.

```dart
TripDetectionManager.instance.tripStartedStream().listen((_) {
    print('A trip has started!');
});

TripDetectionManager.instance.tripEndedStream().listen((_) {
    print('The trip has ended!');
});
```


---

# 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/other-platforms/flutter/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.