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

Lưu ý: Khả năng LMFS cung cấp hai mô hình bảo mật để sử dụng với SDK trình điều khiển: không đáng tin cậy và đáng tin cậy. Cả hai mô hình bảo mật đều xác định cách ứng dụng trình điều khiển có thể cung cấp dữ liệu cập nhật về phương tiện cho Fleet Engine. Mô hình bảo mật không đáng tin cậy cung cấp thêm một lớp kiểm tra dữ liệu từ ứng dụng trình điều khiển. Điều này có nghĩa là trong mô hình không đáng tin cậy, ứng dụng trình điều khiển chỉ có thể gửi các thông tin cập nhật về vị trí của xe trực tiếp đến Fleet Engine. Tất cả các bản cập nhật dữ liệu khác của xe từ một ứng dụng lái xe không đáng tin cậy phải được gửi đến phần phụ trợ của khách hàng. Sau khi được cập nhật, hệ thống sẽ chuyển tiếp ngày đến Fleet Engine.

Mô hình bảo mật đáng tin cậy cho phép ứng dụng của người lái gửi các bản cập nhật dữ liệu của xe trực tiếp đến Fleet Engine mà không cần dịch vụ trung gian. Trong đó có cả việc tạo và cập nhật thông tin về xe cộ, nhiệm vụ và điểm dừng.

Cuối cùng, chức năng của mô hình không đáng tin cậy thường có sẵn, trong khi chức năng của mô hình người lái đáng tin cậy vẫn có trong Bản xem trước. Xem bài viết Tích hợp API phân phối trong tài liệu về Fleet Engine để biết thông tin chi tiết.

Yêu cầu hệ thống tối thiểu

Thiết bị di động phải chạy Android 5.0 (API cấp 21) trở lên.

Điều kiện tiên quyết

Hướng dẫn này giả định ứng dụng của bạn đã triển khai SDK điều hướng và phần phụ trợ Fleet Engine đã được thiết lập và có sẵn.

SDK trình điều khiển dành cho Android được phát hành lên kho lưu trữ Maven của Artifact Registry. 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 ngoại tuyến.

Nhận quyền truy cập

Nếu bạn là khách hàng của Google Workspace, hãy tạo một Nhóm Workspace, chẳng hạn như [e-mail] trong quá trình giới thiệu và cung cấp tên cho Google. Đây là phương pháp tiếp cận được đề xuất. Sau đó, Nhóm Workspace của bạn sẽ được thêm vào danh sách cho phép cấp quyền truy cập vào kho lưu trữ Maven gmp-artifacts/transportation. Xác nhận rằng email người dùng và email tài khoản dịch vụ cần quyền truy cập sẽ có trong danh sách này.

Nếu tổ chức của bạn không thể tạo các Nhóm Workspace, hãy gửi cho Google danh sách email tài khoản người dùng và dịch vụ cần quyền truy cập vào các cấu phần phần mềm này.

Lưu ý: Nhóm Workspace không giống với Google Groups (kết thúc bằng @googlegroups.com). Chỉ các Nhóm Workspace mới được hỗ trợ.

Phát triển địa phương

Để phát triển cục bộ, bạn chỉ cần đăng nhập bằng SDK đám mây.

đám mây

gcloud auth login

Email dùng để đăng nhập phải là thành viên của Nhóm Workspace.

Tự động hoá (hệ thống xây dựng hoặc tích hợp liên tục)

Thiết lập máy chủ tự động hóa theo các phương pháp hay nhất:

• Nếu quy trình của bạn chạy trong môi trường Google Cloud, hãy sử dụng tính năng phát hiện thông tin xác thực tự động.

• Nếu không, hãy lưu trữ tệp khoá tài khoản dịch vụ ở một vị trí an toàn trên hệ thống tệp của máy chủ và đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS cho phù hợp.

Email tài khoản dịch vụ liên kết với thông tin xác thực phải là thành viên của Nhóm Workspace.

Cấu hình

Định cấu hình Maven hoặc Gradle để tự động phát hiện thông tin đăng nhập của người dùng hoặc dịch vụ.

Gradle

