میتوانید از Consumer SDK برای ساخت و اجرای یک برنامه مصرفکننده اساسی که با خدمات باطنی Rides و Deliveries Solution بر اساس تقاضا یکپارچه شده است، استفاده کنید. می توانید یک برنامه Trip and Order Progress ایجاد کنید که می تواند یک سفر فعال را نمایش دهد، به به روز رسانی سفر پاسخ دهد و خطاهای سفر را مدیریت کند.
از آنجایی که Consumer SDK یک معماری ماژولار دارد، میتوانید از بخشهایی از API که میخواهید برای برنامه خاص خود استفاده کنید استفاده کنید و آنها را با APIهای خود، سرویسهای Backend ارائهشده توسط Fleet Engine و APIهای اضافی پلتفرم نقشههای Google ادغام کنید. .
کمترین سیستم مورد نیاز
دستگاه همراه باید دارای Android 6.0 (سطح API 23) یا بالاتر باشد.
پیکربندی ساخت و وابستگی ها
نسخه 1.99.0 و جدیدتر SDK مصرف کننده با استفاده از مخزن Google Maven در دسترس است. کانال مخزن خصوصی که قبلا استفاده شده بود منسوخ شده است.
گریدل
موارد زیر را به فایل build.gradle
خود اضافه کنید:
repositories {
...
google()
}
ماون
موارد زیر را به فایل pom.xml
خود اضافه کنید:
<project>
...
<repositories>
<repository>
<id>google-maven-repository</id>
<url>https://maven.google.com</url>
</repository>
</repositories>
...
</project>
پیکربندی پروژه
برای استفاده از Consumer SDK برای Android، برنامه شما باید minSdkVersion
23 یا بالاتر را هدف قرار دهد.
برای اجرای برنامهای که با Consumer SDK ساخته شده است، دستگاه Android باید سرویسهای Google Play را نصب کرده باشد.
پروژه توسعه خود را تنظیم کنید
برای راهاندازی پروژه توسعه خود و دریافت کلید API برای پروژه در Google Cloud Console:
یک پروژه جدید Google Cloud Console ایجاد کنید یا یک پروژه موجود را برای استفاده با Consumer SDK انتخاب کنید. چند دقیقه صبر کنید تا پروژه جدید در Google Cloud Console قابل مشاهده باشد.
برای اجرای برنامه آزمایشی، پروژه شما باید به Maps SDK برای اندروید دسترسی داشته باشد. در Google Cloud Console، APIs & Services > Library را انتخاب کنید، سپس Maps SDK for Android را جستجو و فعال کنید.
با انتخاب APIs & Services > Credentials > Create credentials > API key، یک کلید API برای پروژه دریافت کنید. برای اطلاعات بیشتر درباره دریافت کلید API، به دریافت کلید API مراجعه کنید.
Consumer SDK را به برنامه خود اضافه کنید
Consumer SDK از طریق مخزن خصوصی Maven در دسترس است. این مخزن شامل فایلهای Project Object Model (.pom) SDK و Javadocs است. برای افزودن Consumer SDK به برنامه خود:
همانطور که در بخش قبل توضیح داده شد، محیط خود را برای دسترسی به مخزن میزبان Maven تنظیم کنید.
اگر پیکربندی مدیریت وابستگی متمرکزی دارید که در
settings.gradle
اعلام شده است، آن را به صورت زیر غیرفعال کنید.بلوک کد زیر را در
settings.gradle
حذف کنید:import org.gradle.api.initialization.resolve.RepositoriesMode dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید و جای جای
VERSION_NUMBER
را جایگزین نسخه مورد نظر Consumer SDK کنید.گریدل
موارد زیر را به
build.gradle
خود اضافه کنید:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER' }
ماون
موارد زیر را به
pom.xml
خود اضافه کنید:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-consumer</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Consumer SDK به Maps SDK بستگی دارد. این وابستگی به گونه ای پیکربندی شده است که اگر نسخه Maps SDK به صراحت در فایل پیکربندی ساخت مانند زیر تعریف نشده باشد ، زمانی که نسخه جدیدی از Maps SDK منتشر شد، SDK مصرف کننده به استفاده از حداقل نسخه Maps SDK پشتیبانی شده ادامه خواهد داد . مورد نیاز آن است.
گریدل
موارد زیر را به
build.gradle
خود اضافه کنید:dependencies { ... implementation 'com.google.android.gms:play-services-maps:18.1.0' }
ماون
موارد زیر را به
pom.xml
خود اضافه کنید:<dependencies> ... <dependency> <groupId>com.google.android.gms</groupId> <artifactId>play-services-maps</artifactId> <version>18.1.0</version> </dependency> </dependencies>
کلید API را به برنامه خود اضافه کنید
هنگامی که Consumer SDK را به برنامه خود اضافه کردید، کلید API را به برنامه خود اضافه کنید. شما باید از کلید API پروژه که هنگام راه اندازی پروژه توسعه خود به دست آورده اید استفاده کنید.
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند با امنیت بیشتری توسط برنامه شما ارجاع دهد. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید. باید در فایل local.properties
که در دایرکتوری ریشه پروژه شما قرار دارد ذخیره شود. برای اطلاعات بیشتر در مورد فایل local.properties
، فایل های ویژگی های Gradle را ببینید.
برای سادهسازی این کار، میتوانید از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه و ذخیره کلید API:
فایل
build.gradle
سطح ریشه خود را باز کنید و کد زیر را به عنصرdependencies
در زیرbuildscript
اضافه کنید.شیار
buildscript { dependencies { // ... classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0" } }
کاتلین
buildscript { dependencies { // ... classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0") } }
فایل
build.gradle
سطح برنامه خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.شیار
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
کاتلین
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
اگر از Android Studio استفاده می کنید، پروژه خود را با Gradle همگام کنید .
local.properties
در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید.MAPS_API_KEY=YOUR_API_KEY
در فایل
AndroidManifest.xml
خود، بهcom.google.android.geo.API_KEY
بروید و ویژگیandroid:value
به صورت زیر به روز کنید:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
مثال زیر یک مانیفست کامل را برای یک برنامه نمونه نشان می دهد:
<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>
اسناد مورد نیاز را در برنامه خود قرار دهید
اگر از Consumer SDK در برنامه خود استفاده می کنید، باید متن منبع و مجوزهای منبع باز را به عنوان بخشی از بخش اعلامیه های قانونی برنامه خود قرار دهید. بهتر است انتسابها را بهعنوان یک آیتم منوی مستقل یا بهعنوان بخشی از یک آیتم درباره منو درج کنید.
اطلاعات مجوزها را می توان در فایل "third_party_licenses.txt" در فایل AAR بایگانی نشده پیدا کرد.
در مورد نحوه گنجاندن اعلامیه های منبع باز به https://developers.google.com/android/guides/opensource مراجعه کنید.
احراز هویت SDK مصرف کننده
Consumer SDK با استفاده از JSON Web Tokens احراز هویت را فراهم می کند. JSON Web Token (JWT) یک نشانه دسترسی مبتنی بر JSON است که یک یا چند ادعا را در مورد یک سرویس ارائه می دهد. به عنوان مثال، یک سرور میتواند توکنی تولید کند که ادعای «بهعنوان مدیر وارد شده» باشد و آن را در اختیار مشتری قرار دهد. سپس مشتری می تواند از آن توکن برای اثبات اینکه به عنوان مدیر وارد شده است استفاده کند.
Consumer SDK از JSON Web Token ارائه شده توسط برنامه برای ارتباط با Fleet Engine استفاده می کند. برای اطلاعات بیشتر به احراز هویت و مجوز ناوگان موتور مراجعه کنید.
نشانه مجوز باید شامل یک ادعای tripid:TRIP_ID
در سرصفحه authorization
رمز باشد، جایی که TRIP_ID
شناسه سفر است. این امکان دسترسی Consumer SDK را به جزئیات سفر، از جمله موقعیت وسیله نقلیه، مسیر، و ETA میدهد.
پاسخ تماس JSON Web Token
Consumer SDK یک پاسخ تماس توکن مجوز را با برنامه در طول مقداردهی اولیه ثبت می کند. SDK برنامه را فراخوانی میکند تا برای تمام درخواستهای شبکه که نیاز به مجوز دارند، یک رمز دریافت کند.
اکیداً توصیه میکنیم که توکنهای مجوز اجرای Cache Backback خود را بهروزرسانی کنید و فقط زمانی که زمان expiry
گذشته است، آنها را بازخوانی کنید. توکن ها باید با انقضای یک ساعته صادر شوند.
پاسخ تماس توکن مجوز مشخص می کند که کدام توکن سرویس برای سرویس TripService
مورد نیاز است. همچنین tripId
مورد نیاز را برای متن فراهم می کند.
مثال کد زیر نشان می دهد که چگونه می توان یک پاسخ تماس توکن مجوز را پیاده سازی کرد.
جاوا
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;
}
}
کاتلین
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
}
}
}
API را راه اندازی کنید
قبل از دنبال کردن این مراحل، فرض بر این است که شما خدمات مناسب و Consumer SDK را فعال کرده اید.
نمونه ConsumerApi
را دریافت کنید
برای استفاده از Consumer SDK، برنامه شما باید ConsumerApi
به صورت ناهمزمان مقداردهی اولیه کند. API یک تکتونه است. روش مقداردهی اولیه یک AuthTokenFactory
می گیرد. کارخانه در صورت لزوم توکن های جدید JWT را برای کاربر تولید می کند.
providerId
شناسه پروژه Google Cloud Project شما است. برای اطلاعات بیشتر در مورد ایجاد پروژه به راهنمای کاربر Fleet Engine مراجعه کنید.
برنامه شما باید AuthTokenFactory
همانطور که در Consumer SDK Authentication توضیح داده شده پیاده سازی کند.
جاوا
Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
this, "myProviderId", authTokenFactory);
consumerApiTask.addOnSuccessListener(
consumerApi -> this.consumerApi = consumerApi);
کاتلین
val consumerApiTask =
ConsumerApi.initialize(this, "myProviderId", authTokenFactory)
consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
this@YourActivity.consumerApi = consumerApi
}
Maps SDK و ارائهدهنده نقشهها
Consumer SDK v2.xx از Maps SDK for Android نسخه 18.1.0 و بالاتر پشتیبانی می کند. جدول زیر رندر پیشفرض بر اساس نسخه Maps SDK و قابلیت پشتیبانی هر دو رندر را خلاصه میکند. توصیه میکنیم از جدیدترین رندرکننده استفاده کنید، با این حال، اگر نیاز به استفاده از رندر قدیمی دارید، میتوانید به صراحت آن را با استفاده از MapsInitializer.initialize()
مشخص کنید.
نسخه SDK نقشه ها | از آخرین رندر پشتیبانی می کند | از رندر قدیمی پشتیبانی می کند | رندر پیش فرض |
---|---|---|---|
V18.1.0 و پایین تر | آره | آره | میراث* |
V18.2.0 | آره | آره | آخرین |
* با عرضه Maps Renderer جدید ، آخرین رندر پیش فرض خواهد بود.
Maps SDK را به عنوان یک وابستگی اضافه کنید
گریدل
موارد زیر را به build.gradle
خود اضافه کنید:
dependencies {
//...
implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}
ماون
موارد زیر را به pom.xml
خود اضافه کنید:
<dependencies>
...
<dependency>
<groupId>com.google.android.gms</groupId>
<artifactId>play-services-maps</artifactId>
<version>18.1.0</version>
</dependency>
</dependencies>
قبل از مقداردهی اولیه SDK مصرف کننده، Maps SDK را راه اندازی کنید
در کلاس Application
یا Start-up Activity
خود، MapsInitializer.initialize() را فراخوانی کنید و قبل از شروع به کار Consumer SDK منتظر نتیجه درخواست رندر باشید.
جاوا
@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();
}
});
}
کاتلین
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()
}
})
}
رابط کاربری را ایجاد کنید
می توانید از ConsumerMapFragment
یا ConsumerMapView
برای ایجاد رابط کاربری برای برنامه خود استفاده کنید. ConsumerMapFragment
به شما امکان می دهد نقشه خود را با استفاده از یک Fragment
تعریف کنید در حالی که ConsumerMapView
به شما امکان می دهد از یک View
استفاده کنید. عملکرد اشتراک گذاری سواری در ConsumerMapView
و ConsumerMapFragment
یکسان است، بنابراین می توانید بر اساس اینکه View
یا Fragment
برای برنامه شما بهتر است یکی را انتخاب کنید.
پشتیبانی از API 19 (KitKat) و کششهای Vector را اضافه کنید
اگر طراحی برنامه شما نیاز به پشتیبانی از دستگاههای API 19 (KitKat) و نقشههای برداری دارد، کد زیر را به Activity خود اضافه کنید. این کد AppCompatActivity
برای استفاده از ترسیمهای Vector در Consumer SDK گسترش میدهد.
جاوا
// ...
import android.support.v7.app.AppCompatActivity;
// ...
public class ConsumerTestActivity extends AppCompatActivity {
// ...
}
کاتلین
// ...
import android.support.v7.app.AppCompatActivity
// ...
class ConsumerTestActivity : AppCompatActivity() {
// ...
}
قطعه یا نمای نقشه را اضافه کنید
شما نقشه را برای نمایش اشتراک گذاری سفر در یک قطعه Android یا یک نمای ایجاد می کنید که در فایل XML طرح بندی برنامه خود (واقع در /res/layout
) تعریف می کنید. سپس قطعه (یا نمای) دسترسی به نقشه اشتراک گذاری سفر را فراهم می کند، که برنامه شما می تواند به آن دسترسی داشته باشد و آن را تغییر دهد. این نقشه همچنین دستهای را در اختیار ConsumerController
قرار میدهد که به برنامه شما اجازه میدهد تجربه اشتراکگذاری سفر را کنترل و سفارشی کند.
نقشه و کنترلر به اشتراک گذاری سفر
همانطور که در مثال کد زیر نشان داده شده است، نقشه اشتراک گذاری سفر را به عنوان یک قطعه (با استفاده از ConsumerMapFragment
)، یا به عنوان یک نما (با استفاده از ConsumerMapView
) تعریف می کنید. متد onCreate()
شما باید getConsumerGoogleMapAsync(callback)
را فراخوانی کند، که ConsumerGoogleMap
به صورت ناهمزمان در تماس برگشتی برمی گرداند. سپس از ConsumerGoogleMap
برای نمایش اشتراکگذاری سفر استفاده میکنید و میتوانید آن را در صورت نیاز توسط برنامه شما بهروزرسانی کنید.
ConsumerMapFragment
همانطور که در مثال کد زیر نشان داده شده است، قطعه را در فایل XML طرح بندی برنامه خود تعریف می کنید.
<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" />
فراخوانی getConsumerGoogleMapAsync()
باید از روش onCreate()
باشد.
جاوا
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();
}
});
}
}
}
کاتلین
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
نمای را می توان در یک قطعه یا در یک فعالیت استفاده کرد، همانطور که در فایل 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" />
تماس با getConsumerGoogleMapAsync()
باید از onCreate()
باشد. علاوه بر پارامتر پاسخ به تماس، به فعالیت یا قطعه شامل، و GoogleMapOptions
(که میتواند تهی باشد)، حاوی ویژگیهای پیکربندی برای MapView
نیاز دارد. اکتیویتی یا کلاس پایه قطعه باید به ترتیب یک FragmentActivity
یا یک Fragment
پشتیبانی باشد، زیرا آنها دسترسی به چرخه حیات آن را فراهم می کنند.
جاوا
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);
}
}
}
کاتلین
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
در یک قطعه مانند مثال بالا برای MapView
در یک اکتیویتی است، با این تفاوت که قطعه طرحی را که شامل MapView
در متد onCreateView()
افزایش میدهد.
جاوا
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);
}
}
کاتلین
class MapViewInFragment : Fragment() {
override fun onCreateView(
layoutInflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?,
): View {
return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
}
}
تنظیم زوم دوربین برای تمرکز بر یک سفر
دکمه پیشفرض My Location که در Maps SDK تعبیه شده است، دوربین را روی مکان دستگاه متمرکز میکند.
اگر جلسه اشتراک گذاری سفر فعالی وجود دارد، ممکن است بخواهید دوربین را در مرکز قرار دهید تا به جای مکان دستگاه، روی سفر تمرکز کند.
راه حل داخلی SDK مصرف کننده برای Android: AutoCamera
برای اینکه بتوانید به جای مکان دستگاه روی سفر تمرکز کنید، Consumer SDK یک ویژگی AutoCamera را ارائه می دهد که به طور پیش فرض فعال است. دوربین بزرگنمایی می کند تا روی مسیر اشتراک گذاری سفر و ایستگاه بعدی سفر تمرکز کند.
سفارشی کردن رفتار دوربین
اگر به کنترل بیشتری بر رفتار دوربین نیاز دارید، میتوانید دوربین خودکار را با استفاده از ConsumerController.setAutoCameraEnabled() غیرفعال یا فعال کنید.
ConsumerController.getCameraUpdate() محدوده های توصیه شده دوربین را در آن لحظه برمی گرداند. سپس می توانید این CameraUpdate
به عنوان یک آرگومان برای GoogleMap.moveCamera() یا GoogleMap.animateCamera() ارائه دهید.
به اشتراک گذاری سواری و نقشه ها دسترسی داشته باشید
برای پشتیبانی از اشتراک گذاری سواری و تعامل نقشه در برنامه خود، باید به ConsumerGoogleMap
و ConsumerController
دسترسی داشته باشید. ConsumerMapFragment
و ConsumerMapView
هر دو به طور ناهمزمان ConsumerGoogleMap
در ConsumerMapReadyCallback
برمیگردانند. ConsumerGoogleMap
ConsumerController
از getConsumerController()
برمی گرداند. به صورت زیر می توانید به ConsumerGoogleMap
و ConsumerController
دسترسی داشته باشید.
جاوا
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);
کاتلین
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
یک کلاس پوششی برای کلاس GoogleMap
است. این امکان را برای برنامه شما فراهم می کند تا با استفاده از یک API معادل GoogleMap
با نقشه تعامل داشته باشد. استفاده از نقشه مصرفکننده به برنامه و اشتراکگذاری سواری شما اجازه میدهد تا با همان GoogleMap زیربنایی تعامل یکپارچه داشته باشد. به عنوان مثال، GoogleMap
تنها امکان ثبت نام پاسخ به تماس را می دهد، اما ConsumerGoogleMap
از تماس های ثبت شده دوگانه پشتیبانی می کند. این تماسها به برنامه و اشتراکگذاری سواری شما اجازه میدهد تا تماسهایی را که بهطور متوالی فراخوانی میشوند، ثبت کند.
ConsumerController
ConsumerController
دسترسی به قابلیت های اشتراک گذاری سواری مانند نظارت بر سفرها، کنترل وضعیت سفر و تنظیم مکان ها را فراهم می کند.
راهاندازی اشتراکگذاری سفر
پس از اینکه باطن یک مصرف کننده را با یک وسیله نقلیه مطابقت داد، از JourneySharingSession
برای شروع رابط کاربری اشتراک گذاری سفر استفاده کنید. اشتراکگذاری سفر، مکان و مسیر وسیله نقلیه منطبق را نشان میدهد. پس از اجرای SDK در برنامه خود، می توانید عملکرد نظارت بر سفرها، گوش دادن به به روز رسانی ها و رسیدگی به خطاها را اضافه کنید. رویههای زیر فرض میکنند که سرویسهای پشتیبان وجود دارند و خدمات شما برای تطبیق مصرفکنندگان با وسایل نقلیه عملیاتی است.
یک شنونده را در یک شی
TripModel
ثبت کنید تا جزئیات سفر مانند ETA (زمان تخمینی رسیدن) و مسافتی که وسیله نقلیه باید قبل از رسیدن طی کند را دریافت کنید.جاوا
// 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) { // ... } // ... });
کاتلین
// 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?, ) { // ... } // ... })
سفر خود را با استفاده از
TripModelOptions
پیکربندی کنید.جاوا
// Set refresh interval to 2 seconds. TripModelOptions tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build(); tripModel.setTripModelOptions(tripOptions);
کاتلین
// Set refresh interval to 2 seconds. val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build() tripModel.setTripModelOptions(tripOptions)
اشتراک گذاری سفر را متوقف کنید
اطمینان حاصل کنید که اشتراک گذاری سفر را زمانی که دیگر مورد نیاز نیست، مانند زمانی که فعالیت میزبان از بین می رود، متوقف می کنید. توقف اشتراکگذاری سفر همچنین درخواستهای شبکه به Fleet Engine را متوقف میکند و از نشت حافظه جلوگیری میکند.
کد نمونه زیر نحوه توقف اشتراک گذاری سفر را نشان می دهد.
جاوا
public class MainActivity extends AppCompatActivity
implements ConsumerViewModel.JourneySharingListener {
// Class implementation
@Override
protected void onDestroy() {
super.onDestroy();
if (journeySharingSession != null) {
journeySharingSession.stop();
}
}
}
کاتلین
class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {
// Class implementation
override fun onDestroy() {
super.onDestroy()
journeySharingSession?.stop()
}
}
خطاهای سفر را مدیریت کنید
روش onTripRefreshError
خطاهایی را که در حین نظارت بر سفر رخ می دهد را نشان می دهد. نقشه برداری برای خطاهای Consumer SDK از همان دستورالعمل های HTTP/RPC پیروی می کند که برای Google Cloud Platform ایجاد شده است. خطاهای رایجی که در حین نظارت بر سفر ظاهر می شوند عبارتند از:
HTTP | RPC | شرح |
---|---|---|
400 | INVALID_ARGUMENT | مشتری یک نام سفر نامعتبر مشخص کرده است. نام سفر باید از فرمت providers/{provider_id}/trips/{trip_id} پیروی کند. Provider_id باید شناسه پروژه Cloud متعلق به ارائه دهنده خدمات باشد. |
401 | بدون احراز هویت | درخواست به دلیل یک توکن JWT نامعتبر احراز هویت نشد. اگر توکن JWT بدون شناسه سفر امضا شده باشد یا نشانه JWT منقضی شده باشد، این خطا رخ می دهد. |
403 | PERMISSION_DENIED | مشتری مجوز کافی ندارد. اگر توکن JWT نامعتبر باشد، کلاینت مجوز نداشته باشد یا API برای پروژه مشتری فعال نباشد، این خطا رخ می دهد. ممکن است رمز JWT وجود نداشته باشد یا رمز با شناسه سفری امضا شده باشد که با شناسه سفر درخواستی مطابقت ندارد. |
429 | RESOURCE_EXHAUSTED | سهمیه منابع صفر است یا میزان ترافیک از حد مجاز فراتر می رود. |
503 | غیر قابل دسترسی | سرویس در دسترس نیست. به طور معمول سرور از کار افتاده است. |
504 | DEADLINE_EXCEEDED | مهلت درخواست فراتر رفت. این تنها در صورتی اتفاق میافتد که تماسگیرنده ضربالاجلی کوتاهتر از مهلت پیشفرض متد تعیین کند (یعنی مهلت درخواستی برای پردازش درخواست توسط سرور کافی نباشد) و درخواست در مهلت تعیین شده به پایان نرسد. |
برای اطلاعات بیشتر، به مدیریت خطاهای SDK مصرف کننده مراجعه کنید.