Mulai menggunakan Driver SDK untuk Android

Persyaratan sistem minimum

Perangkat seluler harus menjalankan Android 6.0 (level API 23) atau yang lebih baru.

Konfigurasi build dan dependensi

Driver SDK versi 4.99 dan yang lebih baru tersedia di repositori Maven Google.

Gradle

Tambahkan baris berikut ke file build.gradle Anda:

repositories {
    ...
    google()
}

Maven

Tambahkan baris berikut ke file pom.xml Anda:

<project>
  ...
  <repositories>
    <repository>
      <id>google-maven-repository</id>
      <url>https://maven.google.com</url>
    </repository>
  </repositories>
  ...
</project>

Konfigurasi Project

Untuk menggunakan Driver SDK, aplikasi Anda harus menargetkan minSdkVersion 23 atau yang lebih tinggi. Untuk mengetahui informasi lebih lanjut, baca Catatan Rilis.

Untuk menjalankan aplikasi yang dibangun dengan Driver SDK, perangkat Android harus menginstal layanan Google Play.

Menyiapkan project pengembangan

Untuk menyiapkan project pengembangan dan mendapatkan kunci API project di Konsol Google Cloud:

  1. Buat project Konsol Google Cloud baru, atau pilih project yang sudah ada, untuk digunakan dengan Driver SDK. Tunggu beberapa menit sampai project baru terlihat di Konsol Google Cloud.

  2. Untuk menjalankan aplikasi demo, project Anda harus memiliki akses ke Maps SDK for Android. Di Konsol Google Cloud, pilih APIs & Services > Library, lalu telusuri dan aktifkan Maps SDK for Android.

  3. Dapatkan kunci API untuk project dengan memilih APIs & Services > Credentials > Create credentials > API key. Untuk informasi selengkapnya tentang mendapatkan kunci API, lihat Mendapatkan kunci API.

Menambahkan Driver SDK ke aplikasi

Driver SDK tersedia dari repositori Maven Google. Repositori ini berisi file Project Object Model (.pom) SDK dan Javadocs. Untuk menambahkan Driver SDK ke aplikasi Anda:

  1. Tambahkan dependensi berikut ke konfigurasi Gradle atau Maven Anda, dengan mengganti placeholder VERSION_NUMBER untuk versi Driver SDK yang dipilih.

    Gradle

    Tambahkan kode berikut ke build.gradle Anda:

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

    Maven

    Tambahkan kode berikut ke pom.xml Anda:

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.libraries.mapsplatform.transportation.driver</groupId>
        <artifactId>transportation-driver</artifactId>
        <version>[VERSION_NUMBER]</version>
      </dependency>
    </dependencies>
    
  2. Driver SDK bergantung pada Navigation SDK, dependensi ini dikonfigurasi sedemikian rupa sehingga jika versi Navigation SDK tertentu diperlukan, dependensi harus ditentukan secara eksplisit dalam file konfigurasi build seperti berikut. Jika blok kode yang disebutkan dihapus, project dapat selalu mendownload Navigation SDK versi terbaru dalam versi rilis utama. Perhatikan bahwa perilaku gabungan antara versi terbaru Driver SDK dan Navigation SDK telah menjalani pengujian ketat sebelum dirilis.

    Atur konfigurasi dependensi lingkungan pengembangan dan rilis Anda sebagaimana mestinya.

    Gradle

    Tambahkan kode berikut ke build.gradle Anda:

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

    Maven

    Tambahkan kode berikut ke pom.xml Anda:

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.libraries.navigation</groupId>
        <artifactId>navigation</artifactId>
        <version>5.0.0</version>
      </dependency>
    </dependencies>
    

Menambahkan kunci API ke aplikasi

Setelah menambahkan Driver SDK ke aplikasi Anda, tambahkan kunci API ke aplikasi Anda. Anda harus menggunakan kunci API project yang diperoleh saat menyiapkan project pengembangan.

Bagian ini menjelaskan cara menyimpan kunci API sehingga dapat dirujuk dengan lebih aman oleh aplikasi Anda. Anda tidak boleh memasukkan kunci API ke dalam sistem kontrol versi. Versi ini harus disimpan di file local.properties, yang terletak di direktori utama project Anda. Untuk informasi selengkapnya tentang file local.properties, lihat file properti Gradle.

