Permissions
The SDK records only after the driver has granted location. The app supplies the explanation shown to the driver. The SDK reports blocked when it cannot record.
- Add Location updates and Background processing to Background Modes.
- List
com.yas.capture.uploadinBGTaskSchedulerPermittedIdentifiers. The SDK registers this processing handler atregisterAtLaunch. It is a task identifier, not a background URL session identifier. Do not register a second handler for it. - Add the Always and When-In-Use usage strings. State that the active trip is being recorded. Use the sentences agreed for your partner.
- Request Always location, with Precise Location, before the first booking. Only Always with full accuracy can record. When In Use is
blocked. - Set
NSLocationDefaultAccuracyReducedto false. That is a default. It does not grant permission, and it does not override the driver’s Precise Location choice. - Add the Motion usage string. The SDK reads motion only during an open booking. Accelerometer and gyroscope do not present a separate prompt.
Replace the sentences below with the copy agreed for your partner. com.yas.capture.upload must match that string.
<key>NSLocationWhenInUseUsageDescription</key><string>Records the route of the active trip.</string><key>NSLocationAlwaysAndWhenInUseUsageDescription</key><string>Records the route of the active trip while the app is in the background.</string><key>NSMotionUsageDescription</key><string>Reads motion during an active trip.</string><key>NSLocationDefaultAccuracyReduced</key><false/><key>UIBackgroundModes</key><array> <string>location</string> <string>processing</string></array><key>BGTaskSchedulerPermittedIdentifiers</key><array> <string>com.yas.capture.upload</string></array>If the driver selects When In Use, or reduced accuracy, state becomes blocked. Once a trip is open, a missing Location updates background mode does the same.
Android
Section titled “Android”- Declare fine location, background location, and the location foreground-service permissions below.
- Request fine location first, together with coarse location. Request background location in a second step. Do not request foreground and background location in one dialog. On Android 10 the second step is a runtime permission. On Android 11 and later it opens the app settings so the driver can choose Allow all the time.
- Approximate location only is
blocked. - The SDK posts an ongoing notification for the open booking. It stays until
endTrip. The title is agreed per partner. The notification is required for background recording. - On Android 13 and later, request notification permission so the notification can appear. Without it, or if notifications are turned off,
statebecomesblocked.
minSdk is 29. The SDK merges com.yas.capture.TripCaptureService with android:exported="false" and android:foregroundServiceType="location". Do not declare that service again.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /><uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /><uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /><uses-permission android:name="android.permission.FOREGROUND_SERVICE" /><uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" /><uses-permission android:name="android.permission.POST_NOTIFICATIONS" />If the driver denies location, or turns it off during the booking, the booking can still be completed. The trace is incomplete. Call endTrip in the same way.
state reports whether the SDK is recording. metadata.state is the booking status sent with the call. Booking completion does not depend on capture status.
Exactly one value applies. Use the first matching row.
state |
When |
|---|---|
notReady |
setup has not succeeded. |
blocked |
The phone cannot record. Location is denied or off. On iOS, When In Use or reduced accuracy is blocked; only Always with Precise Location can record. Once a trip is open, a missing Location updates background mode is also blocked. On Android, approximate location only is blocked. On Android 13 and later, denied notification permission, or notifications turned off, is blocked. |
incomplete |
This trip already has a gap, and the phone can record again. The system ended the app, the driver swiped it away, the phone rebooted, or recording was turned off. Location and motion may still be recorded after that. The gap stays in the trace. |
recording |
A trip is open, now is at or after startTime, no earlier row applies, and sensors are running. |
idle |
setup succeeded and the phone can record, and sensors are not running. No trip is open, or beginTrip was called and startTime is still in the future. |
After endTrip, state is idle when the phone can record. If the phone still cannot record, state stays blocked. While a trip is still open, a gap leaves state at incomplete. Restoring permission does not clear it. If startTime is still in the future and the phone can record, state is idle.
On Android, a new trip starts recording only while the app is in the foreground. If beginTrip is called in the background, or startTime arrives while the app is in the background, the trip stays open but recording waits. Once the trip is due, state is incomplete unless the phone is blocked. Returning to the foreground can start recording. incomplete stays until endTrip.
