權限
司機允許定位之後,SDK 才會記錄。向司機顯示的說明由 App 提供。無法記錄時,SDK 回報 blocked。
iOS
小節:iOS- 在 Background Modes 加入 Location updates 與 Background processing。
- 在
BGTaskSchedulerPermittedIdentifiers列出com.yas.capture.upload。SDK 在registerAtLaunch註冊這個 processing handler。它是 task identifier,不是 background URL session identifier。不要為它再註冊第二個 handler。 - 加入 Always 與 When-In-Use 的用途說明,寫明正在記錄這趟行程。用該合作夥伴約定的句子。
- 第一張預約之前,要求 Always 定位,並開啟 Precise Location。只有 Always 加完整精度可以記錄。When In Use 是
blocked。 - 把
NSLocationDefaultAccuracyReduced設為 false。這是預設值。它不是權限授予,也不會覆蓋司機對 Precise Location 的選擇。 - 加入 Motion 的用途說明。SDK 只在行程開啟時讀取動態。加速度計和陀螺儀不會另外彈出提示。
下面的句子換成該合作夥伴約定的文案。com.yas.capture.upload 必須完全一致。
<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>司機選擇 When In Use,或較低精度時,state 變成 blocked。行程開啟後,缺少 Location updates background mode 也一樣。
Android
小節:Android- 宣告精確定位、背景定位,以及下面的定位前景服務權限。
- 先要求精確定位,連同 coarse location 一起。背景定位是第二步。不要在同一個對話框要求前景和背景定位。Android 10 的第二步是 runtime permission。Android 11 及以後會開啟 App 設定,讓司機選擇 Allow all the time。
- 只有大約位置是
blocked。 - SDK 為開啟中的預約顯示持續通知,一直留到
endTrip。標題按合作夥伴約定。背景記錄需要這則通知。 - Android 13 及以後,要先取得通知權限,通知才會出現。沒有權限,或系統設定關掉通知時,
state變成blocked。
minSdk 是 29。SDK 會 merge com.yas.capture.TripCaptureService,android:exported="false",android:foregroundServiceType="location"。不要再宣告這個 service。
<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" />司機拒絕定位,或在預約中途關掉定位,預約仍可完成。紀錄會未完整。同樣要呼叫 endTrip。
state
小節:statestate 表示 SDK 是否正在記錄。metadata.state 是隨呼叫送出的預約狀態。預約能否完成,不取決於記錄狀態。
只會有一個值。用第一條符合的行。
state |
何時 |
|---|---|
notReady |
setup 尚未成功。 |
blocked |
手機無法記錄。定位被拒或已關閉。iOS 上 When In Use 或較低精度是 blocked;只有 Always 加 Precise Location 可以記錄。行程開啟後,缺少 Location updates background mode 也是 blocked。Android 上只有大約位置是 blocked。Android 13 及以後,通知權限被拒,或系統設定關掉通知,是 blocked。 |
incomplete |
這趟行程已有一段空缺,而手機可以再記錄。系統結束了 App、司機把 App 滑走、手機重啟,或記錄被關掉。其後仍可能寫入定位和動態。空缺會留在紀錄裡。 |
recording |
行程開啟,現在已到或已過 startTime,前面的行都不符合,感應器正在運作。 |
idle |
setup 已成功,手機可以記錄,感應器未在運作。沒有開啟的行程,或已呼叫 beginTrip 而 startTime 仍在未來。 |
endTrip 之後,手機可以記錄時 state 是 idle。手機仍然無法記錄時,state 維持 blocked。行程仍開啟時,一段空缺會令 state 停在 incomplete。重新允許權限不會清掉它。手機可以記錄而 startTime 仍在未來時,state 維持 idle。
Android 上,新行程只在 App 在前景時開始記錄。在背景呼叫 beginTrip,或到達 startTime 時 App 仍在背景,行程保持開啟,但記錄會等待。到達開始時間後,手機不是 blocked 時,state 是 incomplete。回到前景後可以開始記錄。incomplete 一直留到 endTrip。
