Bắt đầu với SDK Trình điều khiển dành cho Android

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ữ Google Maven.

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 Ghi chú phát hành.

Để chạy một ứng dụng tạo bằng SDK trình điều khiển, thiết bị Android phải có 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à tải khoá API cho dự án trên Google Cloud Console:

  1. Tạo một Google Cloud Console mới dự án hoặc chọn một dự án hiện có để sử dụng thông qua SDK trình điều khiển. Đợi vài phút cho đến khi dự án mới sẽ hiển thị trên Bảng điều khiển Google Cloud.

  2. Để 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 cho Android. Trong Google Cloud Console, hãy chọn API và Dịch vụ > thư viện, sau đó tìm kiếm và bật SDK Maps cho Android.

  3. Nhận khoá API cho dự án bằng cách chọn 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 tải khoá API, hãy xem Tải khoá API.

Thêm SDK Trình điều khiển vào ứng dụng của bạn

SDK Trình điều khiển có sẵn trong kho lưu trữ Google Maven. Chiến lược phát hành đĩa đơn kho lưu trữ bao gồm các tệp Mô hình đối tượng dự án (.pom) của SDK và Javadocs. Cách thêm SDK Trình điều khiển vào ứng dụng:

  1. Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven của bạn: thay thế phần giữ chỗ VERSION_NUMBER cho phiên bản đã chọn của SDK trình điều khiển.

    Gradle

    Thêm phần sau vào build.gradle:

    dependencies {
  ...
  implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:[VERSION_NUMBER]'
}

    Maven

    Thêm phần sau vào pom.xml:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.mapsplatform.transportation.driver</groupId>
    <artifactId>transportation-driver</artifactId>
    <version>[VERSION_NUMBER]</version>
  </dependency>
</dependencies>

  2. SDK trình đ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 trong một theo cách mà nếu cần một phiên bản cụ thể của SDK điều hướng, phiên bản đó phải rõ ràng được xác định trong tệp cấu hình bản dựng như sau, việc bỏ qua khối mã được đề cập sẽ cho phép dự án luôn tải xuống 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 hành vi 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 quá trình thử nghiệm 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 quá trình phát triển và phát hành môi trường tương ứng.

    Gradle

    Thêm phần sau vào build.gradle:

    dependencies {
  ...
  implementation 'com.google.android.libraries.navigation:navigation:5.0.0'
}

    Maven

    Thêm phần sau vào pom.xml:

    <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 của bạn

Sau khi bạn 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 của dự án mà bạn đã nhận được khi thiết lập dự án phát triển của bạn.

Phần này mô tả cách lưu trữ khoá API để bạn có thể sử dụng khoá một cách an toàn hơn mà ứng dụng của bạn tham chiếu đến. Bạn không nên kiểm tra khoá API trong phiên bản của mình hệ thống kiểm soát. Thông tin này phải được lưu trữ trong tệp local.properties, tức là nằm trong thư mục gốc của dự án. Để biết thêm thông tin về local.properties tệp, xem Các tệp thuộc tính Gradle.

Để đơn giản hoá tác vụ này, hãy sử dụng Trình bổ trợ Secrets Gradle cho Android. 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.

  1. Mở tệp build.gradle ở cấp cơ sở rồi thêm mã sau vào tệp Phần tử dependencies trong buildscript.

    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")
    }
}

  2. Mở tệp build.gradle ở cấp ứng dụng rồi thêm mã sau vào tệp Phần tử plugins.

    Groovy

    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")

  3. Đồng bộ hoá dự án với Gradle.

  4. Mở local.properties trong thư mục cấp dự án rồi thêm sau đây. Hãy nhớ thay thế YOUR_API_KEY bằng khoá API của bạn.

    MAPS_API_KEY=YOUR_API_KEY

  5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY rồi cập nhật thuộc tính android:value như sau:

    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

Ví dụ sau đây trình bày một tệp kê khai hoàn chỉnh 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>

Đưa các thuộc tính bắt buộc vào ứ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 thêm văn bản ghi công và giấy phép nguồn mở như một phần trong thông báo pháp lý của ứng dụng . Tốt nhất là nên bao gồm các thuộc tính dưới dạng một mục trình đơn độc lập hoặc dưới dạng một phần của mục trong trình đơn Giới thiệu.

