Bắt đầu với SDK người tiêu dùng dành cho Android

Bạn có thể sử dụng SDK người tiêu dùng để xây dựng và chạy một ứng dụng cơ bản dành cho người tiêu dùng, tích hợp với các dịch vụ phụ trợ Giải pháp gọi xe và giao hàng theo yêu cầu. Bạn có thể tạo ứng dụng Chuyến đi và Tiến trình đặt hàng có thể hiển thị một chuyến đi đang diễn ra, phản hồi thông tin cập nhật về chuyến đi và xử lý các lỗi về chuyến đi.

Vì SDK người tiêu dùng có cấu trúc mô-đun, nên bạn có thể sử dụng các phần của API mà bạn muốn sử dụng cho ứng dụng cụ thể của mình cũng như tích hợp các API đó bằng API của riêng bạn, các dịch vụ phụ trợ do Fleet Engine cung cấp, và các API bổ sung của Nền tảng Google Maps.

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

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

Cấu hình bản dựng và phần phụ thuộc

SDK người tiêu dùng phiên bản 1.99.0 trở lên có sẵn bằng Google Maven kho lưu trữ. Kênh kho lưu trữ riêng tư được sử dụng trước đây không còn được dùng nữa.

Gradle

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

repositories {
    ...
    google()
}

Maven

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

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

Cấu hình dự án

Để sử dụng SDK dành cho người tiêu dùng cho Android, ứng dụng của bạn phải nhắm mục tiêu minSdkVersion 23 trở lên.

Để chạy một ứng dụng tạo bằng SDK người tiêu dùng, Android thiết bị phải có Dịch vụ Google Play .

Thiết lập dự án phát triển

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

  1. Tạo dự án mới trên Google Cloud Console hoặc chọn một dự án hiện có để sử dụng thông qua SDK Người tiêu dùng. Đợi vài phút cho đến khi dự án mới sẽ hiển thị trên Bảng điều khiển Google Cloud.

  2. Để chạy ứng dụng minh hoạ, dự án của bạn phải có quyền truy cập vào SDK bản đồ cho Android. Trong Google Cloud Console, hãy chọn API và Dịch vụ > thư viện, sau đó tìm kiếm và bật SDK Maps cho Android.

  3. Nhận khoá API cho dự án bằng cách chọn API và Dịch vụ > Thông tin xác thực > Tạo thông tin xác thực > Khoá API. Để biết thêm thông tin về cách tải khoá API, hãy xem Tải khoá API.

Thêm SDK người tiêu dùng vào ứng dụng

SDK Người tiêu dùng có sẵn thông qua một kho lưu trữ Maven riêng tư. Chiến lược phát hành đĩa đơn kho lưu trữ bao gồm các tệp Mô hình đối tượng dự án (.pom) của SDK và Javadocs. Cách thêm SDK người tiêu dùng vào ứng dụng:

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

    Nếu bạn khai báo cấu hình quản lý phần phụ thuộc ở một nơi tập trung settings.gradle, hãy tắt tính năng này như sau.

    • Xoá khối mã dưới đây trong settings.gradle:

      import org.gradle.api.initialization.resolve.RepositoriesMode
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

  2. Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven, thay thế phần phụ thuộc Phần giữ chỗ VERSION_NUMBER cho phiên bản SDK người tiêu dùng mong muốn.

    Gradle

    Thêm phần sau vào build.gradle:

    dependencies {
  ...
  implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER'
}

    Maven

    Thêm phần sau vào pom.xml:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
    <artifactId>transportation-consumer</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

  3. SDK người tiêu dùng phụ thuộc vào SDK Maps. Phần phụ thuộc này được định cấu hình trong một theo cách đó nếu phiên bản SDK Maps không được xác định rõ ràng trong tệp cấu hình bản dựng như sau, khi một phiên bản mới của Maps SDK được phát hành, SDK người tiêu dùng sẽ tiếp tục sử dụng SDK tối thiểu được hỗ trợ mà phiên bản SDK Maps yêu cầu.

    Gradle

    Thêm phần sau vào build.gradle:

    dependencies {
  ...
  implementation 'com.google.android.gms:play-services-maps:18.1.0'
}

    Maven

    Thêm phần sau vào pom.xml:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.gms</groupId>
    <artifactId>play-services-maps</artifactId>
    <version>18.1.0</version>
  </dependency>
</dependencies>

Thêm khoá API vào ứng dụng của bạn