Untuk menyederhanakan tugas ini, gunakan Plugin Secrets Gradle untuk Android. Ikuti prosedur ini untuk menginstal plugin Secrets Gradle dan menyimpan kunci API Anda dengan aman.

  1. Buka file build.gradle tingkat root dan tambahkan kode berikut ke elemen dependencies di bagian 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. Buka file build.gradle tingkat aplikasi, dan tambahkan kode berikut ke elemen plugins.

    Groovy

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

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. Sinkronkan project Anda dengan Gradle.

  4. Buka local.properties pada direktori tingkat project, lalu tambahkan kode berikut. Pastikan untuk mengganti YOUR_API_KEY dengan kunci API Anda.

    MAPS_API_KEY=YOUR_API_KEY
    
  5. Dalam file AndroidManifest.xml Anda, buka com.google.android.geo.API_KEY dan perbarui atribut android:value sebagai berikut:

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

Contoh berikut menunjukkan manifes lengkap untuk aplikasi contoh:

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

Menyertakan atribusi yang diperlukan dalam aplikasi

Jika menggunakan Driver SDK di aplikasi, Anda harus menyertakan teks atribusi dan lisensi open source sebagai bagian dari bagian pemberitahuan hukum aplikasi. Sebaiknya sertakan atribusi sebagai item menu independen atau sebagai bagian dari item menu Tentang.

Informasi lisensi dapat ditemukan di file "third_party_licenses.txt" dalam file AAR yang tidak diarsipkan.

Lihat https://developers.google.com/android/guides/opensource tentang cara menyertakan pemberitahuan open source.

Dependensi

Driver SDK menggunakan gRPC untuk berkomunikasi dengan server Fleet Engine. Jika belum menyertakan gRPC, Anda mungkin perlu mendeklarasikan dependensi berikut:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

Tanpa dependensi ini, Driver SDK mungkin mengalami error saat runtime saat mencoba berkomunikasi dengan server Fleet Engine.

Jika menggunakan ProGuard untuk mengoptimalkan build, Anda mungkin perlu menambahkan baris berikut ke file konfigurasi Proguard Anda:

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

API level minimum yang didukung adalah 23.

Menginisialisasi SDK

ID penyedia (biasanya Project ID Google Cloud) diperlukan untuk menginisialisasi objek DriverContext. Untuk mengetahui detail lebih lanjut tentang cara menyiapkan Project Google Cloud, lihat Autentikasi dan Otorisasi.

Sebelum menggunakan Driver SDK, Anda harus melakukan inisialisasi Navigation SDK terlebih dahulu. Untuk melakukan inisialisasi SDK:

  1. Dapatkan objek Navigator dari 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. Buat objek DriverContext, dengan mengisi kolom yang wajib diisi.

    DriverContext driverContext = DriverContext.builder(application)
        .setProviderId(providerId)
        .setVehicleId(vehicleId)
        .setAuthTokenFactory(authTokenFactory)
        .setNavigator(navigator)
        .setRoadSnappedLocationProvider(
            NavigationApi.getRoadSnappedLocationProvider(application))
        .build();
    
  3. Gunakan objek DriverContext untuk melakukan inisialisasi *DriverApi.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
    
  4. Dapatkan DeliveryVehicleReporter dari objek API. (DeliveryVehicleReporter memperluas NavigationVehicleReporter.)

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
    

Mengautentikasi dengan AuthTokenFactory

Saat Driver SDK menghasilkan pembaruan lokasi, SDK harus mengirimkan pembaruan ini ke server Fleet Engine. Untuk mengautentikasi permintaan ini, Driver SDK memanggil instance AuthTokenFactory yang disediakan oleh pemanggil. Factory bertanggung jawab untuk membuat token autentikasi pada waktu update lokasi.

Cara token dibuat secara pasti berbeda-beda untuk setiap situasi developer. Namun, penerapannya mungkin perlu:

  • mengambil token autentikasi, mungkin dalam format JSON, dari server HTTPS
  • mengurai dan meng-cache token
  • memperbarui token jika masa berlakunya telah habis