Bạn có thể tìm thấy thông tin về giấy phép tại "third_party_permissions.txt" tệp trong tệp AAR đã huỷ lưu trữ.

Tham khảo https://developers.google.com/android/guides/opensource về 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 thành kết nối với máy chủ Fleet Engine. Nếu chưa sử dụng 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ể lỗi gặp phải trong thời gian chạy trong khi cố gắng giao tiếp với máy chủ Fleet Engine.

Nếu bạn 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 ProGuard tệp cấu hình:

-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 phải có mã nhà cung cấp (thường là mã dự án trên Google Cloud) để khởi tạo đối tượng DriverContext. Để biết thêm chi tiết về cách thiết lập Dự án trong Google Cloud, xem 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:

  1. 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;
      }
    }
);

  2. 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();

  3. Sử dụng đối tượng DriverContext để khởi tạo *DriverApi.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);

  4. Lấy DeliveryVehicleReporter từ đối tượng API. (DeliveryVehicleReporter mở rộng NavigationVehicleReporter.)

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();

Đang xác thực với AuthTokenFactory

Khi SDK Driver tạo thông tin cập nhật vị trí, nó phải gửi những nội dung cập nhật này cho máy chủ Fleet Engine. Để xác thực các yêu cầu này, SDK trình điều khiển gọi ra một phương thức gọi do người gọi cung cấp thực thể của AuthTokenFactory. Nhà máy chịu trách nhiệm tạo mã thông báo xác thực tại vị trí thời gian cập nhật.

Cách tạo mã thông báo chính xác sẽ khác nhau tuỳ theo trường hợp 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ộ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ề các mã thông báo mà máy chủ Fleet Engine dự kiến, hãy xem Tạo Mã thông báo web JSON (JWT) để uỷ quyền.

Dưới đây là cách triển khai khung của AuthTokenFactory:

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // initially null
  private long expiryTimeMs = 0;
  private String vehicleId;

  // 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) {
    String vehicleId = requireNonNull(context.getVehicleId());

    if (System.currentTimeMillis() > expiryTimeMs || !vehicleId.equals(this.vehicleId)) {
      // The token has expired, go get a new one.
      fetchNewToken(vehicleId);
    }

    return vehicleServiceToken;
  }

  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;
      this.vehicleId = vehicleId;
    } 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 là đã lưu để sử dụng lại. Mã thông báo được tìm nạp lại nếu mã thông báo cũ nằm trong vòng 10 phút về thời gian hết hạn.

Quá trình 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 ở chế độ 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 xảy ra lặp lại. Sau một số lần thử, SDK trình điều khiển Giả định rằng lỗi này là vĩnh viễn và ngừng tìm cách gửi 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 hành động trong ở chế độ nền, hãy sử dụng StatusListener để kích hoạt thông báo khi nhất định các sự kiện xảy ra, chẳng hạn như lỗi, cảnh báo hoặc thông báo gỡ lỗi. Có thể có lỗi có tính chất tạm thời (chẳng hạn như BACKEND_CONNECTIVITY_ERROR) hoặc chúng có thể khiến thông tin cập nhật vị trí bị dừng vĩnh viễn (chẳng hạn như VEHICLE_NOT_FOUND, chỉ báo 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 để kết nối an toàn với máy chủ Fleet Engine. Các phiên bản cũ của Android (API phiên bản 23 hoặc sớm hơn) 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 Nhà cung cấp GMS bảo mật. Bài viết này cũng chứa các mã mẫu để vá trình cung cấp dịch vụ bảo mật.

Bật tính năng cập nhật vị trí

Sau khi bạn có một phiên bản *VehicleReporter, thao tác bật tính năng cập nhật vị trí sẽ đơ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 vị trí thông tin cập nhật cũng cho biết rằng xe đang trực tuyến.

Theo mặc định, khoảng thời gian báo cáo là 10 giây. Bạn có thể thay đổi báo cáo bằng reporter.setLocationReportingInterval(long, TimeUnit). Chiến lược phát hành đĩa đơn khoảng thời gian cập nhật tối thiểu được hỗ trợ là 5 giây. Bản cập nhật thường xuyên hơn có thể dẫn đến yêu cầu và lỗi chậm hơn.

Tắt tính năng cập nhật vị trí

Khi ca lái xe kết thúc, bạn có thể ngừ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 tin cậy.

Tạo phương tiện di chuyển

Bạn có thể tạo xe thông qua SDK tài xế.

Trước khi tạo xe, hãy nhớ khởi chạy API Trình điều khiển phân phối. Bạn phải tạo mã xe bằng mã xe và mã nhà cung cấp đã sử dụng trong quá trình khởi chạy SDK trình điều khiển. Sau đó, hãy tạo chiếc xe như hình minh hoạ 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 để vận chuyển

Bạn có thể tạo nhiệm vụ đến lấy hàng vận chuyển qua SDK Driver.

Trước khi tạo một việc cần làm, hãy nhớ khởi chạy 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 SDK trình điều khiển khởi tạo. Sau đó, hãy tạo nhiệm vụ đến lấy hàng để vận chuyển như minh hoạ trong phần bên dưới ví dụ: Để biết thông tin về mã tác vụ, hãy xem Ví dụ về mã tác vụ.

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 nhiệm vụ giao hàng vận chuyển từ SDK Driver.

Trước khi tạo một việc cần làm, hãy nhớ khởi chạy 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ã 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_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Không thể sử dụng theo lịch

Bạn có thể tạo một nhiệm vụ cho biết không có dịch vụ (ví dụ: cho người lái xe) bị hỏng hoặc tiếp nhiên liệu xe) khỏi SDK tài xế. Không có sẵn theo lịch công việc không được bao gồm mã theo dõi. Bạn có thể cung cấp vị trí nếu muốn.