Thêm đoạn mã sau vào tệp build.gradle của mô-đun ứng dụng, không phải tệp build.gradle của mô-đun dự án gốc:

  plugins {
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
  }
  repositories {
    maven {
      url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
  }

Lưu ý: Nếu bạn sử dụng Android Studio, hãy nhấp vào thao tác Đồng bộ hóa dự án với tệp Gradle để kiểm tra cấu hình của bạn.

Maven

Thêm mã sau vào pom.xml của bạn:

  <repositories>
    <repository>
      <id>gmp-artifacts</id>
      <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
  </repositories>
  <build>
    <extensions>
      <extension>
        <groupId>com.google.cloud.artifactregistry</groupId>
        <artifactId>artifactregistry-maven-wagon</artifactId>
        <version>2.1.0</version>
      </extension>
    </extensions>
  </build>

Để biết thông tin về cách xác minh quyền truy cập, hãy xem phần Quản lý gói Java.

Cấu hình dự án

Để sử dụng SDK trình điều khiển, ứng dụng phải nhắm đến minSdkVersion 21 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 được xây dựng bằng SDK của trình điều khiển, thiết bị Android phải cài đặt các dịch vụ của Google Play.

Thiết lập dự án phát triển của bạn

Cách thiết lập dự án phát triển và nhận khoá API cho dự án đó trên Google Cloud Console:

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

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

3. Lấy khoá API cho dự án bằng cách chọn APIs & Services >Credential > 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 phần Nhận khoá API.

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

SDK của trình điều khiển được cung cấp thông qua kho lưu trữ Maven riêng tư. Kho lưu trữ bao gồm các tệp Dự án mô hình đối tượng (.pom) của SDK và tài liệu Java. Để thêm SDK trình điều khiển vào ứng dụng của bạn:

1. Thiết lập môi trường để truy cập vào kho lưu trữ Maven như được mô tả trong phần Cấu hình.

2. 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 mong muốn.

   Gradle

   Thêm mã sau vào build.gradle của bạn:

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

   Maven

   Thêm mã 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>
   

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 của dự án mà bạ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ó thể tham chiếu 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 của mình. Mã 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 phần Tệp thuộc tính Gradle.

Để đơn giản hoá việc này, hãy sử dụng Trình bổ trợ Gradle cho Android. Làm theo quy trình này để cài đặt trình bổ trợ Secrets Gradle và lưu trữ khoá API một cách an toàn.

1. Mở tệp build.gradle cấp gốc và thêm mã sau vào 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 và 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")
   

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

4. 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
   

5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY và 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 cho thấ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>

Lưu ý: Để có trải nghiệm điều hướng tốt nhất, người dùng phải cấp cả android.permission.ACCESS_COARSE_LOCATION và android.permission.ACCESS_FINE_LOCATION. Hãy đảm bảo yêu cầu cả hai trong thời gian chạy đó trong ứng dụng.

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

Bạn có thể tìm thấy văn bản ghi nhận tác giả bắt buộc và giấy phép nguồn mở trong tệp zip SDK trình điều khiển:

• NOTICE.txt
• LICENSES.txt

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 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 sẽ gặp lỗi trong thời gian chạy khi cố gắng giao tiếp với máy chủ Fleet Engine.

Nếu sử dụng ProGuard để tối ưu hoá các 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à 21.

Khởi chạy SDK

Bạn cần cung cấp mã nhận dạng 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 thông tin chi tiết về cách thiết lập Dự án trên Google Cloud, hãy xem phần 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. Để 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 vào 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 qua đối tượng API. (DeliveryVehicleReporter mở rộng NavigationVehicleReporter.)

   DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
   

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

Khi SDK điều khiển tạo thông tin cập nhật về vị trí, SDK phải gửi các thông tin cập nhật này cho máy chủ của 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 người gọi cung cấp. Nhà máy 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í.

Mã thông báo được tạo chính xác như thế nào sẽ tùy thuộc vào tình hình của từng nhà phát triển. Tuy nhiên, việc triển khai có thể sẽ 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 vào bộ nhớ đệm mã thông báo
• làm mới mã thông báo khi mã hết hạn

Để biết thông tin chi tiết về các mã thông báo do máy chủ Fleet Engine yêu cầu, hãy xem phần Tạo mã thông báo web JSON (JWT) để uỷ quyền.

Dưới đây là quy trình triển khai khung sườn 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 qua 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 này sẽ được tìm nạp lại nếu mã thông báo cũ nằm trong khoảng thời gian 10 phút kể từ thời điểm hết hạn.

Hoạt động triển khai có thể thực hiện những việc 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 sẽ được coi là tạm thời trừ khi chúng xảy ra nhiều lần. Sau một số lần thử, SDK trình điều khiển sẽ cho rằng lỗi là vĩnh viễn và sẽ dừ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, hãy sử dụng StatusListener để kích hoạt thông báo khi một số 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. Lỗi có thể tạm thời có tính chất tạm thời (chẳng hạn như BACKEND_CONNECTIVITY_ERROR) hoặc có thể khiến tính năng cập nhật vị trí bị dừng vĩnh viễn (chẳng hạn như VEHICLE_NOT_FOUND, gây ra 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ộ, quá trình 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ũ (API phiên bản 21 trở xuống) có thể yêu cầu bản vá SecurityProvider để có thể giao tiếp với máy chủ. Bạn nên xem bài viết này để biết thêm thông tin về cách làm việc với SSL trong Android. Bài viết này cũng chứa các mẫu mã để vá cho nhà cung cấp dịch vụ bảo mật.

Bật cập nhật vị trí

Sau khi có một thực thể *VehicleReporter, bạn có thể dễ dàng bật tính năng cập nhật vị trí:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Thông tin cập nhật vị trí sẽ được gửi định kỳ nếu có thể. Mỗi thông tin cập nhật vị trí cũng sẽ 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ợ là 5 giây. 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 cập nhật vị trí

Khi quá trình chuyển trình điều khiển hoàn tất, bạn có thể dừng 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

Sản phẩm hoặc tính năng này đang ở giai đoạn Xem trước (trước khi phát hành rộng rãi). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể chỉ được hỗ trợ hạn chế. Những thay đổi đối với các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với các phiên bản trước khi phát hành rộng rãi. Sản phẩm trước giai đoạn phát hành rộng rãi chịu sự điều chỉnh của Điều khoản dành riêng cho dịch vụ của Google Maps Platform. Để biết thêm thông tin, hãy xem phần mô tả giai đoạn ra mắt.

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 xe

Bạn có thể tạo xe từ SDK của Trình điều khiển.

Trước khi tạo xe, hãy nhớ khởi chạy Delivery Driver API. Bạn phải tạo mã nhận dạng xe với mã xe và mã nhận dạng nhà cung cấp được sử dụng trong quá trình khởi chạy SDK trình điều khiển. Sau đó, tạo phương tiện 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 trong lô 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 chạy Delivery Driver API. Tác vụ phải được tạo bằng cách sử dụng mã nhận dạng nhà cung cấp được 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ụ đến lấy hàng theo lô hàng trong ví dụ sau. Để 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ụ vận chuyển hàng

Bạn có thể tạo nhiệm vụ phân phối lô 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 chạy Delivery Driver API. Sau đó, tạo nhiệm vụ vận chuyển lô hàng như trong ví dụ sau. Để 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_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 nhiệm vụ cho biết không có sẵn (ví dụ: cho các điểm ngắt của người lái hoặc tiếp nhiên liệu của xe) từ SDK trình điều khiển. Tác vụ không có sẵn theo lịch biểu 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 tác vụ, hãy nhớ khởi chạy Delivery Driver API. Sau đó, hãy tạo nhiệm vụ không áp dụng như trong ví dụ sau. Để 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)
   .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.
}