Sau khi thêm SDK người tiêu dùng vào ứng dụng, hãy thêm khoá API vào ứng dụng. Bạn phải sử dụng khoá API của dự án mà bạn đã nhận được khi thiết lập dự án phát triển của bạn.

Phần này mô tả cách lưu trữ khoá API để bạn có thể sử dụng khoá một cách an toàn hơn mà ứng dụng của bạn tham chiếu đến. Bạn không nên kiểm tra khoá API trong phiên bản của mình hệ thống kiểm soát. Thông tin này phải được lưu trữ trong tệp local.properties, tức là nằm trong thư mục gốc của dự án. Để biết thêm thông tin về local.properties tệp, xem Các tệp thuộc tính Gradle.

Để đơn giản hoá công việc này, bạn có thể sử dụng Trình bổ trợ Secrets Gradle cho Android.

Cách cài đặt trình bổ trợ và lưu trữ khoá API:

  1. Mở tệp build.gradle ở cấp cơ sở rồi thêm mã sau vào tệp Phần tử dependencies trong buildscript.

    Groovy

    buildscript {
    dependencies {
        // ...
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
    }
}

    Kotlin

    buildscript {
    dependencies {
        // ...
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
    }
}

  2. Mở tệp build.gradle ở cấp ứng dụng rồi thêm mã sau vào tệp Phần tử plugins.

    Groovy

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

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")

  3. Nếu sử dụng Android Studio, đồng bộ hoá dự án với Gradle.

  4. Mở local.properties trong thư mục cấp dự án rồi thêm sau đây. Thay thế YOUR_API_KEY bằng khoá API.

    MAPS_API_KEY=YOUR_API_KEY

  5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY rồi cập nhật thuộc tính android:value như sau:

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

Ví dụ sau đây trình bày một tệp kê khai hoàn chỉnh cho một ứng dụng mẫu:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.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>

Đưa các thuộc tính bắt buộc vào ứng dụng của bạn

Nếu sử dụng SDK người tiêu dùng trong ứng dụng, bạn phải đưa vào văn bản ghi công và giấy phép nguồn mở như một phần trong thông báo pháp lý của ứng dụng . Tốt nhất là nên bao gồm các thuộc tính dưới dạng một mục trình đơn độc lập hoặc dưới dạng một phần của mục trong trình đơn Giới thiệu.

Bạn có thể tìm thấy thông tin về giấy phép tại "third_party_permissions.txt" tệp trong tệp AAR đã huỷ lưu trữ.

Tham khảo https://developers.google.com/android/guides/opensource về cách đưa thông báo nguồn mở vào.

Xác thực SDK người tiêu dùng

SDK người tiêu dùng cung cấp tính năng xác thực bằng Mã thông báo web JSON. Mã thông báo web JSON (JWT) là mã truy cập cơ sở JSON cung cấp hoặc nhiều khiếu nại khác về một dịch vụ. Ví dụ: máy chủ có thể tạo mã thông báo có thông báo "đăng nhập với tư cách quản trị viên" và cung cấp điều đó cho một khách hàng. Sau đó, khách hàng có thể dùng mã thông báo đó để chứng minh rằng thiết bị được đăng nhập với vai trò quản trị viên.

SDK người tiêu dùng sử dụng Mã thông báo web JSON do ứng dụng cung cấp để giao tiếp với Fleet Engine. Tham khảo phần Xác thực và uỷ quyền cho Fleet Engine để biết thêm thông tin.

Mã thông báo uỷ quyền phải bao gồm thông báo xác nhận quyền sở hữu tripid:TRIP_ID trong Tiêu đề authorization, trong đó TRIP_ID là mã chuyến đi. Điều này cho phép Người tiêu dùng Quyền truy cập của SDK vào thông tin chi tiết về chuyến đi, bao gồm cả vị trí của xe, tuyến đường và giờ đến dự kiến.

Lệnh gọi lại Mã thông báo web JSON

SDK người tiêu dùng đăng ký lệnh gọi lại mã thông báo uỷ quyền với ứng dụng trong quá trình khởi chạy. SDK gọi ứng dụng để nhận mã thông báo cho tất cả yêu cầu mạng yêu cầu uỷ quyền.

Bạn nên uỷ quyền bộ nhớ đệm triển khai lệnh gọi lại và chỉ làm mới chúng khi đã hết thời gian expiry. Mã thông báo phải sẽ được phát hành với thời hạn một giờ.