Trước khi tạo một việc cần làm, hãy nhớ khởi chạy API Trình điều khiển phân phối. Sau đó, hãy tạo tác vụ về việc không sử dụng được như trong ví dụ sau. Để biết thông tin về mã công việc, 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)
   .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.
}

Điểm dừng theo lịch trình

Bạn có thể tạo tác vụ dừng theo lịch từ SDK trình điều khiển. Đã lên lịch tác vụ dừng có thể không bao gồm mã theo dõi.

Trước khi tạo một việc cần làm, hãy nhớ khởi chạy 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ã 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)
       .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 hiện các nhiệm vụ đã giao cho xe trên SDK trình điều khiển.

Việc cập nhật thứ tự nhiệm vụ cũng sẽ chỉ định nhiệm vụ cho một chiếc xe nếu chúng không được giao đã chỉ định trước đó cho một chiếc xe. Thao tác này cũng đóng các tác vụ trước đó được chỉ định cho một chiếc xe và không được xếp hàng mới trong đơn đặt hàng mới. Chỉ định một nhiệm vụ cho một chiếc xe khác nếu trước đó nó đã được giao cho một chiếc xe khác xe tạo ra lỗi. Trước khi giao một nhiệm vụ cho xe mới, hãy đóng công việc hiện tại rồi tạo một công việc mới.

Bạn có thể cập nhật thứ tự việc cần làm 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 chiếc xe và nhiệm vụ đã được tạo trong Fleet Engine. Sau đó, hãy cập nhật thứ tự tác vụ cho chiếc 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.
    }

Có thể xảy ra một trường hợp ngoại lệ ngăn cản quá trình cập nhật đối với 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 sau đó 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:

  • VehicleStop được chỉ định không tuân theo mẫu hợp lệ. Chỉ người đầu tiên VehicleStop có thể ở bất kỳ trạng thái nào: NEW, ENROUTE hoặc ARRIVED. VehicleStops sau khi dừng hiện tại phải ở trong NEW xeStopState.

  • Việc cần làm không tồn tại hoặc thuộc về một chiếc 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

Fleet Engine phải được thông báo khi xe khởi hành từ điểm dừng và khi chiếc xe đó bắt đầu điều hướng. Bạn có thể thông báo cho Fleet Engine từ SDK Driver.

Trước khi thông báo cho Fleet Engine rằng một phương tiện đã khởi hành tại một điểm dừng, hãy đảm bảo rằng điểm dừng xe đã được tạo và thiết lập. Sau đó, hãy thông báo cho Fleet Engine về thời gian khởi hành của xe 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.
    }

Có thể xảy ra một ngoại lệ ngăn cản quá trình cập nhật SDK trình điều khiển trạng thái nội bộ. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi enrouteToNextStop cho đến khi 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 đã dừng tại điể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 Driver.