Các điểm dừng đã lên lịch

Bạn có thể tạo một nhiệm vụ dừng theo lịch biểu từ SDK trình điều khiển. Một tác vụ dừng đã lên 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 chạy Delivery Driver API. Sau đó, hãy tạo nhiệm vụ dừng theo lịch trình như trong ví dụ sau. Để 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)
   .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ủa các nhiệm vụ được gán cho một phương tiện từ SDK trình điều khiển.

Việc cập nhật thứ tự tác vụ cũng sẽ chỉ định các tác vụ cho một phương tiện nếu trước đó chưa được chỉ định cho một phương tiện. Thao tác này cũng đóng các nhiệm vụ trước đây đã được chỉ định cho một phương tiện và không được xếp thứ tự cập nhật. Việc giao nhiệm vụ cho một phương tiện khác nếu trước đó đã được giao cho một phương tiện khác sẽ gây ra lỗi. Trước khi giao một nhiệm vụ cho phương tiện 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ự 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ụ của một 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ự thao tác 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 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:

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

• Việc cần làm không tồn tại hoặc việc đó thuộc về một phương tiện khác.

• Xe 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 một phương tiện khởi hành từ điểm dừng và khi bắt đầu đi theo chỉ dẫn. 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 xe đã khởi hành từ điểm dừng, hãy đảm bảo rằng xe đã được tạo và thiết lập xong. Sau đó, hãy thông báo cho Fleet Engine về chuyến 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.
}