Lệnh gọi lại mã thông báo uỷ quyền chỉ định mã thông báo dịch vụ cần thiết cho dịch vụ TripService. Lớp này cũng cung cấp tripId bắt buộc cho ngữ cảnh.

Ví dụ về mã sau đây minh hoạ cách triển khai lệnh uỷ quyền gọi lại mã thông báo.

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

Khởi chạy API

Trước khi thực hiện theo các quy trình này, giả định rằng bạn đã bật các dịch vụ phù hợp và SDK Người tiêu dùng.

Tải thực thể ConsumerApi

Để sử dụng SDK người tiêu dùng, ứng dụng của bạn cần khởi chạy ConsumerApi không đồng bộ. API này là một singleton. Phương thức khởi chạy sẽ lấy AuthTokenFactory. Nhà máy tạo ra Mã thông báo JWT cho người dùng khi cần thiết.

providerId là Mã dự án của dự án trên Google Cloud. Xem Hướng dẫn sử dụng Fleet Engine để biết thêm thông tin về cách tạo dự án.

Ứng dụng của bạn nên triển khai AuthTokenFactory như mô tả trong Xác thực SDK người tiêu dùng.

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
}

SDK Maps và trình kết xuất bản đồ

SDK người tiêu dùng phiên bản 2.x.x hỗ trợ SDK Maps dành cho Android phiên bản 18.1.0 trở lên. Bảng bên dưới tóm tắt trình kết xuất đồ hoạ mặc định theo phiên bản SDK Maps và khả năng hỗ trợ của cả hai trình kết xuất. Tuy nhiên, nếu bạn cần sử dụng trình kết xuất đồ hoạ mới nhất để sử dụng trình kết xuất đồ hoạ cũ, sau đó bạn có thể chỉ định rõ ràng bằng cách sử dụng MapsInitializer.initialize().

Phiên bản SDK Maps Hỗ trợ trình kết xuất đồ hoạ mới nhất Hỗ trợ trình kết xuất đồ hoạ cũ Trình kết xuất đồ hoạ mặc định
Phiên bản 18.1.0 trở xuống Có Có Kế thừa*
V18.2.0 Có Có Mới nhất

* Với việc phát hành Trình kết xuất Maps mới, trình kết xuất đồ hoạ mới nhất sẽ được đặt theo mặc định.

Thêm SDK Maps làm phần phụ thuộc

Gradle

Thêm phần sau vào build.gradle:

dependencies {
  //...
  implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}

Maven

Thêm phần sau vào pom.xml:

 <dependencies>
   ...
   <dependency>
     <groupId>com.google.android.gms</groupId>
     <artifactId>play-services-maps</artifactId>
     <version>18.1.0</version>
   </dependency>
 </dependencies>

Chạy SDK Maps trước khi khởi chạy SDK người tiêu dùng

Trong lớp Application hoặc lớp Activity đã khởi động, hãy gọi MapsInitializer.initialize() và đợi kết quả yêu cầu trình kết xuất trước khi khởi chạy SDK người tiêu dùng.

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()
      }
    })
  }

Tạo giao diện người dùng

Bạn có thể sử dụng ConsumerMapFragment hoặc ConsumerMapView để tạo giao diện người dùng cho . ConsumerMapFragment cho phép bạn xác định bản đồ của bạn bằng cách sử dụng Fragment trong khi ConsumerMapView cho phép bạn sử dụng View. Chia sẻ chuyến đi chức năng giống nhau trong cả ConsumerMapView và ConsumerMapFragment, nên bạn có thể chọn một tuỳ chọn dựa trên có thể là View hoặc Fragment phù hợp hơn cho ứng dụng của bạn.

Thêm tính năng hỗ trợ cho API 19 (KitKat) và Vectơ vẽ được

Nếu thiết kế ứng dụng của bạn cần hỗ trợ cho thiết bị API 19 (KitKat) và các vectơ vẽ được, thêm mã sau vào Hoạt động của bạn. Mã này mở rộng AppCompatActivity để sử dụng Các vectơ vẽ được trong SDK người dùng.

Java

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

Thêm mảnh bản đồ hoặc chế độ xem