Trước khi thông báo cho Fleet Engine rằng một chiếc xe đã dừng lại, hãy đảm bảo rằng đã đặt trạm dừng xe. Sau đó, thông báo cho Fleet Engine về việc xe đến như được minh hoạ trong ví dụ sau đây.

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 ngoại lệ có thể xảy ra và có thể ngăn việc cập nhật bộ phận nội bộ của SDK Trình điều khiển state. Nếu trường hợp này xảy ra, hãy giải quyết vấn đề rồi gọi lại arrivedAtStop cho đến khi 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 tất một điểm dừng

Bạn phải thông báo cho Fleet Engine khi xe dừng xong. Thông báo này khiến tất cả các tác vụ liên kết với điểm dừng được đặt thành trạng thái ĐÃ ĐÓNG CỬA. Bạn có thể thông báo cho Fleet Engine từ SDK Driver.

Thông báo cho Fleet Engine rằng xe đã hoàn tất việc dừng xe như được minh hoạ 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 ngoại lệ có thể xảy ra và có thể ngăn việc cập nhật bộ phận nội bộ của SDK Trình điều khiển state. Nếu trường hợp này xảy ra, hãy giải quyết vấn đề rồi gọi lại completedStop cho đến khi 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 chiếc xe, hãy thông báo cho Fleet Engine rằng chiếc xe đã hoàn thành điểm dừng nơi thực hiện nhiệm vụ, hoặc xoá vị trí đó khỏi danh sách điểm dừng xe. Để làm như vậy, bạn có thể đặt danh sách xe còn lại dừng ngay khi cập nhật thứ tự nhiệm vụ cho một chiếc xe.

Nếu một nhiệm vụ chưa được giao cho xe và xe cần phải đóng, hãy cập nhật công việc sang trạng thái ĐÃ ĐÓNG CỬA. Tuy nhiên, bạn không thể mở lại việc cần làm ĐÃ ĐÓNG CỬA.

Việc đóng một tác vụ không có nghĩa là thành công hay thất bại. Nó cho biết tác vụ không còn được xem là đang tiến hành. Để theo dõi quá trình vận chuyển, bạn cần biểu thị kết quả thực tế của một nhiệm vụ để có thể hiển thị kết quả phân phối.

Bạn phải giao một nhiệm vụ cho một chiếc xe để có thể sử dụng SDK trình điều khiển để đóng tác vụ. Để đóng một việc cần làm đã được giao cho một chiếc xe, hãy thông báo Fleet Engine mà xe đã hoàn thành tại điểm dừng nơi thực hiện nhiệm vụ.

Ngoài ra, bạn có thể cập nhật thứ tự nhiệm vụ của xe công việc được giao, sau đó xoá công việc đó khỏi danh sách dừng.

Đặt kết quả của nhiệm vụ và vị trí kết quả

Việc đóng một tác vụ không có nghĩa là thành công hay thất bại. Nó cho biết tác vụ không còn được xem là đang tiến hành. Để theo dõi quá trình vận chuyển, bạn cần chỉ ra kết quả thực tế của một nhiệm vụ để có thể hiển thị kết quả phân phối, v.v. có phương thức 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ả tác vụ. Nhưng bạn có thể sửa đổi thời gian kết quả của nhiệm vụ và vị trí kết quả của nhiệm vụ sau khi bạn đã đặt chúng.

Có thể đặt kết quả cho những tác vụ ở trạng thái ĐÃ ĐÓNG CỬA thành: SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc KHÔNG THÀNH CÔNG. Fleet Engine chỉ tính phí các nhiệm vụ phân phối có trạng thái là SUCCEEDED (ĐÃ THÀNH CÔNG).

Khi đánh dấu kết quả của một nhiệm vụ, Fleet Engine sẽ tự động điền vị trí kết quả nhiệm vụ cùng với vị trí chiếc 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 để đặt kết quả tác vụ và dấu thời gian. Bạn không thể đặt vị trí kết quả tác vụ bằng cách sử dụ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 phương tiện

Bạn có thể tra cứu một chiếc xe trong SDK tài xế. Trước khi tra cứu xe, đảm bảo rằng bạn khởi chạy API Trình điều khiển phân phối. 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 cho mã xe được cung cấp trong quá trình khởi chạy Delivery Driver API.