Untuk detail tentang token yang diharapkan oleh server Fleet Engine, lihat Membuat Token Web JSON (JWT) untuk otorisasi.

Berikut adalah implementasi kerangka 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);
    }
  }
}

Implementasi khusus ini menggunakan klien HTTP Java bawaan untuk mengambil token dalam format JSON dari server autentikasi developer. Token disimpan untuk digunakan kembali. Token diambil ulang jika token lama berada dalam waktu 10 menit sejak waktu habis masa berlakunya.

Penerapan Anda mungkin melakukan hal-hal yang berbeda, seperti menggunakan thread latar belakang untuk memuat ulang token.

Pengecualian dalam AuthTokenFactory diperlakukan sebagai sementara kecuali jika terjadi berulang kali. Setelah beberapa kali percobaan, Driver SDK akan menganggap bahwa error tersebut bersifat permanen dan berhenti mencoba mengirim update.

Pelaporan Status dan Error dengan StatusListener

Karena Driver SDK melakukan tindakan di latar belakang, gunakan StatusListener untuk memicu notifikasi saat peristiwa tertentu terjadi, seperti error, peringatan, atau pesan debug. Error mungkin bersifat sementara (seperti BACKEND_CONNECTIVITY_ERROR), atau dapat menyebabkan pembaruan lokasi dihentikan secara permanen (seperti VEHICLE_NOT_FOUND, yang menunjukkan error konfigurasi).

Anda menyediakan implementasi StatusListener opsional seperti berikut:

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

Catatan tentang SSL/TLS

Secara internal, implementasi Driver SDK menggunakan SSL/TLS untuk berkomunikasi secara aman dengan server Fleet Engine. Versi Android yang lebih lama (API versi 23 atau yang lebih lama) mungkin memerlukan patch SecurityProvider untuk berkomunikasi dengan server. Untuk mengetahui informasi selengkapnya tentang menggunakan SSL di Android, lihat Penyedia GMS Keamanan. Artikel ini juga berisi contoh kode untuk melakukan patch pada penyedia keamanan.

Aktifkan pembaruan lokasi

Setelah memiliki instance *VehicleReporter, Anda dapat mengaktifkan pembaruan lokasi dengan mudah:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Pembaruan lokasi dikirim dengan interval rutin, jika memungkinkan. Setiap pembaruan lokasi juga menunjukkan bahwa kendaraan sedang online.

Secara default, interval pelaporan adalah 10 detik. Anda dapat mengubah interval pelaporan dengan reporter.setLocationReportingInterval(long, TimeUnit). Interval update minimum yang didukung adalah 5 detik. Update yang lebih sering dapat mengakibatkan error dan permintaan yang lebih lambat.

Menonaktifkan pembaruan lokasi

Saat shift pengemudi selesai, Anda dapat menghentikan pembaruan lokasi dengan memanggil DeliveryVehicleReporter.disableLocationTracking.

Kasus penggunaan model tepercaya

Bagian ini menjelaskan cara menggunakan Driver SDK untuk menerapkan kasus penggunaan umum saat menggunakan model tepercaya.

Buat kendaraan

Anda dapat membuat kendaraan dari Driver SDK.

Sebelum membuat kendaraan, pastikan untuk melakukan inisialisasi Delivery Driver API. ID kendaraan harus dibuat dengan ID kendaraan dan penyedia yang digunakan selama inisialisasi Driver SDK. Kemudian, buat kendaraan seperti yang ditunjukkan dalam contoh berikut:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

Membuat tugas pengambilan pengiriman

Anda dapat membuat tugas pengambilan kiriman dari Driver SDK.

Sebelum membuat tugas, pastikan untuk melakukan inisialisasi Delivery Driver API. Tugas harus dibuat menggunakan ID penyedia yang ditentukan selama inisialisasi Driver SDK. Kemudian, buat tugas pengambilan pengiriman seperti yang ditunjukkan pada contoh berikut. Untuk informasi tentang ID tugas, lihat contoh ID Tugas.

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

Membuat tugas pengiriman pengiriman

Anda dapat membuat tugas pengiriman pengiriman dari Driver SDK.

