Anda dapat menggunakan Driver SDK untuk memberikan navigasi dan pelacakan yang lebih baik ke aplikasi Progres Perjalanan dan Pesanan Anda. Driver SDK menyediakan pembaruan tugas dan lokasi kendaraan ke Mesin Fleet Solusi Perjalanan dan Pengiriman On-demand.
Driver SDK membuat layanan Fleet Engine dan layanan kustom Anda mengetahui
lokasi dan status kendaraan. Misalnya, kendaraan dapat ONLINE
atau OFFLINE
, dan lokasi kendaraan berubah seiring berlangsungnya perjalanan.
Persyaratan sistem minimum
Perangkat seluler harus menjalankan Android 6.0 (API level 23) atau yang lebih baru.
Konfigurasi build dan dependensi
Driver SDK versi 4.99 dan yang lebih baru tersedia dari 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 lebih tinggi.
Untuk menjalankan aplikasi yang dibangun dengan Driver SDK, Android perangkat harus memiliki Layanan Google Play terinstal.
Menyiapkan project pengembangan
Untuk menyiapkan project pengembangan dan mendapatkan kunci API untuk project di Konsol Google Cloud:
Buat project Konsol Google Cloud baru, atau pilih project yang sudah ada, untuk digunakan dengan Driver SDK. Tunggu beberapa menit sampai project baru dapat dilihat di Konsol Google Cloud.
Untuk menjalankan aplikasi demo, project Anda harus memiliki akses ke Maps SDK untuk Android. Di Konsol Google Cloud, pilih API & Layanan > Library, lalu telusuri dan aktifkan Maps SDK untuk Android.
Dapatkan kunci API untuk project dengan memilih API & Layanan > Kredensial > Buat kredensial > Kunci API Anda. Untuk informasi selengkapnya tentang mendapatkan kunci API, lihat Mendapatkan kunci API.
Menambahkan Driver SDK ke aplikasi
Driver SDK tersedia dari repositori Maven Google. Tujuan yang berisi file Project Object Model (.pom) SDK dan Javadocs. Untuk menambahkan Driver SDK ke aplikasi Anda:
Tambahkan dependensi berikut ke konfigurasi Gradle atau Maven Anda, dengan mengganti Placeholder
VERSION_NUMBER
untuk versi Driver SDK yang diinginkan.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</groupId> <artifactId>transportation-driver</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Driver SDK bergantung pada Navigation SDK, dan dependensi ini dikonfigurasi sedemikian rupa sehingga jika diperlukan versi Navigation SDK tertentu, SDK harus secara eksplisit di file konfigurasi build seperti berikut, menghilangkan blok kode yang disebutkan akan memungkinkan project untuk selalu mendownload versi terbaru Navigation SDK dalam versi rilis utama. Perhatikan bahwa perilaku gabungan dari versi terbaru SDK Driver dan Navigation SDK telah menjalani pengujian ketat sebelum dirilis.
Mengatur konfigurasi dependensi pengembangan dan rilis Anda lingkungan yang sesuai.
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 Anda peroleh saat menyiapkan project pengembangan.
Bagian ini menjelaskan cara menyimpan kunci API sehingga dapat lebih aman
yang direferensikan oleh aplikasi Anda. Anda tidak boleh memasukkan kunci API ke versi Anda
sistem kontrol. Data tersebut harus disimpan di file local.properties
, yang
yang terletak di direktori {i>
root<i} proyek Anda. Untuk informasi selengkapnya tentang
File local.properties
, lihat
File properti Gradle.
Untuk menyederhanakan tugas ini, Anda dapat menggunakan Plugin Secrets Gradle untuk Android.
Untuk menginstal plugin dan menyimpan kunci API Anda:
Buka file
build.gradle
tingkat root dan tambahkan kode berikut ke Elemendependencies
di bawahbuildscript
.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") } }
Buka file
build.gradle
tingkat aplikasi dan tambahkan kode berikut ke elemenplugins
.Groovy
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
Jika Anda menggunakan Android Studio, menyinkronkan project Anda dengan Gradle.
Buka
local.properties
pada direktori tingkat project, lalu tambahkan pada kode berikut. GantiYOUR_API_KEY
dengan kunci API Anda.MAPS_API_KEY=YOUR_API_KEY
Di file
AndroidManifest.xml
Anda, bukacom.google.android.geo.API_KEY
dan update atributandroid: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 pemberitahuan hukum aplikasi Anda bagian. Sebaiknya sertakan atribusi sebagai item menu independen atau sebagai bagian dari item menu Tentang.
Informasi lisensi dapat ditemukan di "third_party_licenses.txt" file di file AAR yang tidak diarsipkan.
Lihat https://developers.google.com/android/guides/opensource tentang cara menyertakan pemberitahuan {i>open source<i}.
Dependensi
Jika Anda menggunakan ProGuard untuk mengoptimalkan build, Anda mungkin perlu menambahkan baris berikut ke ProGuard file konfigurasi:
-dontwarn com.google.**
-dontwarn okio.**
API level minimum yang didukung adalah 23.
Melakukan inisialisasi SDK
ID penyedia (biasanya ID Project Google Cloud) diperlukan untuk
melakukan inisialisasi objek DriverContext
. Untuk detail selengkapnya tentang cara menyiapkan
Project Google Cloud, lihat
Autentikasi dan Otorisasi.
Sebelum menggunakan Driver SDK, Anda harus melakukan inisialisasi terlebih dahulu Navigation SDK. Untuk melakukan inisialisasi SDK:
Dapatkan objek
Navigator
dariNavigationApi
.Java
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; } } );
Kotlin
NavigationApi.getNavigator( this, // Activity object : NavigatorListener() { override fun onNavigatorReady(navigator: Navigator) { // Keep a reference to the Navigator (used to configure and start nav) this@myActivity.navigator = navigator } }, )
Buat objek
DriverContext
, dengan mengisi kolom yang wajib diisi.Java
DriverContext driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider( NavigationApi.getRoadSnappedLocationProvider(application)) .build();
Kotlin
val driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application)) .build()
Gunakan objek
DriverContext
untuk melakukan inisialisasi*DriverApi
.Java
RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
Kotlin
val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
Dapatkan
RidesharingVehicleReporter
dari objek API. (*VehicleReporter
memperluasNavigationVehicleReporter
.)Java
RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
Kotlin
val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
Mengautentikasi dengan AuthTokenFactory
Saat Driver SDK membuat pembaruan lokasi,
sistem harus mengirimkan
pembaruan tersebut ke
server Fleet Engine. Untuk mengotentikasi permintaan ini,
Driver SDK akan memanggil nomor yang disediakan penelepon
dari instance AuthTokenFactory
.
Factory bertanggung jawab untuk membuat token autentikasi di lokasi
waktu update.
Cara token dihasilkan akan spesifik sesuai dengan situasi setiap 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
:
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private String token; // 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(authTokenContext.getVehicleId());
}
return token;
}
private void fetchNewToken(String vehicleId) {
String url =
new Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token = obj.get("Token").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);
}
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: String = ""
private var expiryTimeMs: Long = 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 fun getToken(context: AuthTokenContext): String {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId())
}
return token
}
fun fetchNewToken(vehicleId: String) {
val url =
Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token = obj.get("ServiceToken").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 (e: IOException) {
// 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 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 tersebut adalah disimpan untuk digunakan kembali. Token diambil ulang jika token lama berada dalam waktu 10 menit tentang waktu habis masa berlakunya.
Implementasi Anda mungkin melakukan hal-hal yang berbeda, seperti menggunakan thread latar belakang untuk memperbarui token.
Pengecualian di AuthTokenFactory
akan diperlakukan sebagai sementara kecuali jika terjadi
berulang kali. Setelah beberapa kali percobaan, Driver SDK
akan mengasumsikan bahwa
kesalahan bersifat permanen dan akan berhenti mencoba mengirimkan pembaruan.
Pelaporan Status dan Error dengan StatusListener
Karena Driver SDK melakukan tindakan dalam
latar belakang, gunakan StatusListener
untuk memicu notifikasi saat
terjadi, seperti error, peringatan, atau pesan debug. Error mungkin
bersifat sementara (seperti BACKEND_CONNECTIVITY_ERROR
), atau mungkin
menyebabkan pembaruan lokasi dihentikan secara permanen (seperti VEHICLE_NOT_FOUND
,
yang menunjukkan error konfigurasi).
Anda menyediakan implementasi StatusListener
opsional seperti berikut:
Java
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.
}
}
Kotlin
class MyStatusListener : StatusListener() {
/** Called when background status is updated, during actions such as location reporting. */
override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
// 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 dengan aman
dengan server Fleet Engine. Versi Android yang lebih lama (API versi 19 atau
lebih rendah) mungkin memerlukan patch SecurityProvider
agar dapat berkomunikasi dengan
server tertentu. Anda akan melihat gambar ini
artikel
untuk informasi selengkapnya tentang cara menggunakan SSL di Android. Artikel ini juga
berisi contoh kode untuk mem-patch penyedia keamanan.
Mengaktifkan pembaruan lokasi
Setelah Anda memiliki instance *VehicleReporter
, mengaktifkan pembaruan lokasi adalah
langsung:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
Pembaruan lokasi dikirim pada interval reguler saat status kendaraan
ONLINE
. Perhatikan bahwa memanggil reporter.enableLocationTracking()
tidak
status kendaraan ditetapkan secara otomatis ke ONLINE
. Anda harus
menetapkan status kendaraan secara eksplisit.
Secara default, interval pelaporan adalah 10 detik. Interval pelaporan dapat
diubah dengan reporter.setLocationReportingInterval(long, TimeUnit)
. Tujuan
interval update minimum yang didukung adalah 5 detik. Pembaruan yang lebih sering dapat
menyebabkan permintaan dan error menjadi lebih lambat.
Menonaktifkan pembaruan lokasi
Ketika shift pengemudi selesai, pembaruan lokasi dapat dihentikan dan
kendaraan ditandai offline dengan menelepon
DeliveryVehicleReporter.disableLocationTracking
atau
RidesharingVehicleReporter.disableLocationTracking
.
Panggilan ini akan menjadwalkan satu pembaruan terakhir untuk segera dikirimkan, yang menunjukkan bahwa kendaraan sedang offline. Pembaruan ini tidak berisi lokasi HTTP/HTTPS.
Menetapkan status kendaraan
Saat pembaruan lokasi diaktifkan, menyetel status kendaraan ke ONLINE
akan
menyediakan kendaraan untuk kueri SearchVehicles
; juga menandai
kendaraan sebagai OFFLINE
akan menandai kendaraan tersebut sebagai tidak tersedia.
Anda memiliki opsi untuk menyetel status kendaraan di sisi server (lihat Memperbarui Kendaraan), atau langsung di Driver SDK:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
Saat pembaruan lokasi diaktifkan, panggilan ke setVehicleState
akan diterapkan di
pembaruan lokasi berikutnya.
Menandai kendaraan sebagai ONLINE
saat pelacakan lokasi tidak diaktifkan akan menghasilkan
di IllegalStateException
. Kendaraan dapat ditandai sebagai OFFLINE
saat
pelacakan lokasi belum diaktifkan atau dinonaktifkan secara eksplisit. Hal ini akan menghasilkan
dalam waktu nyata. Panggilan ke
RidesharingVehicleReporter.disableLocationTracking()
akan
tetapkan status kendaraan ke OFFLINE
.
Perhatikan bahwa setVehicleState
segera ditampilkan, dan update dilakukan pada
rangkaian pesan pembaruan lokasi. Mirip dengan penanganan error atas pembaruan lokasi, error
memperbarui status kendaraan akan disebarkan menggunakan atribut
StatusListener
ditetapkan di DriverContext
.