يمكنك استخدام حزمة تطوير البرامج (SDK) الخاصة بالمستهلك لإنشاء وتشغيل تطبيق مستهلِك أساسي متكامل من خلال خدمات الواجهة الخلفية لحلول الرحلات وعمليات التسليم عند الطلب. يمكنك إنشاء تطبيق Trip and Order Progress الذي يمكنه عرض رحلة نشطة والاستجابة لتحديثات الرحلة والتعامل مع أخطاء الرحلة.
ونظرًا لأن حزمة تطوير البرامج (SDK) الخاصة بالمستهلك لها بنية نموذجية، يمكنك استخدام الأجزاء من واجهة برمجة التطبيقات التي تريد استخدامها لتطبيقك المعيّن ودمجها مع واجهات برمجة التطبيقات الخاصة بك، وخدمات الخلفية التي يوفرها Fleet Engine، بالإضافة إلى واجهات برمجة التطبيقات الخاصة بمنصة خرائط Google.
الحد الأدنى لمتطلبات النظام
يجب أن يعمل الجهاز الجوّال بنظام Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) أو مستوى أحدث.
تكوين الإصدار والتبعيات
يتوفّر الإصدار 1.99.0 والإصدارات الأحدث من حزمة تطوير البرامج (SDK) للمستهلكين باستخدام Google Maven. المستودع. تم إيقاف قناة المستودع الخاص المستخدَمة سابقًا.
Gradle
أضِف ما يلي إلى ملف build.gradle
:
repositories {
...
google()
}
Maven
أضِف ما يلي إلى ملف pom.xml
:
<project>
...
<repositories>
<repository>
<id>google-maven-repository</id>
<url>https://maven.google.com</url>
</repository>
</repositories>
...
</project>
تكوين المشروع
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين لنظام التشغيل Android، يجب أن يستهدف التطبيق
الإصدار 23 من minSdkVersion
أو الإصدارات الأحدث
لتشغيل تطبيق تم إنشاؤه باستخدام حزمة تطوير البرامج (SDK) للمستهلكين، يمكن لنظام يجب أن يتضمّن الجهاز خدمات Google Play مثبت.
إعداد مشروع التطوير
لإعداد مشروع التطوير والحصول على مفتاح واجهة برمجة التطبيقات للمشروع على Google Cloud Console:
أنشِئ مشروعًا جديدًا على Google Cloud Console أو اختَر مشروعًا حاليًا لاستخدامه. مع حزمة SDK للمستهلكين. انتظر بضع دقائق حتى المشروع الجديد مرئيًا على Google Cloud Console.
من أجل تشغيل التطبيق التجريبي، يجب أن يمتلك مشروعك إذن الوصول إلى حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". لأجهزة Android. في Google Cloud Console، اختَر واجهات برمجة التطبيقات الخدمات > المكتبة، ثم ابحث عن حزمة تطوير البرامج (SDK) للخرائط وفعّلها في Android
احصل على مفتاح واجهة برمجة تطبيقات للمشروع من خلال النقر واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد > إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات. لمزيد من المعلومات حول الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على الحصول على مفتاح واجهة برمجة التطبيقات
إضافة حزمة تطوير البرامج (SDK) للمستهلكين إلى تطبيقك
تتوفّر "حزمة تطوير البرامج (SDK) للمستهلكين" من خلال مستودع Maven خاص. تشير رسالة الأشكال البيانية يتضمّن المستودع ملفات نموذج كائن المشروع (pom.) في حزمة تطوير البرامج (SDK) ومستندات Javadocs. لإضافة حزمة تطوير البرامج (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
للإصدار المطلوب من حزمة تطوير البرامج (SDK) الخاصة بالمستهلكGradle
أضِف ما يلي إلى
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER' }
Maven
أضِف ما يلي إلى
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-consumer</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
تعتمد حزمة تطوير البرامج (SDK) الخاصة بالمستهلك على حزمة تطوير البرامج (SDK) للخرائط. يتم تكوين هذه التبعية في بطريقة تتيح لم يتم تحديد إصدار حزمة تطوير البرامج (SDK) للخرائط بشكل صريح في ملف تهيئة الإصدار كما يلي، عند طرح إصدار جديد من الخرائط تم إصدار حزمة SDK للمستهلكين، ستستمر حزمة SDK للمستهلكين في استخدام الحد الأدنى إصدار حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" والمطلوب بواسطته.
Gradle
أضِف ما يلي إلى
build.gradle
:dependencies { ... implementation 'com.google.android.gms:play-services-maps:18.1.0' }
Maven
أضِف ما يلي إلى
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.gms</groupId> <artifactId>play-services-maps</artifactId> <version>18.1.0</version> </dependency> </dependencies>
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
بعد إضافة حزمة تطوير البرامج (SDK) للمستهلكين إلى تطبيقك، أضِف مفتاح واجهة برمجة التطبيقات إلى تطبيقك. يجب عليك استخدام مفتاح واجهة برمجة تطبيقات المشروع الذي حصلت عليه عند لإعداد مشروع التطوير
يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات ليكون أكثر أمانًا.
التي يشير إليها تطبيقك. يجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في إصدارك.
نظام التحكم. يجب تخزينها في ملف local.properties
، وهو
الموجودة في الدليل الجذري لمشروعك. لمزيد من المعلومات عن
ملف local.properties
، عرض
ملفات خصائص Gradle:
لتبسيط هذه المهمة، يمكنك استخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android
لتثبيت المكوّن الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:
افتح ملف
build.gradle
على مستوى الجذر وأضِف الرمز التالي إلى العنصرdependencies
ضمن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") } }
افتح ملف
build.gradle
على مستوى التطبيق وأضِف الرمز التالي إلى العنصرplugins
Groovy
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
إذا كنت تستخدم "استوديو Android" مزامنة مشروعك مع Gradle
افتح
local.properties
في دليل مستوى المشروع، ثم أضِف العنصر الرمز التالي. استبدِل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>
إدراج عمليات تحديد المصدر المطلوبة في تطبيقك
إذا كنت تستخدم حزمة تطوير البرامج (SDK) للمستهلكين في تطبيقك، يجب تضمين نص تحديد المصدر وتراخيص البرامج المفتوحة المصدر كجزء من الإشعارات القانونية في تطبيقك . ومن الأفضل تضمين عمليات الإحالة كعنصر قائمة مستقل أو كجزء من عنصر القائمة لمحة.
يمكن العثور على معلومات التراخيص في "third_party_ Licenses.txt". تسجيل ملف AAR غير المؤرشف.
يُرجى الرجوع إلى https://developers.google.com/android/guides/opensource. حول كيفية تضمين إشعارات البرامج المفتوحة المصدر.
مصادقة حزمة تطوير البرامج (SDK) للمستهلك
توفر حزمة تطوير البرامج (SDK) الخاصة بالمستهلك المصادقة باستخدام الرموز المميزة للويب JSON. رمز JSON للويب (JWT) هو رمز دخول مستند إلى JSON يوفّر أو عدد أكبر من المطالبات على خدمةٍ ما. على سبيل المثال، يمكن للخادم إنشاء رمز مميز يحتوي على المطالبة "تم تسجيل الدخول كمشرف" وتوفير أن إلى العميل. ويمكن للعميل بعد ذلك استخدام هذا الرمز لإثبات أن تم تسجيل الدخول كمسؤول.
تستخدم حزمة تطوير البرامج (SDK) الخاصة بالمستهلك رمز JSON المميّز للويب الذي يوفّره التطبيق. على التواصل مع Fleet Engine. يُرجى الاطّلاع على مصادقة وتفويض مجموعة المركبات للحصول على مزيد من المعلومات.
يجب أن يشتمل الرمز المميّز للتفويض على مطالبة بقيمة tripid:TRIP_ID
في
عنوان authorization
، حيث يكون TRIP_ID
هو معرّف الرحلة. وهذا يمنح المستهلك
إذن وصول حزمة SDK إلى تفاصيل الرحلة، بما في ذلك موضع المركبة ومسارها والوقت المقدّر للوصول إليها
عمليات استدعاء الرمز المميّز للويب بتنسيق JSON
تسجِّل حزمة تطوير البرامج (SDK) الخاصة بالمستهلك معاودة الاتصال بالرمز المميز للتفويض مع التطبيق أثناء الإعداد. تستدعي حزمة SDK التطبيق للحصول على رمز مميز لجميع طلبات الشبكة التي تتطلب إذنًا.
ننصحك بشدة بمنح الإذن لذاكرة التخزين المؤقت لتنفيذ معاودة الاتصال
الرموز المميزة وإعادة تحميلها فقط عند انقضاء وقت expiry
. يجب أن تكون الرموز المميزة
يتم إصدارها لمدة ساعة واحدة.
يحدد معاودة الاتصال بالرمز المميز للتفويض الرمز المميز للخدمة المطلوب
لخدمة TripService
. وتوفِّر أيضًا tripId
المطلوبة.
للسياق.
يوضّح مثال الرمز التالي كيفية تطبيق تفويض الرمز المميز.
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
}
}
}
إعداد واجهة برمجة التطبيقات
قبل اتباع هذه الإجراءات، يفترض أنك قد مكنت والخدمات المناسبة وحزمة SDK للمستهلك.
الحصول على مثيل "ConsumerApi
"
لاستخدام حزمة تطوير البرامج (SDK) للمستهلكين، يجب إعداد تطبيقك
ConsumerApi
بشكل غير متزامن. واجهة برمجة التطبيقات أحادية اللون.
تستخدم طريقة الإعداد AuthTokenFactory
. يُنتج المصنع
رموز JWT المميزة للمستخدم عند الضرورة.
providerId
هو رقم تعريف المشروع الخاص بمشروعك على Google Cloud. يمكنك الاطّلاع على
دليل مستخدم Fleet Engine
لمزيد من المعلومات حول إنشاء المشروع.
يجب أن ينفِّذ تطبيقك AuthTokenFactory
كما هو موضّح في
مصادقة حزمة تطوير البرامج (SDK) للمستهلك
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
}
حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" وبرامج عرض الخرائط
يتوافق الإصدار 2.x.x من حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين مع حزمة تطوير البرامج (SDK) للخرائط للإصدار 18.1.0 والإصدارات الأحدث من نظام التشغيل Android. الجدول
أدناه يلخّص العارض التلقائي حسب إصدار حزمة تطوير البرامج (SDK) لـ "خرائط Google" وإمكانية الدعم
كلا العارضين. ومع ذلك، ننصحك باستخدام أحدث إصدار من العارض إذا كنت بحاجة إلى
لاستخدام العارض القديم، يمكنك عندئذٍ تحديده بوضوح باستخدام
MapsInitializer.initialize()
إصدار حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" | التوافق مع أحدث إصدار من العارض | دعم العارض القديم | العارض التلقائي |
---|---|---|---|
الإصدار 18.1.0 والإصدارات الأقدم | نعم | نعم | الإصدار القديم* |
V18.2.0 | نعم | نعم | الأحدث |
* مع طرح عارض الخرائط الجديد، سيتم ضبط "أحدث عارض" تلقائيًا.
إضافة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" كملحق
Gradle
أضِف ما يلي إلى build.gradle
:
dependencies {
//...
implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}
Maven
أضِف ما يلي إلى pom.xml
:
<dependencies>
...
<dependency>
<groupId>com.google.android.gms</groupId>
<artifactId>play-services-maps</artifactId>
<version>18.1.0</version>
</dependency>
</dependencies>
إعداد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" قبل إعداد حزمة تطوير البرامج (SDK) الخاصة بالمستهلك
يمكنك التواصل مع أحد أفراد الصف الدراسي "Activity
" في "Application
" أو بدء التشغيل.
MapsInitializer.initialize()
وانتظار ظهور نتيجة طلب العارض قبل الإعداد
حزمة 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()
}
})
}
إنشاء واجهة المستخدم
يمكنك استخدام إما ConsumerMapFragment
أو
ConsumerMapView
لإنشاء واجهة مستخدم
التطبيق. يتيح لك ConsumerMapFragment
تحديد
لخريطتك باستخدام
Fragment
بينما يتيح لك ConsumerMapView
استخدام
View
مشاركة الرحلات
الوظيفة هي نفسها في كل من ConsumerMapView
ConsumerMapFragment
، لذا يمكنك اختيار واحدة استنادًا إلى
سواء كانت View
أو
إنّ Fragment
أفضل لتطبيقك.
إتاحة استخدام عناصر واجهة برمجة التطبيقات 19 (KitKat) وVector القابل للرسم
إذا كان تصميم تطبيقك يتطلب دعمًا لأجهزة واجهة برمجة التطبيقات 19 (KitKat) والعناصر المتجهة للرسم،
عليك إضافة الرمز التالي إلى سجلّ "نشاطك". يمتد هذا الرمز
AppCompatActivity
لاستخدام
عناصر الرسومات المتجهة القابلة للرسم في حزمة تطوير البرامج (SDK) الخاصة بالمستهلك
Java
// ...
import android.support.v7.app.AppCompatActivity;
// ...
public class ConsumerTestActivity extends AppCompatActivity {
// ...
}
Kotlin
// ...
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()
.
.
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
ويمكن استخدام العرض إما في جزء أو في نشاط، كما هو محدد في ملف 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
فريق دعم (على التوالي)، بما أنّهما يوفّران
حق الوصول إلى دورة حياته.
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
في كسر هي نفسها في المثال أعلاه، لـ MapView
في
نشاط ما، باستثناء أن الجزء يتضخم التنسيق الذي يتضمن
MapView
في طريقة الجزء onCreateView()
.
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)
}
}
ضبط التكبير أو التصغير في الكاميرا للتركيز في رحلة
يعمل الزر "موقعي" التلقائي المُضمَّن في حزمة تطوير البرامج (SDK) للخرائط على تركيز الكاميرا على موقع الجهاز.
إذا كانت هناك جلسة "مشاركة الرحلة" نشطة، قد تحتاج إلى توسيط الكاميرا للتركيز على الرحلة بدلاً من موقع الجهاز.
حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين لنظام التشغيل Android المُدمَجة: Auto Camera
للسماح لك بالتركيز على الرحلة بدلاً من موقع الجهاز، توفر حزمة تطوير البرامج (SDK) الخاصة بالمستهلك ميزة "كاميرا تلقائية" مُفعَّلة تلقائيًا. يتم تكبير الكاميرا للتركيز على مسار مشاركة الرحلة نقطة طريق الرحلة التالية.
تخصيص سلوك الكاميرا
إذا كنت بحاجة إلى التحكّم بشكل أكبر في سلوك الكاميرا، يمكنك إيقافه أو تفعيله. كاميرا تلقائية باستخدام ConsumerController.setAutoCameraEnabled().
تعرض ConsumerController.getCameraUpdate() حدود الكاميرا المقترَحة في هذه اللحظة. يمكنك بعد ذلك تقديم CameraUpdate
كوسيطة إلى
GoogleMap.moveCamera() أو GoogleMap.animateCamera().
الوصول إلى الخرائط ومشاركة الرحلات
لدعم مشاركة الرحلات والتفاعل مع الخرائط في تطبيقك، يجب أن يكون لديك إذن بالوصول
إلى ConsumerGoogleMap
و
ConsumerController
ConsumerMapFragment
و
ConsumerMapView
تعرض كلتا النتيجتين بشكل غير متزامن
ConsumerGoogleMap
في ConsumerMapReadyCallback
.
يمكن إرجاع المشتريات مقابل ConsumerGoogleMap
.
ConsumerController
من getConsumerController()
. إِنْتَ
يمكنه الوصول إلى ConsumerGoogleMap
ConsumerController
على النحو التالي.
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
هي فئة تضمين لـ
صف واحد (GoogleMap
). وهي تزود تطبيقك بإمكانية تنفيذ ما يلي:
مع الخريطة باستخدام واجهة برمجة تطبيقات تعادل
GoogleMap
يسمح استخدام خريطة المستهلك للتطبيق والتنقّل
للتفاعل بسلاسة مع نفس خريطة Google الأساسية. على سبيل المثال:
يسمح النطاق GoogleMap
بتسجيل معاودة الاتصال مرة واحدة فقط، ولكن
يتيح ConsumerGoogleMap
عمليات معاودة الاتصال المسجَّلة المزدوجة.
تسمح عمليات معاودة الاتصال هذه لتطبيقك ومشاركة الرحلة بتسجيل عمليات معاودة الاتصال التي تكون
تسمى بشكل تسلسلي.
ConsumerController
يوفّر ConsumerController
إمكانية الوصول إلى وظائف مشاركة الرحلات، مثل
مثل مراقبة الرحلات والتحكم في حالتها وتحديد المواقع.
إعداد ميزة "مشاركة الرحلة"
بعد تطابق الخلفية مع مستهلك مع مركبة، استخدِم "JourneySharingSession
".
لبدء مشاركة الرحلة وواجهة المستخدم. تعرض ميزة "مشاركة الرحلة" النتائج المطابقة
وموقع المركبة ومسارها. بعد تنفيذ حزمة SDK في تطبيقك، يمكنك إضافة
وظائف مراقبة الرحلات، والاستماع إلى التحديثات، والتعامل مع الأخطاء.
تفترض الإجراءات التالية أن الخدمات الخلفية متاحة وأن
خدمات مطابقة المستهلكين مع المركبات.
يمكنك تسجيل أداة استماع إلى عنصر
TripModel
للحصول على تفاصيل حول الرحلة، مثل الوقت المقدّر للوصول والمسافة التي ينبغي أن تسافرها المركبة قبل الوصول.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?, ) { // ... } // ... })
ضبط رحلتك باستخدام "
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)
إيقاف مشاركة الرحلة
تأكَّد من إيقاف مشاركة الرحلة عند عدم الحاجة إليها، مثلاً عند إتلاف نشاط المضيف. يؤدي إيقاف مشاركة الرحلة أيضًا إلى إيقاف طلبات الشبكة إلى Fleet Engine ومنع تسرُّب الذاكرة.
يوضح الرمز النموذجي التالي كيفية إيقاف مشاركة الرحلة.
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()
}
}
التعامل مع أخطاء الرحلة
تعرِض الطريقة onTripRefreshError
الأخطاء التي تحدث أثناء تتبُّع الرحلة.
ربط حزمة SDK للمستهلكين
تتبع نفس إرشادات HTTP/RPC نفسها المحددة
Google Cloud Platform
تشمل الأخطاء الشائعة التي تظهر أثناء مراقبة الرحلة ما يلي:
HTTP | متوسط عائد النقرة | الوصف |
---|---|---|
400 | قيمة غير صالحة | حدّد العميل اسم رحلة غير صالح. تشير رسالة الأشكال البيانية
يجب أن يتّبع اسم الرحلة التنسيق
providers/{provider_id}/trips/{trip_id}
يجب أن يكون provider_id هو معرّف
مشروع Google Cloud المملوك من قِبل مقدم الخدمة |
401 | غير مصدَّق عليها | لم تتم مصادقة الطلب بسبب رمز JWT غير صالح. سيحدث هذا الخطأ إذا تم توقيع رمز JWT بدون رحلة أو انتهت صلاحية رمز JWT. |
403 | PERMISSION_DENIED | لا تتوفّر لدى العميل البيانات الكافية إذن. يحدث هذا الخطأ إذا كان JWT الرمز غير صالح، فلا يمتلك العميل أو لم يتم تفعيل واجهة برمجة التطبيقات بمشروع العميل. قد يكون رمز JWT المميز غير متوفّر أو يتم توقيع الرمز المميّز مع رحلة رقم تعريف لا يتطابق مع معرّف الرحلة المطلوب. |
429 | RESOURCE_EXHAUSTED | تصبح حصة الموارد صفرًا أو معدّل من الزيارات تتجاوز الحد المسموح به. |
503 | UNAVAILABLE | الخدمة غير متاحة. وعادةً ما يكون الخادم انخفضت. |
504 | DEADLINE_EXCEEDED | تجاوزت الموعد النهائي للطلب. سيؤدي هذا إلى لا تحدث إلا إذا حدد المتصل موعدًا نهائيًا وهو أقصر من القيمة الافتراضية للطريقة موعد نهائي (أي أنّ الموعد النهائي المطلوب غير بما يكفي للخادم لمعالجة الطلب) ولم ينتهِ الطلب في الموعد النهائي. |
لمزيد من المعلومات، يُرجى مراجعة معالجة خطأ حزمة SDK للمستهلك: