Consumer SDK for Android 可讓您使用模組化架構建立共乘應用程式。您可以使用要用於特定應用程式的 API 部分,並與自己的 API 整合。不同功能的 Consumer SDK API 已封裝至不同的模組。
如果您的代僱駕駛服務應用程式使用舊版 Consumer SDK,您必須升級應用程式才能使用這個模組架構。本遷移指南說明如何升級應用程式。
總覽
消費者 SDK 模組架構導入了保留使用者介面狀態的工作階段物件。在舊版 Consumer SDK 中,應用程式會在狀態之間流動。採用這種模組架構時,您可以建立工作階段物件,並選擇在地圖上顯示工作階段。如果未顯示任何工作階段,地圖會顯示空白。不再有「空白」或「已初始化」狀態。
工作階段物件代表模組的單一生命週期使用執行個體。工作階段是模組 API 的存取點。舉例來說,行程分享工作階段會在單趟行程中追蹤。您可以和 Session 物件互動來監控行程。
工作階段物件與模組類型相關聯。工作階段物件的行為與用來初始化物件的生命週期有關。
假設您建立 TripModel
物件來追蹤 TRIP_A。
如果您嘗試再次取得 TRIP_A 的 TripModel
物件,就會取得相同的 TripModel
物件。如要追蹤 TRIP_B,請取得新的 TripModel
物件。
工作階段狀態
工作階段可能處於下列其中一種狀態:
建立的工作階段會以工作階段物件表示。呼叫
create
方法即可建立工作階段。例如:JourneySharingSession sessionA = JourneySharingSession.createInstance(TripModelA)
系統會註冊「啟動」工作階段,以更新其使用者介面元素的資料和值。呼叫
start
方法可啟動工作階段。例如:sessionA.start()
系統隨即會自動啟動「已顯示」的工作階段。此模式會顯示使用者介面 e 元素,並根據資料更新進行更新。如要顯示時段,請呼叫
showSession
方法。例如:ConsumerController.showSession(sessionA)
「已停止」的工作階段會停止重新整理資料,並停止更新使用者介面元素。如要停止工作階段,請呼叫
stop
方法。例如:sessionA.stop()
使用僅限資料和使用者介面元件
您可以使用隨選乘車和運送服務解決方案提供的使用者介面元素 API,建立共乘應用程式。
使用僅限資料元件
如何使用純資料元件建立共乘應用程式:
- 初始化
ConsumerApi
物件。 - 從
ConsumerApi
取得TripModelManager
物件。 - 使用
TripModelManager
開始監控行程,接收TripModel
物件。 - 在
TripModel
物件上註冊回呼。
以下範例顯示如何使用僅限資料元件:
TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = tripManager.getTripModel("trip_A");
tripA.registerTripCallback(new TripModelCallback() {})
使用使用者介面元素 API
使用 ConsumerController
物件存取隨選乘車和配送解決方案使用者介面元素 API。
如要使用「隨選乘車」和「配送服務解決方案」使用者介面元素 API,建立共乘應用程式:
- 將
ConsumerApi
物件初始化。 - 從
ConsumerApi
物件取得TripModelManager
物件。 - 從追蹤一趟行程的
TripModelManager
取得TripModel
物件。 - 將
ConsumerMap[View/Fragment]
新增至應用程式檢視畫面。 - 從
ConsumerMap[View/Fragment]
取得ConsumerController
物件。 - 將
TripModel
物件提供給控制器,以取得JourneySharingSession
物件。 - 使用控制器顯示
JourneySharingSession
。
以下範例說明如何使用使用者介面 API:
TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = TripModelManager.getTripModel("trip_A");
// Session is NOT automatically started when created.
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
JourneySharingSession jsSessionB = JourneySharingSession.createInstance(tripB);
// But a session is automatically started when shown.
ConsumerController.showSession(jsSessionA);
ConsumerController.showSession(jsSessionB); // hides trip A; shows trip B.
ConsumerController.hideAllSessions(); // don't show any sessions
// Unregister listeners and delete UI elements of jsSessionA.
consumerController.showSession(jsSessionA);
jsSessionA.stop();
// Recreates and shows UI elements of jsSessionA.
jsSessionA.start();
模組化架構程式碼變更
如果您的代僱駕駛服務應用程式使用舊版 Consumer SDK,則更新後的模組架構必須對程式碼進行一些變更。本節將說明其中幾項異動。
位置存取權
消費者 SDK 不再需要 FINE_LOCATION
權限。
行程監控
更新後的模組架構需要對資料層和使用者介面使用者的程式碼變更。
在先前版本中,資料層使用者可能會使用下列程式碼處理行程監控:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
manager.registerActiveTripCallback(new TripModelCallback() {})
資料層架構採用模組化架構,因此資料層使用者會使用下列程式碼:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTrip("trip_A")
tripA.registerTripCallback(new TripModelCallback() {})
在先前版本中,使用者介面使用者可能會使用下列程式碼處理行程監控:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
ConsumerController controller = consumerGoogleMap.getConsumerController();
consumerController.startJourneySharing()
以模組化架構來說,使用者介面使用者會使用以下程式碼:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTripModel("trip_A");
ConsumerController controller = consumerGoogleMap.getConsumerController();
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
controller.showSession(jsSessionA);
地圖重新置中
當沒有工作階段運作時,地圖檢視或片段在初始化時不會再縮放至使用者的位置。只要啟用 AutoCamera 功能,它仍會自動縮放並顯示執行中的旅程分享工作階段。預設會啟用 AutoCamera。
在舊版中,您應使用以下程式碼,將攝影機置於目前進行中的工作階段中央:
consumerController.centerMapForState()
以模組化架構來說,您應該使用以下程式碼:
CameraUpdate cameraUpdate = consumerController.getCameraUpdate()
if (cameraUpdate != null) {
googleMap.animateCamera(cameraUpdate);
// OR googleMap.moveCamera(cameraUpdate);
}
如要在舊版中停用 AutoCamera 功能,請使用下列程式碼:
consumerController.disableAutoCamera(true);
以模組化架構來說,您應該使用以下程式碼:
consumerController.setAutoCameraEnabled(false);
自訂
「隨選乘車與配送服務」自訂懸浮動作按鈕 (FAB) 已從地圖中移除。
我們也移除了相關 FAB:
ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()