Memulai Consumer SDK untuk Android

Anda dapat menggunakan Consumer SDK untuk mem-build 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 info terbaru perjalanan, dan menangani error perjalanan.

Karena Consumer SDK memiliki arsitektur modular, Anda dapat menggunakan bagian API yang ingin digunakan 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 repositori Maven Google. Saluran repositori pribadi yang digunakan sebelumnya sudah 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

Untuk menggunakan Consumer SDK for Android, aplikasi Anda harus menargetkan minSdkVersion 23 atau yang lebih tinggi.

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

Menyiapkan project pengembangan

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

  1. Buat project Konsol Google Cloud baru, atau pilih project yang sudah ada, untuk digunakan dengan Consumer SDK. Tunggu beberapa menit hingga 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 Consumer SDK ke aplikasi

Consumer SDK tersedia melalui repositori Maven pribadi. Repositori ini mencakup file Project Object Model (.pom) SDK dan Javadocs. Untuk menambahkan Consumer SDK ke aplikasi Anda:

  1. Siapkan lingkungan Anda untuk mengakses repositori Maven host seperti yang dijelaskan di bagian sebelumnya.

    Jika Anda memiliki konfigurasi manajemen dependensi terpusat yang dideklarasikan dalam settings.gradle, nonaktifkan seperti 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()
    }
}

  2. Tambahkan dependensi berikut ke konfigurasi Gradle atau Maven Anda, dengan mengganti placeholder VERSION_NUMBER dengan 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>

  3. Consumer SDK bergantung pada Maps SDK. Dependensi ini dikonfigurasi sedemikian rupa sehingga jika versi Maps SDK tidak ditentukan secara eksplisit dalam file konfigurasi build seperti berikut, saat versi baru Maps SDK dirilis, Consumer SDK akan terus menggunakan versi Maps SDK minimum yang didukung 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 Anda.

Bagian ini menjelaskan cara menyimpan kunci API sehingga dapat dirujuk dengan lebih aman oleh aplikasi Anda. Anda tidak boleh memasukkan kunci API ke sistem kontrol versi Anda. File tersebut harus disimpan dalam file local.properties, yang berada di direktori utama project 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:

  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. Jika Anda menggunakan Android Studio, sinkronkan project Anda dengan Gradle.

  4. Buka local.properties pada direktori tingkat project, lalu tambahkan kode berikut. Ganti 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.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 Anda

Jika menggunakan Consumer SDK di aplikasi, Anda harus menyertakan teks atribusi dan lisensi open source sebagai bagian dari bagian pemberitahuan hukum aplikasi Anda. 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.

Autentikasi SDK Konsumen

Consumer SDK menyediakan autentikasi menggunakan Token Web JSON. JSON Web Token (JWT) adalah token akses dasar JSON yang memberikan satu atau beberapa klaim pada suatu layanan. Misalnya, server dapat membuat token yang memiliki klaim "login sebagai admin" dan memberikannya kepada klien. Klien kemudian dapat menggunakan token tersebut untuk membuktikan bahwa ia login sebagai admin.

Consumer SDK menggunakan Token Web JSON yang disediakan oleh aplikasi untuk berkomunikasi dengan Fleet Engine. Lihat Autentikasi dan Otorisasi Fleet Engine untuk informasi selengkapnya.

Token otorisasi harus menyertakan klaim tripid:TRIP_ID di header authorization token, dengan TRIP_ID sebagai ID perjalanan. Tindakan ini memberi SDK Konsumen akses 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 semua permintaan jaringan yang memerlukan otorisasi.

Sebaiknya Anda membuat token otorisasi cache implementasi callback dan memperbaruinya hanya jika waktu expiry telah berlalu. Token harus diterbitkan dengan masa berlaku satu jam.

Callback token otorisasi menentukan token layanan mana yang diperlukan untuk layanan TripService. Kode ini juga menyediakan tripId yang diperlukan untuk konteksnya.

