為隨選行程提供專屬的消費者體驗，讓他們在行程中輕鬆完成訂單、行程或其他服務。
什麼是 Consumer SDK？
用戶 SDK 是 Fleet Engine 的一部分，用於處理隨選行程。它提供的介面可模擬行程資料，並追蹤 Fleet Engine 中的行程，此外，您還可以使用這些介面建立以地圖為基礎的豐富顯示畫面，與消費者使用者分享行程。您可以將 Consumer SDK 整合至應用程式，並在 Fleet Engine 中設定適當的角色設定檔，以打造這類消費者體驗。
消費者 SDK 平台專屬 API 可讓您在應用程式中原生分享旅程。Consumer SDK 適用於下列平台：
為什麼要使用 Consumer SDK？
將 Consumer SDK 整合至隨選行程應用程式，即可提供完整的消費者體驗，包括近乎即時的位置更新和路線定位。消費者則可在地圖上查看重疊的車輛路線，包括進度詳細資料，方便他們瞭解乘車或外送服務的位置。
消費者 SDK 有哪些功能？
您可以使用 Driver SDK 和 Fleet Engine 中的資訊，打造客製化的消費者體驗，包括下列功能：
根據品牌需求自訂地圖 UI。
追蹤車輛目前的位置，並定期更新其位置，以便車輛沿著路線行駛。
顯示上車和下車地點的預計抵達時間 (ETA)。
顯示剩餘距離。
顯示路線上的即時車流量。
Consumer SDK 的運作方式
大致來說，Consumer SDK 會依賴下列機制：
- 具備適當的 Fleet Engine 角色，讓已驗證的應用程式能夠追蹤與消費者訂單相關聯的行程。
- 用戶與行程之間的關聯 (由後端系統提供)。
TripModel和JourneySharingSessionSDK 類別，用於模擬行程資料，並在消費者應用程式中分享行程工作階段。
Consumer SDK 也提供其他介面和類別，讓您打造豐富的應用程式體驗，並提供詳細資料，例如交通狀況、地圖標記、預估到達時間和路線資料。
下表顯示乘客應用程式所追蹤的旅程流程。
| 1 | 消費者應用程式要求行程 | 您的後端伺服器會收到隨選行程要求，並執行下列操作：
|
| 2 | 司機接受行程 | 司機應用程式會取得行程 ID 和行程資訊，然後司機接受行程。 |
| 3 | 消費者應用程式要求追蹤行程的存取權 | 消費者應用程式會從後端取得行程 ID，並要求開始追蹤行程。 |
| 4 | 駕駛員開始行程 | 當駕駛人使用駕駛應用程式指出行程已開始時，應用程式會透過驅動程式 SDK 通知後端伺服器。例如，司機即將離開餐廳或開往接送地點時。 |
| 5 | Fleet Engine 開始傳送行程資訊 | Fleet Engine 開始追蹤行程，並與消費者應用程式分享進度。 |
| 6 | 消費者應用程式會顯示行程資訊 | 消費者應用程式會通知消費者，並開始向使用者顯示行程資訊，並隨著行程的進展更新行程。 |
| 7 | 行程已取消或完成 | 當駕駛員取消或完成行程時，駕駛員應用程式會停用定位追蹤功能，後端伺服器則會通知車隊引擎將行程標示為已取消或完成。 |
| 8 | 消費者應用程式停止追蹤行程 | 行程顯示為已取消或已完成。 |
| 9 | 在下次行程時重複執行這個程序 | 系統會建立新的行程，並重複這個程序。 |
如何使用 Consumer SDK
請選取您的平台，瞭解如何在消費者應用程式中開始追蹤行程。
Android
| 1 | 在 Android 中設定 Consumer SDK | 如要在應用程式中追蹤隨選行程，請設定 Consumer SDK。詳情請參閱取得 Android Consumer SDK。 |
| 2 | 設定視覺介面 | 定義地圖並新增向量地圖支援功能，以設定消費者體驗。詳情請參閱「設定地圖」。 |
| 3 | 追蹤行程 | 追蹤行程，向消費者分享適當車輛的位置。詳情請參閱「追蹤行程」。 |
| 5 | 更新行程進度及處理行程錯誤 | 更新行程的詳細資料 (例如移動距離和預估抵達時間)，並處理行程期間發生的任何錯誤。詳情請參閱「更新行程進度」和「處理行程錯誤」。 |
| 5 | 行程結束後停止追蹤 | 停止追蹤行程，即可停止與消費者分享車輛位置。詳情請參閱停止追蹤行程。 |
iOS
| 1 | 在 iOS 中設定 Consumer SDK | 如要在應用程式中追蹤隨選行程，請設定 Consumer SDK。詳情請參閱「取得 iOS Consumer SDK」。 |
| 2 | 設定視覺介面 | 初始化地圖檢視畫面並處理地圖事件，以設定消費者體驗。詳情請參閱「設定地圖」。 |
| 3 | 追蹤行程 | 依照行程，將適當車輛的位置分享給消費者。詳情請參閱「追蹤行程」。 |
| 5 | 更新行程進度及處理行程錯誤 | 更新行程的詳細資料 (例如移動距離和預估抵達時間)，並處理行程期間發生的任何錯誤。詳情請參閱「更新行程進度」和「處理行程錯誤」。 |
| 5 | 行程結束後停止追蹤 | 停止追蹤行程，即可停止與消費者分享車輛位置。詳情請參閱「停止追蹤行程」。 |
JavaScript
| 1 | 在 JavaScript 中設定 Consumer SDK | 如要在應用程式中追蹤隨選行程，請設定 Consumer SDK。詳情請參閱「設定 JavaScript Consumer SDK」一文。 |
| 2 | 載入及自訂地圖 | 啟用 Maps JavaScript API 並設定授權，即可設定消費者體驗。詳情請參閱「設定地圖」。 |
| 3 | 追蹤行程 | 依照行程，將適當車輛的位置分享給消費者。詳情請參閱追蹤行程一文。 |
| 5 | 更新行程進度並處理行程錯誤 | 更新行程詳細資料，例如行程距離和預估抵達時間，並處理行程發生的任何錯誤。詳情請參閱「更新並追蹤行程進度」和「處理行程錯誤」。 |
| 5 | 行程結束後停止追蹤 | 停止追蹤行程，即可停止與消費者分享車輛位置。詳情請參閱「停止追蹤行程」。 |
元件
本節將概述追蹤行程所需的兩個必要元件：
您也可以選擇使用這些元件來自訂消費者體驗：
驗證權杖擷取工具
如要控管對儲存在 Fleet Engine 中的定位資料的存取權，您必須執行下列操作：
在伺服器上實作 Fleet Engine 適用的 JSON Web Token (JWT) 建立服務。詳情請參閱「發出 JWT」。
在網頁或行動應用程式中實作驗證權杖擷取器，以便驗證位置資料存取權。如要進一步瞭解如何設定權杖擷取工具，請參閱 Android、iOS 或 JavaScript 的設定指南。
地圖檢視畫面和行程追蹤器
追蹤行程包含車輛和路線點的視覺化元件，以及駕駛員預估抵達時間或剩餘行駛距離的原始資料動態饋給。
下表說明這些元件：
| 元件 | 說明 |
|---|---|
| 消費者地圖檢視畫面 | 地圖檢視畫面會管理行程的生命週期，並在行程進行期間顯示車輛位置的路徑點。如果已知車輛的路線，地圖檢視畫面會更新車輛路線多邊形，以顯示車輛沿路線行駛的進度。 |
| JavaScript 中的行程位置供應器 | 如果是 JavaScript 網頁應用程式，行程地點提供者會將所追蹤物件的位置資訊，提供給共用的行程地圖。詳情請參閱「建立行程位置供應器的例項化」。您可以使用行程位置供應工具，追蹤行程的下列詳細資料：
|
已追蹤的位置物件
位置提供者會追蹤路徑點和車輛等物件的所在位置，詳情請參閱下表。
| 追蹤的位置 | 說明 |
|---|---|
| 取車地點 | 上車地點是行程的起點。 |
| 目的地位置 | 目的地位置是指行程結束的位置。用來標示下車地點。 |
| 路線控點位置 | 路標位置是指沿著追蹤行程路線的任何中途位置。嚴格說來，路線控點可以包含上車和下車地點，但路線控點通常是指路線沿途的中繼停靠站。舉例來說，在運送路線上，從上車地點到目的地之間的停靠站就是路徑點位置。詳情請參閱 Fleet Engine 說明文件中的「行程路線點」。 |
| 車輛位置 | 車輛位置是車輛的回報位置。詳情請參閱 Fleet Engine 說明文件中的「車輛位置」一節。 |
設定地圖樣式
標記和折線樣式會決定地圖上追蹤位置物件的外觀和風格。您可以使用自訂樣式選項，配合網頁應用程式的樣式。
控制追蹤位置的瀏覽權限
Fleet Engine 中預先定義的位置資訊供應器會遵循地圖上追蹤位置物件的這些顯示規則。如果您建立自訂或衍生位置供應器，可以變更瀏覽權限規則。
車輛只會在行程進行中顯示：行程車輛會從指派給行程到下車時間期間顯示。如果行程取消，車輛就不會再顯示。
所有其他地點標記一律顯示：起點、目的地和路線控點的所有其他地點標記一律會顯示在地圖上。舉例來說，無論行程或運送狀態為何，行程下車地點或運送地點一律會顯示在地圖上。
後續步驟
請參閱您要追蹤行程的平台說明文件：