Bạn tạo bản đồ để hiển thị thông tin chia sẻ hành trình trong một mảnh Android hoặc một khung hiển thị mà bạn xác định trong tệp XML bố cục ứng dụng (nằm trong /res/layout). Sau đó, mảnh (hoặc khung hiển thị) cung cấp quyền truy cập vào hành trình chia sẻ bản đồ mà ứng dụng của bạn có thể truy cập và sửa đổi. Bản đồ cũng cung cấp vào ConsumerController để cho phép ứng dụng kiểm soát và tuỳ chỉnh trải nghiệm chia sẻ hành trình.

Bản đồ và bộ điều khiển chia sẻ hành trình

Bạn xác định bản đồ chia sẻ hành trình dưới dạng một mảnh (sử dụng ConsumerMapFragment) hoặc dưới dạng chế độ xem (sử dụng ConsumerMapView), như được thể hiện trong đoạn mã ví dụ sau. Khi đó, phương thức onCreate() của bạn sẽ gọi getConsumerGoogleMapAsync(callback) trả về ConsumerGoogleMap không đồng bộ trong lệnh gọi lại. Sau đó, bạn dùng ConsumerGoogleMap để hiển thị hành trình chia sẻ và ứng dụng của bạn có thể cập nhật dữ liệu này khi cần.

ConsumerMapFragment

Bạn xác định mảnh trong tệp XML bố cục ứng dụng, như minh hoạ trong ví dụ về mã sau đây.

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

Lệnh gọi đến getConsumerGoogleMapAsync() phải đến từ 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

Bạn có thể sử dụng thành phần hiển thị trong một mảnh hoặc trong một hoạt động, như được xác định trong Tệp 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" />

Lệnh gọi đến getConsumerGoogleMapAsync() phải từ onCreate(). Ngang bằng ngoài tham số gọi lại, phương thức này đòi hỏi phải chứa hoạt động hoặc và GoogleMapOptions (có thể rỗng) chứa cấu hình cho MapView. Lớp cơ sở của hoạt động hoặc mảnh phải là FragmentActivity hoặc Fragment hỗ trợ (tương ứng) vì chúng cung cấp quyền truy cập vào vòng đời của nó.

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 trong một mảnh giống như ví dụ trên cho MapView trong một hoạt động, ngoại trừ việc mảnh tăng cường bố cục chứa MapView trong phương thức onCreateView() của mảnh.

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

Điều chỉnh mức thu phóng của máy ảnh để tập trung vào một hành trình

Nút Vị trí của tôi mặc định được tích hợp trong SDK Maps đặt máy ảnh vào giữa vị trí thiết bị.

Nếu có một phiên Chia sẻ hành trình đang diễn ra, bạn nên đặt camera vào giữa để tập trung vào hành trình thay vì vị trí thiết bị.

SDK người dùng dành cho giải pháp tích hợp Android: AutoCamera

Để cho phép bạn tập trung vào hành trình thay vì vị trí của thiết bị, SDK người tiêu dùng cung cấp tính năng AutoCamera bật theo mặc định. Máy ảnh thu phóng để tập trung vào tuyến đường chia sẻ hành trình và điểm tham chiếu tiếp theo.

AutoCamera

Tuỳ chỉnh hoạt động của máy ảnh

Nếu cần kiểm soát nhiều hơn hành vi của máy ảnh, bạn có thể tắt hoặc bật camera tự động bằng ConsumerController.setAutoCameraEnabled().

ConsumerController.getCameraUpdate() sẽ trả về giới hạn máy ảnh được đề xuất tại thời điểm đó. Sau đó, bạn có thể cung cấp CameraUpdate này làm đối số cho GoogleMap.moveCamera() hoặc GoogleMap.animateCamera().

Truy cập tính năng đi chung xe và bản đồ

Để hỗ trợ tính năng đi chung xe và tương tác trên bản đồ trong ứng dụng của bạn, bạn cần có quyền truy cập đến ConsumerGoogleMap và ConsumerController ConsumerMapFragment và ConsumerMapView trả về không đồng bộ ConsumerGoogleMap trong ConsumerMapReadyCallback. Trả lại hàng với mức phí ConsumerGoogleMap ConsumerController từ getConsumerController(). Bạn có thể truy cập vào ConsumerGoogleMap và ConsumerController như sau.

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 là một lớp trình bao bọc cho Lớp GoogleMap. Điều này mang lại cho ứng dụng của bạn khả năng tương tác với bản đồ bằng một API tương đương với GoogleMap. Việc sử dụng bản đồ người tiêu dùng giúp ứng dụng của bạn có thể di chuyển chia sẻ để tương tác liền mạch với cùng một GoogleMap cơ bản. Ví dụ: GoogleMap chỉ cho phép đăng ký một lệnh gọi lại, nhưng ConsumerGoogleMap hỗ trợ các lệnh gọi lại được đăng ký kép. Các lệnh gọi lại này cho phép ứng dụng và tính năng chia sẻ chuyến đi đăng ký các lệnh gọi lại được gọi tuần tự.