Contoh kode berikut menunjukkan cara mengimplementasikan callback token otorisasi.

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, Anda dianggap telah mengaktifkan layanan yang sesuai dan Consumer SDK.

Mendapatkan instance ConsumerApi

Untuk menggunakan Consumer SDK, aplikasi Anda harus melakukan inisialisasi ConsumerApi secara asinkron. API-nya adalah singleton. Metode inisialisasi memerlukan AuthTokenFactory. Pabrik akan membuat token JWT baru untuk pengguna jika diperlukan.

providerId adalah Project ID dari Project Google Cloud Anda. Lihat Panduan Pengguna Fleet Engine untuk mengetahui informasi selengkapnya tentang cara membuat project.

Aplikasi Anda harus menerapkan AuthTokenFactory seperti yang dijelaskan dalam 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
}

Maps SDK dan perender peta

Consumer SDK v2.x.x mendukung Maps SDK for Android v18.1.0 dan yang lebih baru. Tabel di bawah ini meringkas perender default berdasarkan versi Maps SDK dan kemampuan dukungan kedua perender. Namun, sebaiknya gunakan perender terbaru jika Anda perlu menggunakan perender lama, sehingga 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>

Menginisialisasi Maps SDK sebelum menginisialisasi Consumer SDK

Di class Application atau Activity startup, panggil MapsInitializer.initialize() dan tunggu hasil permintaan perender sebelum menginisialisasi Consumer SDK.

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 bagi aplikasi Anda. ConsumerMapFragment memungkinkan Anda menentukan peta menggunakan Fragment, sedangkan ConsumerMapView memungkinkan Anda menggunakan View. Fungsi berbagi perjalanan sama di ConsumerMapView dan ConsumerMapFragment, sehingga Anda dapat memilih salah satunya berdasarkan apakah View atau Fragment lebih baik untuk aplikasi Anda.

Menambahkan dukungan untuk API 19 (KitKat) dan Vektor drawable

Jika desain aplikasi Anda memerlukan dukungan untuk perangkat API 19 (KitKat) dan vektor drawable, tambahkan kode berikut ke Activity 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 dalam fragmen Android atau tampilan, yang Anda tentukan dalam file XML tata letak aplikasi (terletak di /res/layout). Fragmen (atau tampilan) kemudian memberikan akses ke peta berbagi perjalanan, yang dapat diakses dan diubah oleh aplikasi Anda. Peta ini juga menyediakan handle untuk ConsumerController, yang memungkinkan aplikasi Anda mengontrol dan menyesuaikan pengalaman berbagi perjalanan.

Peta dan pengontrol berbagi perjalanan

Anda menentukan peta berbagi perjalanan sebagai fragmen (menggunakan ConsumerMapFragment), atau sebagai tampilan (menggunakan ConsumerMapView), seperti yang ditunjukkan dalam contoh kode berikut. Selanjutnya, metode onCreate() Anda harus memanggil getConsumerGoogleMapAsync(callback), yang menampilkan ConsumerGoogleMap secara asinkron dalam callback. Anda kemudian menggunakan ConsumerGoogleMap untuk menampilkan berbagi perjalanan, dan itu 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 metode 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 dapat digunakan dalam fragmen atau aktivitas, seperti yang ditetapkan dalam file XML Anda.

<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(). Selain parameter callback, parameter ini juga memerlukan aktivitas atau fragmen yang memuatnya, dan GoogleMapOptions (yang dapat bernilai null), yang berisi atribut konfigurasi untuk MapView. Class dasar aktivitas atau fragmen harus berupa FragmentActivity atau Fragment dukungan (masing-masing), karena keduanya memberikan 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 suatu aktivitas, kecuali bahwa fragmen tersebut 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 fokus pada perjalanan

Tombol Lokasiku default yang ada di Maps SDK memusatkan kamera di lokasi perangkat.

