跳到內容

開始使用

SDK 是現有司機 App 裡的原生程式庫。iOS 用 Swift package。Android 用 Gradle module。

SDK 跑在 iPhone 與 Android 手機:iOS 16 及以後,Android 10 及以後。不跑在 iPad,也不跑在 Android 9 及更早。宿主 App 仍可以跑在這些裝置。在 iPad,每次呼叫都會被拒絕,state 維持 notReady,beginTrip 交回 ""。部分華為手機在滑走 App 之後,背景記錄會停止。

Android 程式庫宣告 minSdk 29。minSdk 已是 29 或更高的 App 不用再做設定。仍支援 Android 9 或更早的 App,要在 manifest 加入 <uses-sdk tools:overrideLibrary="com.yas.capture" />,並且只在 Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q 時呼叫 YasCapture。

一部手機只維持一個未結束的行程。單一司機時,這部手機是一位司機、一輛車。要換車,先在有行程時呼叫 endTrip,再呼叫 setup。

  1. 每次重新開啟 App,包括由系統重新開啟,都要呼叫 registerAtLaunch。知道司機和車輛後呼叫 setup。每次 setup 都要傳入 tokenProvider。上次開啟時傳入的 tokenProvider 不會留下。
  2. 讀取 openTripId。沒有未結束的行程時是 null。有值就是未結束的行程,包括 startTime 仍在未來。
  3. 預約開始時呼叫 beginTrip,帶上行程 id、開始時間,以及這單的 metadata。記錄不會早於 startTime,也不會早於這次呼叫。Android 還要等 App 回到前景。見 行程。若 openTripId 是另一個 id,先為該行程呼叫 endTrip。若 openTripId 就是這個 id,beginTrip 交回現有的 sessionId,行程維持不變。
  4. 預約結束時呼叫 endTrip,用同一個行程 id、結束時間,以及當時的 metadata。App 在背景時,下次開啟再呼叫,並傳入實際結束時間。tripId 不是 openTripId 時會被拒絕,未結束的行程保持開啟。
  5. SDK 送出由開始記錄至 endTime 的樣本,連同行程上保存的 metadata。需要 bearer 時會呼叫 tokenProvider。
  6. 每次呼叫之後,以及 App 回到前景時,讀取 state。沒有 listener。值是 notReady、idle、recording、incomplete、blocked。見 權限。

在 App 完成啟動之前呼叫 registerAtLaunch,然後讀取 openTripId。下面的 Android 版本是例子。用隨 SDK 提供的版本。

import YasCapture
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
YasCapture.registerAtLaunch()
if YasCapture.shared.openTripId != nil {
// 仍有未結束的行程。見「行程」。
}
return true
}
func application(
_ application: UIApplication,
handleEventsForBackgroundURLSession identifier: String,
completionHandler: @escaping () -> Void
) {
YasCapture.handleEvents(
forBackgroundURLSession: identifier,
completionHandler: completionHandler
)
// 這個 hook 不會呼叫 completionHandler。
// 把 App 自己的 session identifier 交給原本的 owner。
// 由那個 owner 呼叫 completionHandler。
}

沒有呼叫會 throw。被拒絕的 beginTrip 交回 ""。不要把它存成 sessionId。見 行程。

這位司機不用記錄時,不要呼叫 beginTrip。beginTrip 或 endTrip 失敗時,預約照常完成。該單的紀錄會缺失或未完整。

下一步:設定。