Yêu cầu tối thiểu về hệ thống
Thiết bị di động phải chạy Android 6.0 (API cấp 23) trở lên.
Cấu hình bản dựng và phần phụ thuộc
SDK trình điều khiển phiên bản 4.99 trở lên có trong kho lưu trữ Maven của Google.
Gradle
Thêm đoạn mã sau vào tệp build.gradle
của bạn:
repositories {
...
google()
}
Maven
Thêm đoạn mã sau vào tệp pom.xml
của bạn:
<project>
...
<repositories>
<repository>
<id>google-maven-repository</id>
<url>https://maven.google.com</url>
</repository>
</repositories>
...
</project>
Cấu hình dự án
Để sử dụng SDK trình điều khiển, ứng dụng của bạn phải nhắm đến minSdkVersion
23 trở lên. Để biết thêm thông tin, hãy xem phần Ghi chú phát hành.
Để chạy một ứng dụng được tạo bằng SDK trình điều khiển, thiết bị Android phải cài đặt Dịch vụ Google Play.
Thiết lập dự án phát triển
Cách thiết lập dự án phát triển và lấy khoá API cho dự án trên Google Cloud Console:
Tạo dự án Google Cloud Console mới hoặc chọn một dự án hiện có để sử dụng với SDK Trình điều khiển. Đợi vài phút cho đến khi dự án mới xuất hiện trên Google Cloud Console.
Để chạy ứng dụng minh hoạ, dự án của bạn phải có quyền truy cập vào SDK Maps dành cho Android. Trong Google Cloud Console, hãy chọn APIs & Services > Library (API và dịch vụ > Thư viện), sau đó tìm kiếm và bật SDK Maps cho Android.
Lấy khoá API cho dự án bằng cách chọn APIs & Services > Credentials > Create credentials > API key (API và Dịch vụ > Thông tin xác thực > Tạo thông tin xác thực > Khoá API). Để biết thêm thông tin về cách lấy khoá API, hãy xem bài viết Lấy khoá API.
Thêm SDK trình điều khiển vào ứng dụng
SDK Trình điều khiển có trong kho lưu trữ Google Maven. Kho lưu trữ bao gồm các tệp Mô hình đối tượng dự án (.pom) của SDK và tài liệu Java. Cách thêm Driver SDK vào ứng dụng:
Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven, thay thế phần giữ chỗ
VERSION_NUMBER
cho phiên bản SDK trình điều khiển đã chọn.Gradle
Thêm nội dung sau vào
build.gradle
của bạn:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:[VERSION_NUMBER]' }
Maven
Thêm nội dung sau vào
pom.xml
của bạn:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation.driver</groupId> <artifactId>transportation-driver</artifactId> <version>[VERSION_NUMBER]</version> </dependency> </dependencies>
SDK điều khiển phụ thuộc vào SDK điều hướng, phần phụ thuộc này được định cấu hình theo cách cần có phiên bản cụ thể của SDK điều hướng, cần được xác định rõ ràng trong tệp cấu hình bản dựng như sau. Việc bỏ qua khối mã đã đề cập sẽ cho phép dự án luôn tải phiên bản mới nhất của SDK điều hướng trong phiên bản phát hành chính. Xin lưu ý rằng các hoạt động kết hợp của các phiên bản mới nhất của SDK trình điều khiển và SDK điều hướng đã trải qua quy trình kiểm thử nghiêm ngặt trước khi phát hành.
Sắp xếp cấu hình phần phụ thuộc của môi trường phát triển và phát hành cho phù hợp.
Gradle
Thêm nội dung sau vào
build.gradle
của bạn:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
Thêm nội dung sau vào
pom.xml
của bạn:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>5.0.0</version> </dependency> </dependencies>
Thêm khoá API vào ứng dụng
Sau khi thêm SDK trình điều khiển vào ứng dụng, hãy thêm khoá API vào ứng dụng. Bạn phải sử dụng khoá API dự án đã nhận được khi thiết lập dự án phát triển.
Phần này mô tả cách lưu trữ khoá API để ứng dụng của bạn có thể tham chiếu khoá đó một cách an toàn hơn. Bạn không nên kiểm tra khoá API vào hệ thống quản lý phiên bản. Tệp này phải được lưu trữ trong tệp local.properties
, nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp local.properties
, hãy xem các tệp thuộc tính Gradle.
Để đơn giản hoá tác vụ này, hãy dùng Trình bổ trợ Bí mật cho Gradle cho Android. Hãy làm theo quy trình này để cài đặt trình bổ trợ Secrets cho Gradle và lưu trữ an toàn khoá API của bạn.
Mở tệp
build.gradle
ở cấp độ gốc rồi thêm mã sau vào phần tửdependencies
trongbuildscript
.Groovy
buildscript { dependencies { // ... classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0" } }
Kotlin
buildscript { dependencies { // ... classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0") } }
Mở tệp
build.gradle
ở cấp ứng dụng rồi thêm mã sau vào phần tửplugins
.Groovy
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
Mở
local.properties
trong thư mục cấp dự án, sau đó thêm mã sau. Hãy nhớ thay thếYOUR_API_KEY
bằng khoá API.MAPS_API_KEY=YOUR_API_KEY
Trong tệp
AndroidManifest.xml
, hãy chuyển đếncom.google.android.geo.API_KEY
rồi cập nhật thuộc tínhandroid:value
như sau:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Ví dụ sau đây minh hoạ một tệp kê khai đầy đủ cho một ứng dụng mẫu:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.driverapidemo" >
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/_AppTheme" >
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="${MAPS_API_KEY}" />
<activity android:name=".MainActivity" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
Bao gồm các thuộc tính bắt buộc trong ứng dụng của bạn
Nếu sử dụng SDK trình điều khiển trong ứng dụng, bạn phải đưa văn bản phân bổ và giấy phép nguồn mở vào mục thông báo pháp lý của ứng dụng. Bạn nên đưa các thuộc tính vào dưới dạng mục trình đơn độc lập hoặc dưới dạng mục trong trình đơn About (Giới thiệu).
Bạn có thể tìm thấy thông tin về giấy phép tại tệp "third_party_ permissions.txt" trong tệp AAR đã huỷ lưu trữ.
Hãy tham khảo https://developers.google.com/android/guides/opensource để biết cách đưa thông báo nguồn mở vào.
Phần phụ thuộc
SDK trình điều khiển sử dụng gRPC để giao tiếp với máy chủ Fleet Engine. Nếu chưa triển khai gRPC, bạn có thể cần khai báo các phần phụ thuộc sau:
dependencies {
implementation 'io.grpc:grpc-android:1.12.0'
implementation 'io.grpc:grpc-okhttp:1.12.0'
}
Nếu không có các phần phụ thuộc này, SDK trình điều khiển có thể gặp lỗi trong thời gian chạy trong khi cố gắng giao tiếp với máy chủ Fleet Engine.
Nếu sử dụng ProGuard để tối ưu hoá bản dựng, bạn có thể cần thêm các dòng sau vào tệp cấu hình ProGuard:
-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**
Cấp độ API tối thiểu được hỗ trợ là 23.
Khởi chạy SDK
Bạn cần có mã nhà cung cấp (thường là mã dự án trên Google Cloud) để khởi động đối tượng DriverContext
. Để biết thêm thông tin chi tiết về cách thiết lập Dự án Google Cloud, hãy xem bài viết Xác thực và uỷ quyền.
Trước khi sử dụng SDK trình điều khiển, trước tiên, bạn phải khởi chạy SDK điều hướng. Cách khởi chạy SDK:
Lấy đối tượng
Navigator
từNavigationApi
.NavigationApi.getNavigator( this, // Activity new NavigationApi.NavigatorListener() { @Override public void onNavigatorReady(Navigator navigator) { // Keep a reference to the Navigator (used to configure and start nav) this.navigator = navigator; } } );
Tạo đối tượng
DriverContext
, điền sẵn các trường bắt buộc.DriverContext driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider( NavigationApi.getRoadSnappedLocationProvider(application)) .build();
Sử dụng đối tượng
DriverContext
để khởi chạy*DriverApi
.DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
Lấy
DeliveryVehicleReporter
từ đối tượng API. (DeliveryVehicleReporter
mở rộngNavigationVehicleReporter
.)DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
Đang xác thực với AuthTokenFactory
Khi SDK trình điều khiển tạo thông tin cập nhật vị trí, SDK phải gửi những thông tin cập nhật này đến máy chủ Fleet Engine. Để xác thực các yêu cầu này, SDK trình điều khiển sẽ gọi đến một thực thể AuthTokenFactory
do phương thức gọi cung cấp.
Nhà máy (factory) chịu trách nhiệm tạo mã thông báo xác thực tại thời điểm cập nhật vị trí.
Cách tạo mã thông báo chính xác còn tuỳ thuộc vào tình huống của từng nhà phát triển. Tuy nhiên, việc triển khai có thể cần phải:
- tìm nạp mã thông báo xác thực, có thể ở định dạng JSON, từ máy chủ HTTPS
- phân tích cú pháp và lưu mã thông báo vào bộ nhớ đệm
- làm mới mã thông báo khi hết hạn
Để biết thông tin chi tiết về mã thông báo mà máy chủ Fleet Engine dự kiến, hãy xem phần Tạo mã thông báo web JSON (JWT) để uỷ quyền.
Dưới đây là cấu hình triển khai khung của AuthTokenFactory
:
class JsonAuthTokenFactory implements AuthTokenFactory {
private String vehicleServiceToken; // initially null
private long expiryTimeMs = 0;
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
@Override
public String getToken(AuthTokenContext authTokenContext) {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(vehicleId);
}
if (ServiceType.VEHICLE.equals(authTokenContext.getServiceType)) {
return vehicleServiceToken;
} else {
throw new RuntimeException("Unsupported ServiceType: " + authTokenContext.getServiceType());
}
}
private void fetchNewToken(String vehicleId) {
String url = "https://yourauthserver.example/token/" + vehicleId;
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
vehicleServiceToken = obj.get("VehicleServiceToken").getAsString();
expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();
// The expiry time could be an hour from now, but just to try and avoid
// passing expired tokens, we subtract 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000;
} catch (IOException e) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw new RuntimeException("Could not get auth token", e);
}
}
}
Cách triển khai cụ thể này sử dụng ứng dụng HTTP Java tích hợp sẵn để tìm nạp một mã thông báo ở định dạng JSON từ máy chủ xác thực của nhà phát triển. Mã thông báo được lưu để sử dụng lại. Mã thông báo được tìm nạp lại nếu trong vòng 10 phút kể từ thời gian hết hạn của mã thông báo cũ.
Phương thức triển khai của bạn có thể hoạt động theo cách khác, chẳng hạn như sử dụng luồng trong nền để làm mới mã thông báo.
Các ngoại lệ trong AuthTokenFactory
được coi là tạm thời trừ phi chúng lặp lại. Sau một số lần thử, SDK trình điều khiển sẽ giả định rằng lỗi này là vĩnh viễn và ngừng cố gắng gửi các bản cập nhật.
Báo cáo trạng thái và lỗi với StatusListener
Vì SDK trình điều khiển thực hiện các thao tác ở chế độ nền, nên hãy sử dụng StatusListener
để kích hoạt thông báo khi xảy ra một số sự kiện nhất định, chẳng hạn như lỗi, cảnh báo hoặc thông báo gỡ lỗi. Lỗi có thể chỉ tạm thời (chẳng hạn như BACKEND_CONNECTIVITY_ERROR
) hoặc có thể khiến yêu cầu cập nhật vị trí bị dừng vĩnh viễn (chẳng hạn như VEHICLE_NOT_FOUND
, cho biết có lỗi cấu hình).
Bạn có thể triển khai StatusListener
không bắt buộc như sau:
class MyStatusListener implements StatusListener {
/** Called when background status is updated, during actions such as location reporting. */
@Override
public void updateStatus(
StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Lưu ý về SSL/TLS
Trong nội bộ, việc triển khai SDK trình điều khiển sử dụng
SSL/TLS để giao tiếp an toàn với máy chủ Fleet Engine. Các phiên bản Android cũ hơn (API phiên bản 23 trở xuống) có thể cần bản vá SecurityProvider
để giao tiếp với máy chủ. Để biết thêm thông tin về cách làm việc với SSL trong Android, hãy xem bài viết Nhà cung cấp dịch vụ GMS bảo mật.
Bài viết này cũng bao gồm các mã mẫu để vá trình cung cấp dịch vụ bảo mật.
Bật thông tin cập nhật về vị trí
Sau khi có một thực thể *VehicleReporter
, việc bật tính năng cập nhật vị trí sẽ rất đơn giản:
DeliveryVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Thông tin cập nhật vị trí được gửi định kỳ, nếu có thể. Mỗi thông tin cập nhật vị trí cũng cho biết rằng xe đang kết nối mạng.
Theo mặc định, khoảng thời gian báo cáo là 10 giây. Bạn có thể thay đổi khoảng thời gian báo cáo bằng reporter.setLocationReportingInterval(long, TimeUnit)
. Khoảng thời gian tối thiểu được hỗ trợ cho việc cập nhật là 5 giây. Việc cập nhật thường xuyên hơn có thể khiến các yêu cầu và lỗi bị chậm hơn.
Tắt thông tin cập nhật vị trí
Khi ca làm việc của người lái xe kết thúc, bạn có thể dừng yêu cầu cập nhật vị trí bằng cách gọi DeliveryVehicleReporter.disableLocationTracking
.
Các trường hợp sử dụng mô hình đáng tin cậy
Phần này mô tả cách sử dụng SDK trình điều khiển để triển khai các trường hợp sử dụng phổ biến khi sử dụng mô hình đáng tin cậy.
Tạo xe
Bạn có thể tạo xe bằng SDK trình điều khiển.
Trước khi tạo xe, hãy nhớ khởi động Delivery Driver API. Bạn phải tạo mã xe bằng mã xe và mã nhà cung cấp được dùng trong quá trình khởi chạy SDK trình điều khiển. Sau đó, hãy tạo xe như trong ví dụ sau:
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
// Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
// Handle CreateVehicleRequest error.
}
Tạo nhiệm vụ đến lấy hàng
Bạn có thể tạo nhiệm vụ đến lấy hàng thông qua SDK trình điều khiển.
Trước khi tạo một tác vụ, hãy nhớ khởi động API Trình điều khiển phân phối. Bạn phải tạo tác vụ bằng mã nhà cung cấp đã chỉ định trong quá trình khởi chạy SDK trình điều khiển. Sau đó, hãy tạo nhiệm vụ lấy hàng như trong ví dụ sau. Để biết thông tin về mã việc cần làm, hãy xem Ví dụ về mã việc cần làm.
static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
.setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
.setTaskDurationSeconds(2 * 60)
.setParentId("my-tracking-id")
.setTaskType(TaskType.DELIVERY_PICKUP)
.build();
try {
DeliveryTask task = taskManager.createTask(request).get();
// Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e) {
// Handle CreateTaskRequest error.
}
Tạo nhiệm vụ giao hàng
Bạn có thể tạo một nhiệm vụ giao hàng từ SDK trình điều khiển.
Trước khi tạo một tác vụ, hãy nhớ khởi động API Trình điều khiển phân phối. Sau đó, hãy tạo nhiệm vụ giao hàng như trong ví dụ sau. Để biết thông tin về mã công việc, hãy xem Ví dụ về mã công việc.
static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
.setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
.setTaskDurationSeconds(2 * 60)
.setParentId("my-tracking-id")
.setTaskType(TaskType.DELIVERY_DELIVERY)
.build();
try {
DeliveryTask task = taskManager.createTask(request).get();
// Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e) {
// Handle CreateTaskRequest error.
}
Không có sẵn theo lịch
Bạn có thể tạo một tác vụ cho biết không có sẵn (ví dụ: lỗi lái xe hoặc đổ xăng cho xe) từ SDK trình điều khiển. Một tác vụ không có sẵn theo lịch không được có mã theo dõi. Bạn có thể cung cấp vị trí (không bắt buộc).
Trước khi tạo một tác vụ, hãy nhớ khởi động API Trình điều khiển phân phối. Sau đó, hãy tạo tác vụ không có sẵn như trong ví dụ sau. Để biết thông tin về mã công việc, hãy xem Ví dụ về mã công việc.
static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
.setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
.setTaskType(TaskType.UNAVAILABLE)
.build();
try {
DeliveryTask task = taskManager.createTask(request).get();
// Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e) {
// Handle CreateTaskRequest error.
}
Trạm dừng theo lịch
Bạn có thể tạo tác vụ dừng theo lịch từ SDK trình điều khiển. Tác vụ dừng theo lịch có thể không bao gồm mã theo dõi.
Trước khi tạo một tác vụ, hãy nhớ khởi động API Trình điều khiển phân phối. Sau đó, hãy tạo tác vụ dừng theo lịch như trong ví dụ sau. Để biết thông tin về mã công việc, hãy xem Ví dụ về mã công việc.
static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
.setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
.setTaskDurationSeconds(2 * 60)
.setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
.build();
try {
DeliveryTask task = taskManager.createTask(request).get();
// Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e) {
// Handle CreateTaskRequest error.
}
Cập nhật thứ tự tác vụ
Bạn có thể cập nhật thứ tự thực thi các nhiệm vụ được chỉ định cho xe từ SDK trình điều khiển.
Việc cập nhật thứ tự tác vụ cũng sẽ giao các nhiệm vụ cho một chiếc xe nếu trước đó những nhiệm vụ đó chưa được giao cho một chiếc xe nào. Thao tác này cũng đóng các nhiệm vụ trước đây đã được chỉ định cho một xe và không nằm trong thứ tự cập nhật. Việc giao một nhiệm vụ cho một xe khác nếu trước đó nhiệm vụ đó đã được giao cho một xe khác sẽ gây ra lỗi. Trước khi giao một nhiệm vụ cho xe mới, hãy đóng nhiệm vụ hiện có rồi tạo một nhiệm vụ mới.
Bạn có thể cập nhật thứ tự công việc bất cứ lúc nào.
Trước khi cập nhật thứ tự nhiệm vụ cho một chiếc xe, hãy đảm bảo rằng xe đó và các nhiệm vụ đã được tạo trong Fleet Engine. Sau đó, hãy cập nhật thứ tự tác vụ cho xe như trong ví dụ sau.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
try {
List<VehicleStop> stops = reporter.setVehicleStops(
ImmutableList.of(
VehicleStop.builder()
.setVehicleStopState(VehicleStopState.ARRIVED)
.setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
.setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
.build(),
VehicleStop.builder()
.setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
.setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
.setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
.build(),
VehicleStop.builder()
.setVehicleStopState(VehicleStopState.NEW)
.setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
.setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
.build())).get();
// Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
} catch (Exception e) {
// Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
// errors.
}
Một ngoại lệ có thể xảy ra có thể ngăn việc cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi lại setVehicleStops
cho đến khi cuộc gọi thành công.
Các vấn đề tiềm ẩn có thể bao gồm:
XeStops đã chỉ định không tuân theo mẫu hợp lệ. Chỉ xeStop đầu tiên mới có thể nằm trong bất kỳ DeviceStopStates nào: NEW, ENROUTE hoặc rỗng. XeStops sau điểm dừng hiện tại phải ở giá xe (NEWEStopState) mới.
Việc cần làm không tồn tại hoặc thuộc một loại xe khác.
Chiếc xe này không tồn tại.
Xe đang trên đường đến trạm dừng tiếp theo
Bạn phải thông báo cho Fleet Engine khi xe khởi hành từ điểm dừng và khi xe bắt đầu quá trình chỉ đường. Bạn có thể thông báo cho Fleet Engine từ SDK trình điều khiển.
Trước khi thông báo cho Fleet Engine rằng một chiếc xe đã khởi hành từ một điểm dừng, hãy đảm bảo rằng xe đã được tạo và đặt xong. Sau đó, thông báo cho Fleet Engine về việc xe khởi hành như trong ví dụ sau.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.
// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
navigator.setDestination(vehicleStop.getWaypoint());
try {
List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
// Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
// VehicleStop updated to ENROUTE state.
} catch (Exception e) {
// Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
// after resolving errors.
}
Một trường hợp ngoại lệ có thể xảy ra có thể ngăn việc cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi lại enrouteToNextStop
cho đến khi thực hiện thành công.
Các vấn đề tiềm ẩn có thể bao gồm:
- Không còn
VehicleStops
nào được đặt trong SDK trình điều khiển.
Xe đang đến trạm dừng
Fleet Engine phải được thông báo khi xe đến điểm dừng. Bạn có thể thông báo cho Fleet Engine từ SDK trình điều khiển.
Trước khi thông báo cho Fleet Engine về việc có một chiếc xe đã dừng lại, hãy đảm bảo rằng bạn đã đặt điểm dừng xe. Sau đó, thông báo cho Fleet Engine về việc xe đến điểm dừng như minh hoạ trong ví dụ sau.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.
// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.
try {
List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
// Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
// VehicleStop updated to ARRIVED state.
navigator.clearDestinations();
} catch (Exception e) {
// Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
// after resolving errors.
}
Một trường hợp ngoại lệ có thể xảy ra có thể ngăn việc cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi lại arrivedAtStop
cho đến khi thực hiện thành công.
Các vấn đề tiềm ẩn có thể bao gồm:
- Không còn
VehicleStops
nào được đặt trong SDK trình điều khiển.
Xe hoàn thành điểm dừng
Bạn phải thông báo cho Fleet Engine khi xe dừng lại. Thông báo này khiến tất cả các tác vụ liên quan đến điểm dừng được đặt sang trạng thái ĐÃ ĐÓNG. Bạn có thể thông báo cho Fleet Engine từ SDK trình điều khiển.
Thông báo cho Fleet Engine về việc xe đã chạy xong xeStop như được hiển thị trong ví dụ sau.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.
// After completing the tasks at the VehicleStop, remove it from the
// the current list of VehicleStops.
try {
List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
// Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
// Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
} catch (Exception e) {
// Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
// after resolving errors.
}
Một trường hợp ngoại lệ có thể xảy ra có thể ngăn việc cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi lại completedStop
cho đến khi thực hiện thành công.
Các vấn đề tiềm ẩn có thể bao gồm:
- Không còn
VehicleStops
nào được đặt trong SDK trình điều khiển.
Đóng việc cần làm
Để đóng một nhiệm vụ đã được giao cho một xe, hãy thông báo cho Fleet Engine rằng xe đã hoàn thành điểm dừng nơi thực hiện nhiệm vụ đó hoặc xoá nó khỏi danh sách các điểm dừng xe. Để thực hiện việc này, bạn có thể đặt danh sách các điểm dừng của xe còn lại giống như khi cập nhật thứ tự tác vụ cho một chiếc xe.
Nếu một nhiệm vụ chưa được giao cho xe và cần được đóng, hãy cập nhật nhiệm vụ đó thành trạng thái ĐÃ ĐÓNG. Tuy nhiên, bạn không thể mở lại tác vụ ĐÃ ĐÓNG.
Đóng một tác vụ không có nghĩa là thành công hay thất bại. Mã này cho biết tác vụ không còn được xem là đang thực hiện. Để theo dõi quá trình vận chuyển, bạn phải cho biết kết quả thực tế của nhiệm vụ để có thể hiển thị kết quả giao hàng.
Bạn phải giao một tác vụ cho một xe thì mới có thể sử dụng SDK trình điều khiển để đóng tác vụ đó. Để đóng một nhiệm vụ đã được giao cho một xe, hãy thông báo cho Fleet Engine rằng xe đã hoàn thành điểm dừng nơi nhiệm vụ đó diễn ra.
Ngoài ra, hãy cập nhật thứ tự tác vụ của xe mà nhiệm vụ đó được giao, rồi xoá nhiệm vụ đó khỏi danh sách điểm dừng.
Thiết lập kết quả nhiệm vụ và vị trí kết quả
Đóng một tác vụ không biểu thị là thành công hay không thành công. Mã này cho biết tác vụ không còn được xem là đang thực hiện. Để theo dõi quá trình vận chuyển, bạn phải cho biết kết quả thực tế của nhiệm vụ thì mới có thể hiển thị kết quả giao hàng, để có thể có thông tin thanh toán phù hợp cho các dịch vụ. Sau khi đặt, bạn không thể thay đổi kết quả của tác vụ. Tuy nhiên, bạn có thể sửa đổi thời gian kết quả nhiệm vụ và vị trí kết quả nhiệm vụ sau khi đặt chúng.
Kết quả của những tác vụ đang ở trạng thái ĐÃ ĐÓNG có thể được đặt thành SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc FAILED (KHÔNG THÀNH CÔNG). Fleet Engine chỉ tính phí các tác vụ phân phối có trạng thái là SUCCEEDED.
Khi đánh dấu kết quả của một nhiệm vụ, Fleet Engine sẽ tự động điền thông tin vào vị trí kết quả nhiệm vụ bằng vị trí của xe đã biết gần đây nhất. Bạn có thể ghi đè hành vi này.
Ví dụ sau đây cho bạn biết cách sử dụng SDK trình điều khiển để thiết lập kết quả và dấu thời gian của tác vụ. Bạn không thể thiết lập vị trí kết quả nhiệm vụ bằng SDK trình điều khiển.
static final String TASK_ID = "task-8241890";
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
// Updating an existing DeliveryTask which is already CLOSED. Manually
// setting TaskOutcomeLocation with Driver SDK is not supported at this time.
UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
.build();
try {
DeliveryTask updatedTask = taskManager.updateTask(req);
// Handle UpdateTaskRequest DeliveryTask response.
} catch (Exception e) {
// Handle UpdateTaskRequest error.
}
Tra cứu xe
Bạn có thể tra cứu xe trong SDK trình điều khiển. Trước khi tìm xe, hãy đảm bảo bạn khởi động Delivery Driver API. Sau đó, bạn có thể tra cứu chiếc xe như trong ví dụ sau.
DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
// Handle GetVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
// Handle GetVehicleRequest error.
}
DeliveryVehicleManager
chỉ có thể tra cứu DeliveryVehicle
để biết mã xe đã được cung cấp trong quá trình khởi chạy API Trình điều khiển phân phối.