Jika ada sesi Berbagi Perjalanan yang aktif, sebaiknya Anda menempatkan kamera di tengah untuk berfokus pada perjalanan, bukan lokasi perangkat.

Solusi bawaan SDK Konsumen untuk Android: AutoCamera

Agar Anda dapat berfokus pada perjalanan, bukan lokasi perangkat, Consumer SDK menyediakan fitur AutoCamera yang diaktifkan secara default. Kamera melakukan zoom untuk fokus pada rute berbagi perjalanan dan titik jalan perjalanan berikutnya.

AutoCamera

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 ke GoogleMap.moveCamera() atau GoogleMap.animateCamera().

Akses transportasi online dan peta

Untuk mendukung transportasi online dan interaksi peta dalam aplikasi, Anda memerlukan akses ke ConsumerGoogleMap dan ConsumerController. ConsumerMapFragment dan ConsumerMapView secara asinkron menampilkan ConsumerGoogleMap di ConsumerMapReadyCallback. ConsumerGoogleMap menampilkan 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. Hal ini memberi aplikasi Anda kemampuan untuk berinteraksi dengan peta menggunakan API yang setara dengan GoogleMap. Penggunaan peta konsumen memungkinkan aplikasi dan transportasi online Anda 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 dipanggil secara berurutan.

ConsumerController

ConsumerController memberikan akses ke fungsi transportasi online seperti memantau perjalanan, mengontrol status perjalanan, dan menetapkan lokasi.

Menyiapkan fitur berbagi perjalanan

Setelah backend mencocokkan konsumen dengan kendaraan, gunakan JourneySharingSession untuk memulai antarmuka pengguna berbagi perjalanan. Berbagi perjalanan menampilkan lokasi dan rute kendaraan yang dicocokkan. Setelah menerapkan SDK di aplikasi, Anda dapat menambahkan fungsi untuk memantau perjalanan, memproses update, dan menangani error. Prosedur berikut mengasumsikan bahwa layanan backend telah tersedia dan layanan Anda untuk mencocokkan konsumen dengan kendaraan telah beroperasi.

  1. Daftarkan pemroses pada objek TripModel untuk mendapatkan detail tentang perjalanan seperti PWT (Perkiraan Waktu Kedatangan) dan jarak yang perlu ditempuh 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?,
    ) {
      // ...
    }

  // ...
})

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

Berhenti berbagi perjalanan

Pastikan Anda menghentikan berbagi perjalanan saat tidak lagi diperlukan, 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 error SDK Konsumen mengikuti panduan HTTP/RPC yang sama dengan yang dibuat untuk Google Cloud Platform. Error umum yang muncul selama pemantauan perjalanan mencakup:

HTTP RPC Deskripsi
400 INVALID_ARGUMENT Klien menentukan nama perjalanan yang tidak valid. 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 AUTENTIKASI Permintaan tidak diautentikasi karena token JWT tidak valid. Error ini akan terjadi jika token JWT ditandatangani tanpa ID perjalanan atau token JWT sudah tidak berlaku.
403 PERMISSION_DENIED Klien tidak memiliki izin yang memadai. Error ini terjadi jika token JWT tidak valid, klien tidak memiliki izin, atau API tidak diaktifkan untuk project klien. Token JWT mungkin hilang atau token ditandatangani dengan ID perjalanan yang tidak cocok dengan ID perjalanan yang diminta.
429 RESOURCE_EXHAUSTED Kuota resource nol atau tingkat traffic melebihi batas.
503 UNAVAILABLE Layanan tidak tersedia. Biasanya server tidak aktif.
504 DEADLINE_EXCEEDED Batas waktu permintaan terlampaui. Hal ini hanya akan terjadi jika pemanggil menetapkan batas waktu yang lebih pendek dari batas waktu default metode (yaitu, batas waktu yang diminta tidak cukup bagi server untuk memproses permintaan) dan permintaan tidak selesai dalam batas waktu tersebut.

Untuk informasi selengkapnya, lihat Penanganan Error SDK Konsumen.