Anda dapat menggunakan Consumer SDK untuk membuat dan menjalankan aplikasi konsumen dasar yang terintegrasi dengan layanan backend Solusi Perjalanan dan Pengiriman On-demand. Anda dapat membuat aplikasi Perjalanan dan Progres Pesanan yang dapat menampilkan perjalanan aktif, merespons update perjalanan, dan menangani error perjalanan.
Karena Consumer SDK memiliki arsitektur modular, Anda dapat menggunakan bagian yang ingin Anda gunakan untuk aplikasi tertentu dan mengintegrasikannya dengan API Anda sendiri, layanan backend yang disediakan oleh Fleet Engine, dan API tambahan Google Maps Platform.
Persyaratan sistem minimum
Perangkat seluler harus menjalankan Android 6,0 (API level 23) atau yang lebih baru.
Konfigurasi build dan dependensi
Consumer SDK versi 1.99.0 dan yang lebih baru tersedia menggunakan Maven Google repositori resource. Saluran repositori pribadi yang sebelumnya digunakan tidak digunakan lagi.
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
Agar dapat menggunakan Consumer SDK untuk Android, aplikasi Anda harus menargetkan
minSdkVersion
23 atau lebih tinggi.
Untuk menjalankan aplikasi yang dibangun dengan Consumer 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 Consumer 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 Consumer SDK ke aplikasi Anda
Consumer SDK tersedia melalui repositori Maven pribadi. Tujuan yang berisi file Project Object Model (.pom) SDK dan Javadocs. Untuk menambahkan Consumer SDK ke aplikasi Anda:
Siapkan lingkungan Anda untuk mengakses repositori Maven host seperti yang dijelaskan di bagian sebelumnya.
Jika Anda telah mendeklarasikan konfigurasi manajemen dependensi terpusat di
settings.gradle
, nonaktifkan sebagai berikut.Hapus blok kode berikut di
settings.gradle
:import org.gradle.api.initialization.resolve.RepositoriesMode dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
Tambahkan dependensi berikut ke konfigurasi Gradle atau Maven Anda, dengan mengganti Placeholder
VERSION_NUMBER
untuk versi Consumer SDK yang diinginkan.Gradle
Tambahkan kode berikut ke
build.gradle
Anda:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER' }
Maven
Tambahkan kode berikut ke
pom.xml
Anda:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-consumer</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Consumer SDK bergantung pada Maps SDK. Dependensi ini dikonfigurasi sedemikian rupa sehingga jika versi Maps SDK tidak ditentukan secara eksplisit dalam file konfigurasi pembangunan seperti berikut, ketika versi baru Maps SDK dirilis, Consumer SDK akan terus menggunakan didukung versi Maps SDK yang diperlukan olehnya.
Gradle
Tambahkan kode berikut ke
build.gradle
Anda:dependencies { ... implementation 'com.google.android.gms:play-services-maps:18.1.0' }
Maven
Tambahkan kode berikut ke
pom.xml
Anda:<dependencies> ... <dependency> <groupId>com.google.android.gms</groupId> <artifactId>play-services-maps</artifactId> <version>18.1.0</version> </dependency> </dependencies>
Menambahkan kunci API ke aplikasi
Setelah menambahkan Consumer 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 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
padabuildscript
.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.consumerapidemo">
<uses-permission android:name="android.permission.ACCESS_FINE_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 SDK Konsumen 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}.
Autentikasi SDK Konsumen
Consumer SDK menyediakan autentikasi menggunakan Token Web JSON. JSON Web Token (JWT) adalah token akses basis JSON yang menyediakan klaim atau lebih pada suatu layanan. Misalnya, server dapat menghasilkan token yang memiliki klaim "login sebagai admin" serta menyediakan kepada klien. Klien kemudian dapat menggunakan token tersebut untuk membuktikan bahwa komputer itu login sebagai admin.
Consumer SDK menggunakan Token Web JSON yang disediakan oleh aplikasi untuk berkomunikasi dengan Fleet Engine. Lihat Otorisasi dan Autentikasi Mesin Armada untuk informasi selengkapnya.
Token otorisasi harus menyertakan klaim tripid:TRIP_ID
dalam token
Header authorization
, dengan TRIP_ID
adalah ID perjalanan. Hal ini memberi Konsumen
Akses SDK ke detail perjalanan, termasuk posisi kendaraan, rute, dan PWT.
Callback Token Web JSON
Consumer SDK mendaftarkan callback token otorisasi dengan aplikasi selama inisialisasi. SDK memanggil aplikasi untuk mendapatkan token untuk semua permintaan jaringan yang membutuhkan otorisasi.
Kami sangat merekomendasikan agar otorisasi cache penerapan callback Anda
token dan memperbaruinya hanya jika waktu expiry
telah berlalu. Token seharusnya
diberikan dengan masa berlaku satu jam.
Callback token otorisasi menentukan token layanan yang diperlukan
untuk layanan TripService
. Layanan ini juga memberikan tripId
yang diperlukan
sesuai konteks.
Contoh kode berikut menunjukkan cara menerapkan otorisasi callback token.
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private static final String TOKEN_URL =
"https://yourauthserver.example/token";
private static class CachedToken {
String tokenValue;
long expiryTimeMs;
String tripId;
}
private CachedToken token;
/*
* This method is called on a background thread. Blocking is OK. However, be
* aware that no information can be obtained from Fleet Engine until this
* method returns.
*/
@Override
public String getToken(AuthTokenContext context) {
// If there is no existing token or token has expired, go get a new one.
String tripId = context.getTripId();
if (tripId == null) {
throw new RuntimeException("Trip ID is missing from AuthTokenContext");
}
if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
!tripId.equals(token.tripId)) {
token = fetchNewToken(tripId);
}
return token.tokenValue;
}
private static CachedToken fetchNewToken(String tripId) {
String url = TOKEN_URL + "/" + tripId;
CachedToken token = new CachedToken();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token.tokenValue = obj.get("ServiceToken").getAsString();
token.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 5 minutes from that time.
*/
token.expiryTimeMs -= 5 * 60 * 1000;
} catch (IOException e) {
/*
* It's OK to throw exceptions here. The error listeners will receive the
* error thrown here.
*/
throw new RuntimeException("Could not get auth token", e);
}
token.tripId = tripId;
return token;
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: CachedToken? = null
/*
* This method is called on a background thread. Blocking is OK. However, be
* aware that no information can be obtained from Fleet Engine until this
* method returns.
*/
override fun getToken(context: AuthTokenContext): String {
// If there is no existing token or token has expired, go get a new one.
val tripId =
context.getTripId() ?:
throw RuntimeException("Trip ID is missing from AuthTokenContext")
if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
tripId != token.tripId) {
token = fetchNewToken(tripId)
}
return token.tokenValue
}
class CachedToken(
var tokenValue: String? = "",
var expiryTimeMs: Long = 0,
var tripId: String? = "",
)
private companion object {
const val TOKEN_URL = "https://yourauthserver.example/token"
fun fetchNewToken(tripId: String) {
val url = "$TOKEN_URL/$tripId"
val token = CachedToken()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token.tokenValue = obj.get("ServiceToken").getAsString()
token.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 5 minutes from that time.
*/
token.expiryTimeMs -= 5 * 60 * 1000
}
} catch (e: IOException) {
/*
* It's OK to throw exceptions here. The error listeners will receive the
* error thrown here.
*/
throw RuntimeException("Could not get auth token", e)
}
token.tripId = tripId
return token
}
}
}
Menginisialisasi API
Sebelum mengikuti prosedur ini, dianggap bahwa Anda telah mengaktifkan layanan yang sesuai dan Consumer SDK.
Mendapatkan instance ConsumerApi
Untuk menggunakan Consumer SDK, aplikasi Anda perlu melakukan inisialisasi
ConsumerApi
secara asinkron. API-nya adalah singleton.
Metode inisialisasi menggunakan AuthTokenFactory
. Pabrik menghasilkan
Token JWT untuk pengguna, jika diperlukan.
providerId
adalah Project ID untuk Project Google Cloud Anda. Lihat
Panduan Pengguna Fleet Engine
untuk informasi lebih lanjut
tentang pembuatan proyek.
Aplikasi Anda harus menerapkan AuthTokenFactory
seperti yang dijelaskan di
Autentikasi SDK Konsumen.
Java
Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
this, "myProviderId", authTokenFactory);
consumerApiTask.addOnSuccessListener(
consumerApi -> this.consumerApi = consumerApi);
Kotlin
val consumerApiTask =
ConsumerApi.initialize(this, "myProviderId", authTokenFactory)
consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
this@YourActivity.consumerApi = consumerApi
}
Perender Maps SDK dan Maps
Consumer SDK v2.x.x mendukung Maps SDK for Android v18.1.0 dan yang lebih baru. Tabel
di bawah ini merangkum perender default berdasarkan versi Maps SDK dan kemampuan dukungannya
dari kedua perender. Namun, sebaiknya gunakan perender terbaru jika Anda perlu
untuk menggunakan perender lama maka Anda dapat
menentukannya secara eksplisit menggunakan
MapsInitializer.initialize()
Versi Maps SDK | Mendukung perender terbaru | Mendukung perender lama | Perender default |
---|---|---|---|
V18.1.0 dan yang lebih lama | Ya | Ya | Lama* |
V18.2.0 | Ya | Ya | Terbaru |
* Dengan diluncurkannya Perender Maps baru, perender Terbaru akan menjadi default.
Menambahkan Maps SDK sebagai dependensi
Gradle
Tambahkan kode berikut ke build.gradle
Anda:
dependencies {
//...
implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}
Maven
Tambahkan kode berikut ke pom.xml
Anda:
<dependencies>
...
<dependency>
<groupId>com.google.android.gms</groupId>
<artifactId>play-services-maps</artifactId>
<version>18.1.0</version>
</dependency>
</dependencies>
Melakukan inisialisasi Maps SDK sebelum menginisialisasi Consumer SDK
Di class Application
atau Activity
start-up, panggil
MapsInitializer.initialize()
dan menunggu hasil permintaan perender sebelum melakukan inisialisasi
SDK Konsumen.
java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
initViews();
MapsInitializer.initialize(getApplicationContext(), Renderer.LATEST,
new OnMapsSdkInitializedCallback() {
@Override
public void onMapsSdkInitialized(Renderer renderer) {
switch (renderer) {
case LATEST:
Log.i("maps_renderer", "LATEST renderer");
break;
case LEGACY:
Log.i("maps_renderer", "LEGACY renderer");
break;
}
initializeConsumerSdk();
}
});
}
Kotlin
fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.main)
initViews()
MapsInitializer.initialize(
getApplicationContext(), Renderer.LATEST,
object : OnMapsSdkInitializedCallback() {
fun onMapsSdkInitialized(renderer: Renderer?) {
when (renderer) {
LATEST -> Log.i("maps_renderer", "LATEST renderer")
LEGACY -> Log.i("maps_renderer", "LEGACY renderer")
}
initializeConsumerSdk()
}
})
}
Membuat Antarmuka Pengguna
Anda dapat menggunakan ConsumerMapFragment
atau
ConsumerMapView
untuk membuat antarmuka pengguna
aplikasi. ConsumerMapFragment
memungkinkan Anda menentukan
peta Anda menggunakan
Fragment
, sedangkan ConsumerMapView
memungkinkan Anda menggunakan
View
Transportasi online
fungsinya sama, baik di ConsumerMapView
maupun
ConsumerMapFragment
, jadi Anda dapat memilih salah satu berdasarkan
apakah View
atau
Fragment
lebih baik untuk aplikasi Anda.
Menambahkan dukungan untuk API 19 (KitKat) dan Vector drawable
Jika desain aplikasi Anda memerlukan dukungan untuk perangkat API 19 (KitKat) dan vektor drawable,
tambahkan kode berikut ke Aktivitas Anda. Kode ini memperluas
AppCompatActivity
untuk menggunakan
Vektor drawable di Consumer SDK.
Java
// ...
import android.support.v7.app.AppCompatActivity;
// ...
public class ConsumerTestActivity extends AppCompatActivity {
// ...
}
Kotlin
// ...
import android.support.v7.app.AppCompatActivity
// ...
class ConsumerTestActivity : AppCompatActivity() {
// ...
}
Menambahkan fragmen atau tampilan peta
Anda membuat peta untuk menampilkan berbagi perjalanan di fragmen Android
atau tampilan, yang Anda definisikan di file XML tata letak aplikasi (terletak di
/res/layout
). Fragmen (atau tampilan) tersebut kemudian memberikan akses ke perjalanan
berbagi peta, yang dapat diakses
dan diubah oleh aplikasi Anda. Peta ini juga menyediakan
ke ConsumerController
, yang memungkinkan aplikasi Anda mengontrol dan
menyesuaikan pengalaman
berbagi perjalanan.
Peta dan pengontrol untuk berbagi perjalanan
Anda menentukan peta berbagi perjalanan sebagai fragmen (menggunakan
ConsumerMapFragment
), atau sebagai tampilan (menggunakan ConsumerMapView
), seperti yang ditunjukkan dalam
contoh kode berikut. Metode onCreate()
Anda akan memanggil
getConsumerGoogleMapAsync(callback)
, yang menampilkan ConsumerGoogleMap
secara asinkron dalam callback. Anda kemudian menggunakan ConsumerGoogleMap
untuk menampilkan
berbagi perjalanan, dan dapat diperbarui
sesuai kebutuhan aplikasi Anda.
ConsumerMapFragment
Anda menentukan fragmen dalam file XML tata letak aplikasi, seperti yang ditunjukkan dalam contoh kode berikut.
<fragment
xmlns:android="http://schemas.android.com/apk/res/android"
android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
android:id="@+id/consumer_map_fragment"
android:layout_width="match_parent"
android:layout_height="match_parent" />
Panggilan ke getConsumerGoogleMapAsync()
harus berasal dari onCreate()
.
Java
public class SampleAppActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
// Find the ConsumerMapFragment.
ConsumerMapFragment consumerMapFragment =
(ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);
// Initiate the callback that returns the map.
if (consumerMapFragment != null) {
consumerMapFragment.getConsumerGoogleMapAsync(
new ConsumerMapReadyCallback() {
// The map returned in the callback is used to access the ConsumerController.
@Override
public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
ConsumerController consumerController = consumerGoogleMap.getConsumerController();
}
});
}
}
}
Kotlin
class SampleAppActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
// Find the ConsumerMapFragment.
val consumerMapFragment =
fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment
consumerMapFragment.getConsumerGoogleMapAsync(
object : ConsumerMapReadyCallback() {
override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
val consumerController = consumerGoogleMap.getConsumerController()!!
}
}
)
}
}
ConsumerMapView
Tampilan ini bisa digunakan dalam fragmen atau aktivitas, seperti yang didefinisikan dalam XML.
<com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/consumer_map_view"
android:layout_width="match_parent"
android:layout_height="match_parent" />
Panggilan ke getConsumerGoogleMapAsync()
harus dari onCreate()
. Di beberapa
selain parameter callback, parameter ini memerlukan aktivitas yang memuat
fragmen, dan GoogleMapOptions
(yang boleh bernilai null), yang berisi konfigurasi
atribut untuk MapView
. Class dasar aktivitas atau fragmen harus berupa
FragmentActivity
atau Fragment
dukungan (masing-masing), karena menyediakan
akses ke siklus prosesnya.
Java
public class SampleAppActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
ConsumerMapView mapView = findViewById(R.id.consumer_map_view);
if (mapView != null) {
mapView.getConsumerGoogleMapAsync(
new ConsumerMapReadyCallback() {
// The map returned in the callback is used to access the ConsumerController.
@Override
public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
ConsumerController consumerController = consumerGoogleMap.getConsumerController();
}
}, this, null);
}
}
}
Kotlin
class SampleAppActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView
mapView.getConsumerGoogleMapAsync(
object : ConsumerMapReadyCallback() {
// The map returned in the callback is used to access the ConsumerController.
override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
val consumerController = consumerGoogleMap.getConsumerController()!!
}
},
/* fragmentActivity= */ this,
/* googleMapOptions= */ null,
)
}
}
MapView
dalam fragmen sama dengan contoh di atas untuk MapView
dalam
aktivitas, kecuali fragmen meng-inflate tata letak yang menyertakan
MapView
dalam metode onCreateView()
fragmen.
Java
public class MapViewInFragment extends Fragment {
@Override
public View onCreateView(
@NonNull LayoutInflater layoutInflater,
@Nullable ViewGroup viewGroup,
@Nullable Bundle bundle) {
return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
}
}
Kotlin
class MapViewInFragment : Fragment() {
override fun onCreateView(
layoutInflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?,
): View {
return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
}
}
Menyesuaikan zoom kamera untuk berfokus pada perjalanan
Tombol Lokasiku default bawaan Maps SDK menempatkan kamera di tengah lokasi perangkat.
Jika ada sesi Berbagi Perjalanan yang aktif, Anda mungkin perlu memusatkan kamera untuk berfokus pada perjalanan, bukan lokasi perangkat.
Solusi bawaan SDK Konsumen untuk Android: AutoCamera
Agar Anda dapat fokus pada perjalanan, bukan lokasi perangkat, Consumer SDK menyediakan fitur Kamera Otomatis yang diaktifkan secara default. Kamera akan memperbesar gambar untuk berfokus pada rute berbagi perjalanan dan titik jalan perjalanan berikutnya.
Menyesuaikan perilaku kamera
Jika memerlukan kontrol lebih besar atas perilaku kamera, Anda dapat menonaktifkan atau mengaktifkan kamera otomatis menggunakan ConsumerController.setAutoCameraEnabled().
ConsumerController.getCameraUpdate() menampilkan batas kamera yang direkomendasikan pada saat itu. Anda kemudian dapat memberikan CameraUpdate
ini sebagai argumen untuk
GoogleMap.moveCamera() atau GoogleMap.animateCamera().
Akses transportasi online dan peta
Untuk mendukung transportasi online dan interaksi peta di aplikasi Anda, Anda memerlukan akses
ke ConsumerGoogleMap
dan
ConsumerController
.
ConsumerMapFragment
dan
ConsumerMapView
keduanya secara asinkron
ConsumerGoogleMap
di ConsumerMapReadyCallback
.
Pengembalian dengan biaya ConsumerGoogleMap
ConsumerController
dari getConsumerController()
. Anda
dapat mengakses ConsumerGoogleMap
dan
ConsumerController
sebagai berikut.
Java
private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;
consumerMapView.getConsumerGoogleMapAsync(
new ConsumerMapReadyCallback() {
@Override
public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
consumerGoogleMap = consumerMap;
consumerController = consumerMap.getConsumerController();
}
},
this, null);
Kotlin
var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView
consumerMapView.getConsumerGoogleMapAsync(
object : ConsumerMapReadyCallback() {
override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
consumerGoogleMap = consumerMap
consumerController = consumerMap.getConsumerController()
},
/* fragmentActivity= */ this,
/* googleMapOptions= */ null,
}
)
ConsumerGoogleMap
ConsumerGoogleMap
adalah class wrapper untuk
Class GoogleMap
. ID ini memberi aplikasi Anda kemampuan untuk
berinteraksi dengan peta menggunakan API yang setara dengan
GoogleMap
. Menggunakan peta konsumen memungkinkan aplikasi Anda dan perjalanan
berbagi data untuk berinteraksi secara lancar dengan GoogleMap pokok yang sama. Misalnya,
GoogleMap
hanya mengizinkan pendaftaran callback tunggal, tetapi
ConsumerGoogleMap
mendukung callback terdaftar ganda.
Callback ini memungkinkan aplikasi dan transportasi online Anda mendaftarkan callback yang
disebut secara berurutan.
ConsumerController
ConsumerController
memberikan akses ke fungsi transportasi online seperti
seperti memantau perjalanan, mengontrol status perjalanan, dan menetapkan lokasi.
Menyiapkan berbagi perjalanan
Setelah backend mencocokkan konsumen dengan kendaraan, gunakan JourneySharingSession
untuk memulai antarmuka
{i>user journey<i}. Berbagi perjalanan menampilkan
lokasi dan rute kendaraan. Setelah menerapkan SDK di aplikasi, Anda dapat menambahkan
fungsi untuk memantau perjalanan, memproses pembaruan, dan menangani error.
Prosedur berikut mengasumsikan bahwa layanan backend sudah tersedia dan bahwa
layanan untuk mencocokkan konsumen dengan kendaraan telah beroperasi.
Daftarkan pemroses pada objek
TripModel
untuk mendapatkan detail tentang perjalanan seperti PWT (Perkiraan Waktu Kedatangan) dan jaraknya yang perlu dilalui kendaraan sebelum kedatangan.Java
// Create a TripModel instance for listening to updates to the trip specified by this trip name. String tripName = ...; TripModelManager tripModelManager = consumerApi.getTripModelManager(); TripModel tripModel = tripModelManager.getTripModel(tripName); // Create a JourneySharingSession instance based on the TripModel. JourneySharingSession session = JourneySharingSession.createInstance(tripModel); // Add the JourneySharingSession instance on the map for updating the UI. consumerController.showSession(session); // Register for trip update events. tripModel.registerTripCallback(new TripModelCallback() { @Override public void onTripETAToNextWaypointUpdated( TripInfo tripInfo, @Nullable Long timestampMillis) { // ... } @Override public void onTripActiveRouteRemainingDistanceUpdated( TripInfo tripInfo, @Nullable Integer distanceMeters) { // ... } // ... });
Kotlin
// Create a TripModel instance for listening to updates to the trip specified by this trip name. val tripName = "tripName" val tripModelManager = consumerApi.getTripModelManager() val tripModel = tripModelManager.getTripModel(tripName) // Create a JourneySharingSession instance based on the TripModel. val session = JourneySharingSession.createInstance(tripModel) // Add the JourneySharingSession instance on the map for updating the UI. consumerController.showSession(session) // Register for trip update events. tripModel.registerTripCallback( object : TripModelCallback() { override fun onTripETAToNextWaypointUpdated( tripInfo: TripInfo, timestampMillis: Long?, ) { // ... } override fun onTripActiveRouteRemainingDistanceUpdated( tripInfo: TripInfo, distanceMeters: Int?, ) { // ... } // ... })
Konfigurasi perjalanan Anda menggunakan
TripModelOptions
.Java
// Set refresh interval to 2 seconds. TripModelOptions tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build(); tripModel.setTripModelOptions(tripOptions);
Kotlin
// Set refresh interval to 2 seconds. val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build() tripModel.setTripModelOptions(tripOptions)
Hentikan berbagi perjalanan
Pastikan Anda menghentikan berbagi perjalanan jika tidak diperlukan lagi, seperti saat aktivitas host dihancurkan. Menghentikan berbagi perjalanan juga akan menghentikan permintaan jaringan ke Fleet Engine, dan mencegah kebocoran memori.
Kode contoh berikut menunjukkan cara menghentikan berbagi perjalanan.
Java
public class MainActivity extends AppCompatActivity
implements ConsumerViewModel.JourneySharingListener {
// Class implementation
@Override
protected void onDestroy() {
super.onDestroy();
if (journeySharingSession != null) {
journeySharingSession.stop();
}
}
}
Kotlin
class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {
// Class implementation
override fun onDestroy() {
super.onDestroy()
journeySharingSession?.stop()
}
}
Menangani error perjalanan
Metode onTripRefreshError
menampilkan error yang terjadi selama pemantauan perjalanan.
Pemetaan untuk Consumer SDK
mengikuti pedoman HTTP/RPC yang sama yang dibuat untuk
Google Cloud Platform.
Error umum yang muncul selama pemantauan perjalanan meliputi:
HTTP | PPK | Deskripsi |
---|---|---|
400 | INVALID_ARGUMENT | Klien menentukan nama perjalanan yang tidak valid. Tujuan
nama perjalanan harus mengikuti format
providers/{provider_id}/trips/{trip_id} .
Atribut provider_id harus berupa ID
Project Cloud yang dimiliki oleh penyedia layanan. |
401 | TIDAK DIAUTENTIKASI | Permintaan tidak diautentikasi karena token JWT tidak valid. Kesalahan ini akan terjadi jika token JWT ditandatangani tanpa perjalanan atau token JWT telah kedaluwarsa. |
403 | PERMISSION_DENIED | Klien tidak memiliki cukup izin akses. Error ini terjadi jika JWT token tidak valid, klien tidak memiliki izin akses, atau API tidak diaktifkan untuk proyek klien. Token JWT dapat berupa tidak ada atau token ditandatangani dengan perjalanan id yang tidak cocok dengan id perjalanan yang diminta. |
429 | RESOURCE_EXHAUSTED | Kuota resource sama sekali atau tidak ada samanya traffic melebihi batas. |
503 | UNAVAILABLE | Layanan tidak tersedia. Biasanya server turun. |
504 | DEADLINE_EXCEEDED | Batas waktu permintaan terlampaui. Hal ini akan hanya terjadi jika pemanggil menetapkan batas waktu yang lebih pendek dari metode batas waktu (yaitu batas waktu yang diminta bukan bagi server untuk memproses ) dan permintaan tidak selesai melebihi batas waktu. |
Untuk informasi selengkapnya, lihat Penanganan Error SDK Konsumen.