يمكنك استخدام "حزمة تطوير البرامج (SDK) لبرنامج التشغيل" لتوفير ميزتَي التنقّل والتتبُّع المحسّنَين. إلى تطبيق Trip and Order Progress توفّر حزمة تطوير البرامج (SDK) لبرنامج التشغيل موقع السيارة وتحديثات المهام الخاصة بمحرك حل الرحلات عند الطلب وعمليات التسليم.
تُبقي "حزمة تطوير البرامج (SDK) لبرنامج التشغيل" على علم بخدمات Fleet Engine والخدمات المخصّصة.
لموقع المركبة وحالتها على سبيل المثال، يمكن أن تكون المركبة ONLINE
.
أو OFFLINE
ويتغير الموقع الجغرافي للمركبة مع تقدُّم الرحلة.
الحد الأدنى لمتطلبات النظام
يجب أن يعمل الجهاز الجوّال بنظام التشغيل Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) أو مستوى أحدث.
تكوين الإصدار والتبعيات
يتوفّر الإصدار 4.99 والإصدارات الأحدث من حزمة تطوير البرامج (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) لبرنامج التشغيل، يجب أن يستهدف تطبيقك
الإصدار 23 من minSdkVersion
أو الإصدارات الأحدث
لتشغيل تطبيق تم إنشاؤه باستخدام Driver SDK، يمكن لنظام التشغيل يجب أن يتضمّن الجهاز خدمات Google Play مثبت.
إعداد مشروع التطوير
لإعداد مشروع التطوير والحصول على مفتاح واجهة برمجة التطبيقات للمشروع على Google Cloud Console:
أنشِئ مشروعًا جديدًا على Google Cloud Console أو اختَر مشروعًا حاليًا لاستخدامه. باستخدام Driver SDK. انتظر بضع دقائق حتى المشروع الجديد مرئيًا على Google Cloud Console.
من أجل تشغيل التطبيق التجريبي، يجب أن يمتلك مشروعك إذن الوصول إلى حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". لأجهزة Android. في Google Cloud Console، اختَر واجهات برمجة التطبيقات الخدمات > المكتبة، ثم ابحث عن حزمة تطوير البرامج (SDK) للخرائط وفعّلها في Android
احصل على مفتاح واجهة برمجة تطبيقات للمشروع من خلال النقر واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد > إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات. لمزيد من المعلومات حول الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على الحصول على مفتاح واجهة برمجة التطبيقات
إضافة حزمة تطوير البرامج (SDK) لبرنامج التشغيل إلى تطبيقك
تتوفّر حزمة Driver SDK في مستودع Google Maven. تشير رسالة الأشكال البيانية يتضمّن المستودع ملفات نموذج كائن المشروع (pom.) في حزمة تطوير البرامج (SDK) ومستندات Javadocs. لإضافة حزمة تطوير البرامج (SDK) لبرنامج التشغيل إلى تطبيقك، يُرجى اتّباع الخطوات التالية:
أضِف التبعية التالية إلى إعداد Gradle أو Maven، واستبدِل العنصر النائب
VERSION_NUMBER
للإصدار المطلوب من حزمة Driver SDK.Gradle
أضِف ما يلي إلى
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER' }
Maven
أضِف ما يلي إلى
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-driver</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
تعتمد حزمة تطوير البرامج (SDK) لبرنامج التشغيل على حزمة تطوير البرامج (SDK) للتنقّل، ويتم ضبط هذه التبعية في الطريقة التي إذا كانت هناك حاجة إلى إصدار معين من حزمة SDK للتنقل، بشكل صريح في ملف إعداد الإصدار كما يلي: سيؤدي حذف مجموعة الرموز المذكورة إلى تمكين المشروع من التنزيل دائمًا أحدث إصدار من حزمة SDK للتنقل ضمن إصدار الإصدار الرئيسي. تجدر الإشارة إلى أنّ السلوكيات المجمّعة لأحدث إصدارات Driver SDK وقد خضعت حزمة SDK للتنقل لاختبارات صارمة قبل إصدارها.
ترتيب إعدادات التبعية لعملية التطوير والإصدار البيئات وفقًا لذلك.
Gradle
أضِف ما يلي إلى
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
أضِف ما يلي إلى
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>5.0.0</version> </dependency> </dependencies>
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
بعد إضافة حزمة Driver 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.driverapidemo">
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_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. حول كيفية تضمين إشعارات البرامج المفتوحة المصدر.
التبعيات
إذا كنت تستخدم ProGuard لإجراء ما يلي: لتحسين الإصدارات، قد تحتاج إلى إضافة الأسطر التالية إلى ProGuard ملف الإعداد:
-dontwarn com.google.**
-dontwarn okio.**
الحد الأدنى لمستوى واجهة برمجة التطبيقات المتوافق هو 23.
جارٍ إعداد حزمة SDK
يكون رقم تعريف مقدّم الخدمة (عادةً ما يكون رقم تعريف مشروع Google Cloud) مطلوبًا من أجل
لإعداد كائن DriverContext
. لمزيد من التفاصيل حول إعداد
مشروع Google Cloud، يُرجى الاطّلاع على
المصادقة والتفويض.
قبل استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل، عليك أولاً إعداد حزمة SDK للتنقل. لإعداد حزمة SDK:
الحصول على كائن
Navigator
منNavigationApi
.Java
NavigationApi.getNavigator( this, // Activity new NavigationApi.NavigatorListener() { @Override public void onNavigatorReady(Navigator navigator) { // Keep a reference to the Navigator (used to configure and start nav) this.navigator = navigator; } } );
Kotlin
NavigationApi.getNavigator( this, // Activity object : NavigatorListener() { override fun onNavigatorReady(navigator: Navigator) { // Keep a reference to the Navigator (used to configure and start nav) this@myActivity.navigator = navigator } }, )
أنشِئ عنصر
DriverContext
، مع تعبئة الحقول المطلوبة.Java
DriverContext driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider( NavigationApi.getRoadSnappedLocationProvider(application)) .build();
Kotlin
val driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application)) .build()
استخدِم الكائن
DriverContext
لإعداد*DriverApi
.Java
RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
Kotlin
val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
يمكنك الحصول على
RidesharingVehicleReporter
من كائن واجهة برمجة التطبيقات. (تمتد*VehicleReporter
إلىNavigationVehicleReporter
.)Java
RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
Kotlin
val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
المصادقة مع AuthTokenFactory
عندما تنشئ حزمة تطوير البرامج (SDK) لبرنامج التشغيل تحديثات الموقع الجغرافي،
يجب أن يرسل هذه التحديثات إلى
خادم Fleet Engine. ومن أجل مصادقة هذه الطلبات،
سيتم الاتصال بحزمة تطوير البرامج (SDK) لبرنامج التشغيل مع الطلب الذي قدّمه المتصل.
مثيل لـ AuthTokenFactory
.
المصنع مسؤول عن إنشاء رموز المصادقة المميزة في الموقع
وقت التحديث.
وستكون الطريقة التي يتم بها إنشاء الرموز المميزة بالضبط خاصة بحالة كل مطوّر. مع ذلك، قد تحتاج عملية التنفيذ إلى:
- جلب رمز مصادقة مميز، ربما بتنسيق JSON، من خادم HTTPS
- تحليل الرمز المميز وتخزينه مؤقتًا
- إعادة تحميل الرمز المميّز عند انتهاء صلاحيته
للحصول على تفاصيل الرموز المميّزة التي يتوقعها خادم Fleet Engine، يُرجى الاطّلاع على إنشاء رمز JSON المميّز للويب (JWT) للتفويض:
في ما يلي شرح أساسي لـ AuthTokenFactory
:
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private String token; // initially null
private long expiryTimeMs = 0;
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
@Override
public String getToken(AuthTokenContext authTokenContext) {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId());
}
return token;
}
private void fetchNewToken(String vehicleId) {
String url =
new Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token = obj.get("Token").getAsString();
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 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000;
} catch (IOException e) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw new RuntimeException("Could not get auth token", e);
}
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: String = ""
private var expiryTimeMs: Long = 0
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
override fun getToken(context: AuthTokenContext): String {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId())
}
return token
}
fun fetchNewToken(vehicleId: String) {
val url =
Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token = obj.get("ServiceToken").getAsString()
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 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000
}
} catch (e: IOException) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw RuntimeException("Could not get auth token", e)
}
}
}
يستخدم هذا التنفيذ تحديدًا عميل Java HTTP المضمن لجلب رمز مميز بتنسيق JSON من خادم مصادقة المطوِّر. الرمز المميز هو لإعادة استخدامها. تتم إعادة استرجاع الرمز المميّز إذا كان الرمز القديم في غضون 10 دقائق. وقت انتهاء صلاحيته
قد تختلف آلية التنفيذ لديك، مثل استخدام سلسلة محادثات في الخلفية. لتحديث الرموز المميزة.
سيتم التعامل مع الاستثناءات في AuthTokenFactory
كاستثناءات مؤقتة ما لم تحدث.
بشكل متكرر. بعد عدد من المحاولات، قرّرَت حزمة تطوير البرامج (SDK) لبرنامج التشغيل
أن القيمة
خطأ نهائي وسيتوقف عن محاولة إرسال التحديثات.
الإبلاغ عن الحالة والأخطاء في "StatusListener
"
نظرًا لأن حزمة تطوير البرامج (SDK) لبرنامج التشغيل تنفّذ إجراءات في
الخلفية، يمكنك استخدام StatusListener
لتشغيل الإشعارات عند التأكّد
الأحداث، مثل الأخطاء أو التحذيرات أو رسائل تصحيح الأخطاء. قد تكون الأخطاء
عابر بطبيعة الحال (مثل BACKEND_CONNECTIVITY_ERROR
)، أو قد
إلى إيقاف تحديثات الموقع الجغرافي نهائيًا (مثل VEHICLE_NOT_FOUND
أو
إلى خطأ في التهيئة).
يتم تقديم عملية تنفيذ StatusListener
اختيارية على النحو التالي:
Java
class MyStatusListener implements StatusListener {
/** Called when background status is updated, during actions such as location reporting. */
@Override
public void updateStatus(
StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Kotlin
class MyStatusListener : StatusListener() {
/** Called when background status is updated, during actions such as location reporting. */
override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
ملاحظات حول طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS)
داخليًا، يستخدم تنفيذ حزمة تطوير البرامج (SDK) لبرنامج التشغيل
طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS) للاتصال الآمن
مع خادم Fleet Engine. الإصدارات الأقدم من Android (الإصدار 19 أو
أقل) قد تتطلب رمز تصحيح SecurityProvider
حتى يتسنى لك الاتصال بـ
الخادم. من المفترض أن يظهر هذا
المقالة
لمزيد من المعلومات حول استخدام طبقة المقابس الآمنة (SSL) في Android. تتضمّن المقالة أيضًا
يحتوي على عيّنات تعليمات برمجية لتصحيح بيانات موفّر خدمة الأمان.
جارٍ تفعيل تحديثات الموقع الجغرافي
بعد تفعيل مثيل "*VehicleReporter
"، ستكون ميزة تفعيل تعديلات الموقع الجغرافي مفعّلة.
مباشر:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
يتم إرسال إشعارات الموقع الجغرافي على فترات زمنية منتظمة عندما تكون حالة المركبة هي
ONLINE
يُرجى ملاحظة أنّ الاتصال بالرقم reporter.enableLocationTracking()
غير متاح
يتم تلقائيًا ضبط حالة المركبة على ONLINE
. يجب
ضبط حالة المركبة بشكل صريح
بشكل افتراضي، يبلغ الفاصل الزمني لإعداد التقارير 10 ثوانٍ. يمكن للفاصل الزمني لإعداد التقارير أن
مع reporter.setLocationReportingInterval(long, TimeUnit)
. تشير رسالة الأشكال البيانية
الحد الأدنى للفاصل الزمني للتحديث هو 5 ثوانٍ. قد يتم إجراء تحديثات أكثر تكرارًا
تؤدي إلى إبطاء الطلبات والأخطاء.
جارٍ إيقاف تحديثات الموقع الجغرافي
عند انتهاء وردية السائق، يمكن إيقاف تحديثات الموقع الجغرافي
تم وضع علامة على مركبة غير متصلة بالإنترنت من خلال إجراء مكالمة
DeliveryVehicleReporter.disableLocationTracking
أو
RidesharingVehicleReporter.disableLocationTracking
ستؤدي هذه المكالمة إلى جدولة تحديث نهائي واحد للتسليم الفوري، يشير إلى أنّ المركبة غير متصلة بالإنترنت. لن يحتوي هذا التحديث على معلومات الموقع.
ضبط حالة المركبة
عند تفعيل تعديلات الموقع الجغرافي، سيؤدي ضبط حالة المركبة على ONLINE
إلى:
إتاحة المركبة لطلبات البحث عن SearchVehicles
وبالمثل، فإن وضع علامة
المركبة على أنّها OFFLINE
ستضع علامة على المركبة على أنّها غير متوفّرة.
يتوفّر لك خيار ضبط حالة المركبة على جانب الخادم (يُرجى الاطّلاع على المقالة تحديث). مركبة) أو مباشرةً في Driver SDK:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
عند تفعيل تحديثات الموقع الجغرافي، سيتم نشر مكالمة إلى setVehicleState
في
تحديث الموقع التالي.
سيؤدي وضع علامة ONLINE
على مركبة في حال عدم تفعيل ميزة "تتبُّع الموقع الجغرافي" إلى ذلك.
في IllegalStateException
. يمكن وضع علامة "OFFLINE
" على مركبة في الحالات التالية:
لم يتم تفعيل ميزة تتبُّع الموقع الجغرافي أو إيقافها بشكلٍ صريح. سيؤدي هذا إلى
في تحديث فوري. مكالمة إلى
الإجراء الذي سينفّذه RidesharingVehicleReporter.disableLocationTracking()
هو
ضبط حالة المركبة على OFFLINE
يُرجى العِلم أنّ setVehicleState
يمكن إرجاعه على الفور، وسيتم إجراء التعديلات على
سلسلة محادثات تحديث الموقع الجغرافي تشبه عملية معالجة الأخطاء في تحديثات المواقع الجغرافية والأخطاء
يتم نشر تعديل حالة المركبة باستخدام
تم ضبط StatusListener
في DriverContext
.