ConsumerController

ConsumerController cung cấp quyền truy cập vào chức năng chia sẻ chuyến đi, chẳng hạn như như theo dõi chuyến đi, kiểm soát trạng thái chuyến đi và đặt vị trí.

Thiết lập tính năng chia sẻ hành trình

Sau khi phần phụ trợ đã so khớp người tiêu dùng với một chiếc xe, hãy sử dụng JourneySharingSession để bắt đầu giao diện người dùng chia sẻ hành trình. Tính năng Chia sẻ hành trình cho thấy những người phù hợp vị trí và tuyến đường của xe. Sau khi triển khai SDK trong ứng dụng của mình, bạn có thể thêm chức năng theo dõi các chuyến đi, theo dõi thông tin cập nhật và xử lý lỗi. Các quy trình sau giả định các dịch vụ phụ trợ đã có sẵn và các dịch vụ tìm phương tiện cho người tiêu dùng đã đi vào hoạt động.

  1. Đăng ký trình nghe trên đối tượng TripModel để biết thông tin chi tiết về chuyến đi như ETA (Thời gian đến ước tính) và khoảng cách xe cần đi trước khi đến nơi.

    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. Thiết lập chuyến đi của bạn bằng 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)

Ngừng chia sẻ hành trình

Đảm bảo rằng bạn ngừng chia sẻ hành trình khi không còn cần đến, chẳng hạn như khi hoạt động của máy chủ lưu trữ bị huỷ. Việc dừng tính năng chia sẻ hành trình cũng ngăn không cho các yêu cầu mạng gửi đến Fleet Engine, và tránh rò rỉ bộ nhớ.

Mã mẫu sau đây minh hoạ cách ngừng chia sẻ hành trình.

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()
  }
}

Xử lý lỗi về chuyến đi

Phương thức onTripRefreshError cho thấy các lỗi xảy ra trong quá trình theo dõi chuyến đi. Liên kết cho SDK người tiêu dùng tuân theo cùng các nguyên tắc HTTP/RPC đã được thiết lập cho Google Cloud Platform. Sau đây là một số lỗi thường gặp trong quá trình theo dõi chuyến đi:

HTTP RPC Mô tả
400 INVALID_ARGUMENT Khách hàng đã chỉ định tên chuyến đi không hợp lệ. Chiến lược phát hành đĩa đơn tên chuyến đi phải theo định dạng providers/{provider_id}/trips/{trip_id}. provider_id phải là mã của Dự án trên đám mây do nhà cung cấp dịch vụ sở hữu.
401 KHÔNG XÁC THỰC Yêu cầu không được xác thực do mã thông báo JWT không hợp lệ. Lỗi này sẽ xảy ra nếu mã thông báo JWT được ký mà không có chuyến đi id hoặc mã thông báo JWT đã hết hạn.
403 PERMISSION_DENIED Ứng dụng không có đủ quyền. Lỗi này xảy ra nếu JWT mã thông báo không hợp lệ, máy khách không có hoặc API không được bật cho dự án khách hàng. Mã thông báo JWT có thể là bị thiếu hoặc mã thông báo đã được ký với một chuyến đi không khớp với mã chuyến đi được yêu cầu.
429 RESOURCE_EXHAUSTED Hạn mức tài nguyên bằng 0 hoặc bằng tỷ lệ lưu lượng truy cập vượt quá giới hạn.
503 KHÔNG CÓ Dịch vụ hiện không hoạt động. Thông thường, máy chủ đã giảm.
504 DEADLINE_EXCEEDED Đã vượt quá thời hạn yêu cầu. Thao tác này sẽ chỉ xảy ra nếu phương thức gọi đặt thời hạn ngắn hơn giá trị mặc định của phương thức hạn chót (tức là hạn chót được yêu cầu không phải là đủ để máy chủ xử lý và yêu cầu không kết thúc trong thời hạn.

Để biết thêm thông tin, hãy xem Xử lý lỗi về SDK dành cho người tiêu dùng.