Sebelum membuat tugas, pastikan untuk melakukan inisialisasi Delivery Driver API. Lalu, buat tugas pengiriman seperti yang ditunjukkan pada contoh berikut. Untuk mengetahui informasi tentang ID tugas, lihat contoh ID Tugas.

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

Ketidaktersediaan terjadwal

Anda dapat membuat tugas yang menunjukkan ketidaktersediaan (misalnya, untuk jeda saat pengemudi atau mengisi bahan bakar kendaraan) dari Driver SDK. Tugas ketidaktersediaan terjadwal tidak boleh menyertakan ID pelacakan. Anda dapat memberikan lokasi secara opsional.

Sebelum membuat tugas, pastikan untuk melakukan inisialisasi Delivery Driver API. Kemudian buat tugas ketidaktersediaan seperti yang ditunjukkan pada contoh berikut. Untuk mengetahui informasi tentang ID tugas, lihat contoh ID Tugas.

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

Perhentian terjadwal

Anda dapat membuat tugas perhentian terjadwal dari Driver SDK. Tugas berhenti terjadwal mungkin tidak menyertakan ID pelacakan.

Sebelum membuat tugas, pastikan untuk melakukan inisialisasi Delivery Driver API. Kemudian buat tugas perhentian terjadwal seperti yang ditunjukkan pada contoh berikut. Untuk mengetahui informasi tentang ID tugas, lihat contoh ID Tugas.

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

Perbarui pengurutan tugas

Anda dapat memperbarui urutan pelaksanaan tugas yang ditetapkan ke kendaraan dari Driver SDK.

Memperbarui pengurutan tugas juga akan menetapkan tugas ke kendaraan jika sebelumnya tidak ditetapkan ke kendaraan. Fungsi ini juga menutup tugas yang sebelumnya ditetapkan ke kendaraan dan tidak dicantumkan dalam pemesanan yang diperbarui. Menetapkan tugas ke kendaraan lain jika sebelumnya telah ditetapkan ke kendaraan lain akan menyebabkan error. Sebelum menetapkan tugas ke kendaraan baru, tutup tugas yang ada, lalu buat tugas baru.

Anda dapat memperbarui pengurutan tugas kapan saja.

Sebelum memperbarui pengurutan tugas untuk kendaraan, pastikan kendaraan dan tugas telah dibuat di Fleet Engine. Kemudian perbarui urutan tugas untuk kendaraan seperti yang ditunjukkan pada contoh berikut.

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

Mungkin terjadi pengecualian yang dapat mencegah update pada status internal Driver SDK. Jika hal ini terjadi, selesaikan masalah, lalu panggil setVehicleStops lagi hingga panggilan berhasil.

Potensi masalah dapat mencakup:

  • VehicleStop yang ditentukan tidak mengikuti pola yang valid. Hanya VehicleStop pertama yang dapat berada di VehicleStopStates: BARU, ENROUTE, atau ARRIVED. VehicleStopState setelah perhentian saat ini harus berada di VehicleStopState BARU.

  • Tugas tidak ada, atau tugas tersebut milik kendaraan lain.

  • Kendaraan tidak ada.

Kendaraan sedang dalam perjalanan ke perhentian berikutnya

Fleet Engine harus diberi tahu saat kendaraan berangkat dari perhentian, dan saat memulai navigasi. Anda dapat memberi tahu Fleet Engine dari Driver SDK.

Sebelum memberi tahu Fleet Engine bahwa kendaraan berangkat dari perhentian, pastikan perhentian kendaraan telah dibuat dan ditetapkan. Kemudian, beri tahu Fleet Engine tentang keberangkatan kendaraan seperti ditunjukkan pada contoh berikut.

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

Mungkin terjadi pengecualian yang dapat mencegah update pada status internal Driver SDK. Jika hal ini terjadi, selesaikan masalah, lalu panggil enrouteToNextStop lagi hingga berhasil.

Potensi masalah dapat mencakup:

  • Tidak ada VehicleStops tersisa yang ditetapkan di Driver SDK.

Kendaraan tiba di perhentian

Fleet Engine harus diberi tahu saat kendaraan tiba di perhentian. Anda dapat memberi tahu Fleet Engine dari Driver SDK.

