Skip to content

Trips

Field Send
tripId Your id for this job. Use the same id until endTrip.
startTime When recording should start, including the drive to the passenger. Pass a Swift Date or a Kotlin Instant. YAS stores UTC.
endTime When the trip ended. Pass a Swift Date or a Kotlin Instant: the current time, or a time in the past when closing the trip after the fact.
metadata Required. Job details at the time of the call. Field names are agreed per partner and are not listed here.
sessionId Returned by beginTrip. Store it with the booking.

Send beginTrip metadata when the driver starts the job.

startTime is when the driver starts the job. Recording includes the drive to the passenger.

The endTrip metadata replaces the beginTrip metadata. Only the keys on the end metadata are kept. Send every key again.

Call the SDK from the existing trip screen. On launch, read openTripId before beginTrip. Omit the call when the job is only assigned. Arrival and passenger boarding do not need another call. A repeat beginTrip for the open id returns the same sessionId and does not change startTime or the stored metadata.

Booking event SDK
Job assigned No call
Driver starts the job beginTrip
Arrived, passenger onboard No call. The same trip stays open.
Drop-off complete endTrip, including on a later launch if the app was in the background
Job canceled endTrip with the time tracking stopped and the booking status at that time in metadata.state

One booking is open at a time. beginTrip with a different id is rejected. Call endTrip for the open id first. The end time may be in the past.

endTrip with an id other than openTripId is rejected. The open trip stays unchanged. endTrip when openTripId is null does not create a trip. endTrip with an endTime earlier than startTime ends the trip and drops the samples. The closing upload can still send that trip’s metadata with no samples.

beginTrip while state is blocked is not rejected. The trip opens, and state stays blocked. A rejected beginTrip returns "". Do not save it as a sessionId. state and openTripId stay unchanged. It is also rejected before registerAtLaunch, when state is notReady, when tripId is empty, or when metadata is empty or not JSON.

If startTime is in the future, recording waits until that time. If beginTrip is called after startTime and the phone can record, recording starts at the call. Samples from before the call are not available. On Android, starting recording also needs the app in the foreground. A new trip that becomes due in the background stays open and is incomplete unless it is blocked. See Permissions.

endTrip stops recording and keeps samples up to endTime. Samples taken after endTime, because the app was in the background, are omitted from the trace.

The app closes the trip with endTrip. The backend can also close it with POST /v1/vehicles/trips/end (beta). POST /v1/trips/end is deprecated.

jobMetadata is what this call sends. Send every key again on endTrip.

import YasCapture
func driverStartedJob(tripId: String, startTime: Date, jobMetadata: [String: Any]) {
if let openId = YasCapture.shared.openTripId, openId != tripId {
return // Call endTrip for openId first.
}
let sessionId = YasCapture.shared.beginTrip(
tripId: tripId,
startTime: startTime,
metadata: jobMetadata
)
if sessionId.isEmpty { return }
saveSessionId(sessionId, for: tripId)
}
func jobEnded(tripId: String, endTime: Date, jobMetadata: [String: Any]) {
YasCapture.shared.endTrip(
tripId: tripId,
endTime: endTime,
metadata: jobMetadata
)
}

Next: Authentication.