Một ngoại lệ có thể xảy ra có thể ngăn 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ành công.

Các vấn đề tiềm ẩn có thể bao gồm:

• Chưa đặt VehicleStops còn lại nào trong SDK trình điều khiển.

Xe dừng tại một điểm dừng

Bạn sẽ phải thông báo cho Fleet Engine khi có xe đến. 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 phương tiện đã dừng lại, hãy đảm bảo bạn đã đặt phương tiện dừng. Sau đó, thông báo cho Fleet Engine về phương tiện đến tại điểm dừng 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.
// 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 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ành công.

Các vấn đề tiềm ẩn có thể bao gồm:

• Chưa đặt VehicleStops còn lại nào trong SDK trình điều khiển.

Xe hoàn thành bước dừng

Bạn sẽ phải thông báo cho Fleet Engine khi một phương tiện dừng xong. Điều này khiến tất cả các tác vụ liên kết với điểm dừng đều được đặt thành 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 rằng xe đã hoàn tất việc Xe dừng lại như 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 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ành công.

Các vấn đề tiềm ẩn có thể bao gồm:

• Chưa đặt VehicleStops còn lại nào trong SDK trình điều khiển.

Đóng một việc cần làm

Để đóng một nhiệm vụ đã được giao cho một phương tiện, hãy thông báo cho Fleet Engine rằng phương tiện đó đã hoàn tất điểm dừng nơi nhiệm vụ diễn ra hoặc xoá nó khỏi danh sách các điểm dừng của phương tiện. Để thực hiện việc này, bạn có thể đặt danh sách các phương tiện còn lại giống như khi cập nhật thứ tự trong nhiệm vụ của phương tiện.

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

Đóng một tác vụ không cho biết thành công hay không thành công. Nó cho biết tác vụ không còn được xem xét trong tiến trình. Để theo dõi quá trình vận chuyển, bạn cần cho biết 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.

Nhiệm vụ phải được giao cho một phương tiện để có thể sử dụng SDK trình điều khiển để đóng nhiệm vụ đó. Để đóng một nhiệm vụ đã được giao cho một phương tiện, hãy thông báo cho Fleet Engine rằng phương tiện đó đã hoàn tất việc dừng khi nhiệm vụ đó diễn ra.

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

Đặt kết quả việc cần làm và vị trí kết quả

Đóng một tác vụ không cho biết thành công hay không thành công. Nó cho biết tác vụ không còn được xem xét trong tiến trình. Đối với hoạt động theo dõi quá trình vận chuyển, bạn cần cho biết kết quả thực tế của một nhiệm vụ để hiển thị kết quả phân phối, từ đó có các khoản thanh toán thích hợp cho dịch vụ. Sau khi đặt, bạn không thể thay đổi kết quả của nhiệm vụ. Tuy nhiên, bạn có thể sửa đổi thời gian và kết quả của nhiệm vụ sau khi đặt.

Kết quả của nhiệm vụ ở trạng thái ĐÓNG có thể là SUCCEEDED hoặc FAILED. Fleet Engine chỉ tính phí các thao tác phân phối có trạng thái SUCCEEDED.

Khi đánh dấu kết quả của một việc cần làm, Fleet Engine sẽ tự động điền vị trí kết quả đã biết gần đây nhất của xe vào vị trí kết quả của việc cần làm. 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ả và dấu thời gian của tác vụ. Bạn không thể đặt vị trí kết quả của việc cần làm 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 phương tiện

Bạn có thể tra cứu xe từ SDK của Trình điều khiển. Trước khi tìm xe, hãy đả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 thông tin về 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 để tìm mã nhận dạng xe đã cung cấp trong quá trình khởi chạy API Trình điều khiển phân phối.