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 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:
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.
Để chạy ứng dụng minh hoạ, dự án của bạn phải có quyền truy cập vào SDK Maps 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.
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:
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() } }
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>
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:
Mở tệp
build.gradle
ở cấp cơ sở rồi thêm mã sau vào tệp Phần tửdependencies
trongbuildscript
.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") } }
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")
Nếu sử dụng Android Studio, đồng bộ hoá dự án với Gradle.
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
Trong tệp
AndroidManifest.xml
, hãy chuyển đếncom.google.android.geo.API_KEY
rồi cập nhật thuộc tínhandroid: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()
. Trong
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.
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.
Đă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?, ) { // ... } // ... })
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 | Hàm 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.