Skip to main content

Android Trip Feature

Our SDK can manage for you the notion of trip, giving you useful data like traveled distance or the start time of the user's last ongoing stop.

Get the SDK instance​

After initialization, use the shared instance to access trip APIs.

// Initialize once (e.g., in Application.onCreate)
val sdk = SafeRider.initialize(appContext, "<API_KEY>")

// Later, anywhere in the app
val safeRider = SafeRider.sharedInstance

Manage a trip​

Trip status​

// Public type exposed by the SDK
sealed class LRTripStatus {
    data class Ongoing(
        val tripStartTime: Long,      // UTC epoch millis
        val distanceMeter: Double,    // meters since tripStartTime
        val dwellStartTime: Long?     // UTC epoch millis or null if moving
    ) : LRTripStatus()

    data object None : LRTripStatus()
}

The LRTripStatus gives you useful data about an ongoing trip:

  • tripStartTime: UTC epoch milliseconds when the trip started.
  • distanceMeter: total traveled distance in meters since tripStartTime.
  • dwellStartTime: UTC epoch milliseconds when the last dwell started, or null if the user is currently moving.

Start a trip​

Start a manual trip. If a trip is already running, the current status is returned.

val status: SafeRider.LRTripStatus.Ongoing =
    SafeRider.sharedInstance.startTrip()

Stop a trip​

Stop the current manual trip.

SafeRider.sharedInstance.stopTrip()

Collect tripStatusFlow to be notified of changes, and read tripStatus for an immediate snapshot.

val sdk = SafeRider.sharedInstance

// Snapshot
val current: SafeRider.LRTripStatus = sdk.tripStatus

// Reactive updates
sdk.tripStatusFlow.collect { status ->
    when (status) {
        is SafeRider.LRTripStatus.Ongoing -> {
            // status.tripStartTime, status.distanceMeter, status.dwellStartTime
        }
        SafeRider.LRTripStatus.None -> {
            // No active trip
        }
    }
}

Use a listener (Java/Kotlin)​

Register a listener if you cannot use coroutines/Flow.

val sdk = SafeRider.sharedInstance

val listener = object : SafeRider.LRTripStatusListener {
    override fun onTripStatusChanged(tripStatus: SafeRider.LRTripStatus) {
        when (tripStatus) {
            is SafeRider.LRTripStatus.Ongoing -> {
                // tripStatus.tripStartTime, tripStatus.distanceMeter, tripStatus.dwellStartTime
            }
            SafeRider.LRTripStatus.None -> { /* No trip */ }
        }
    }
}

sdk.addTripStatusListener(listener)
// Later
sdk.removeTripStatusListener(listener)

Notes​

  • tripStatusFlow is a StateFlow: the first emission is always the current state.
  • Public APIs are intended to be called from the main thread.
  • During a manual trip, automatic trip detection analysis is muted and is unmuted when the trip stops.
  • There is no dedicated trip status error stream on Android; implement your own guards as needed.