Sebelum memberi tahu Fleet Engine bahwa kendaraan tiba di perhentian, pastikan perhentian kendaraan telah ditetapkan. Kemudian, beri tahu Fleet Engine tentang kedatangan kendaraan di perhentian seperti yang ditunjukkan dalam contoh berikut.

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

Pengecualian dapat terjadi yang dapat mencegah update pada status internal Driver SDK. Jika hal ini terjadi, selesaikan masalah, lalu panggil arrivedAtStop lagi sampai berhasil.

Potensi masalah mungkin termasuk:

  • Tidak ada VehicleStops tersisa yang ditetapkan di Driver SDK.

Kendaraan menyelesaikan perhentian

Anda harus memberi tahu Fleet Engine saat kendaraan berhenti. Notifikasi ini menyebabkan semua tugas yang terkait dengan perhentian ditetapkan ke status TUTUP. Anda dapat memberi tahu Fleet Engine dari Driver SDK.

Beri tahu Fleet Engine bahwa kendaraan telah menyelesaikan VehicleStop-nya, seperti yang ditunjukkan pada contoh berikut.

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

Pengecualian dapat terjadi yang dapat mencegah update pada status internal Driver SDK. Jika hal ini terjadi, selesaikan masalah, lalu panggil completedStop lagi sampai berhasil.

Potensi masalah dapat mencakup:

  • Tidak ada VehicleStops tersisa yang ditetapkan di Driver SDK.

Menutup tugas

Untuk menutup tugas yang telah ditetapkan ke kendaraan, beri tahu Fleet Engine bahwa kendaraan telah menyelesaikan perhentian tempat tugas dilakukan, atau hapus dari daftar perhentian kendaraan. Untuk melakukannya, Anda dapat menetapkan daftar perhentian kendaraan yang tersisa, sama seperti saat memperbarui pengurutan tugas untuk kendaraan.

Jika tugas belum ditetapkan ke kendaraan, dan tugas harus ditutup, perbarui tugas ke status TUTUP. Namun, Anda tidak dapat membuka kembali tugas yang TERTUTUP.

Menutup tugas tidak mengindikasikan keberhasilan atau kegagalan. Ini menunjukkan bahwa tugas tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga hasil pengiriman dapat ditampilkan.

Tugas harus ditetapkan ke kendaraan agar dapat menggunakan Driver SDK untuk menutup tugas. Untuk menutup tugas yang telah ditetapkan ke kendaraan, beri tahu Fleet Engine bahwa kendaraan telah menyelesaikan perhentian tempat tugas dilakukan.

Atau, perbarui urutan tugas kendaraan tempat tugas ditetapkan, lalu hapus tugas dari daftar perhentian.

Menetapkan hasil tugas dan lokasi hasil

Menutup tugas tidak mengindikasikan keberhasilan atau kegagalan. Ini menunjukkan bahwa tugas tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas agar hasil pengiriman dapat ditampilkan, sehingga ada penagihan yang tepat untuk layanan tersebut. Setelah ditetapkan, Anda tidak dapat mengubah hasil tugas. Tetapi Anda dapat mengubah waktu hasil tugas dan lokasi hasil tugas setelah menetapkannya.

Tugas yang memiliki status DITUTUP dapat menetapkan hasilnya ke Berhasil atau GAGAL. Fleet Engine hanya menagih tugas pengiriman dengan status Berhasil.

Saat menandai hasil tugas, Fleet Engine akan otomatis mengisi lokasi hasil tugas dengan lokasi kendaraan terakhir yang diketahui. Anda dapat mengganti perilaku ini.

Contoh berikut menunjukkan cara menggunakan Driver SDK untuk menetapkan hasil tugas dan stempel waktu. Anda tidak dapat menetapkan lokasi hasil tugas menggunakan Driver SDK.

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

Cari kendaraan

Anda dapat mencari kendaraan dari Driver SDK. Sebelum mencari kendaraan, pastikan Anda menginisialisasi Delivery Driver API. Anda kemudian dapat mencari kendaraan seperti yang ditunjukkan pada contoh berikut.

    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 hanya dapat mencari DeliveryVehicle untuk ID kendaraan yang diberikan selama inisialisasi Delivery Driver API.