بدء استخدام SDK Driver لنظام التشغيل Android

يمكنك استخدام "حزمة تطوير البرامج (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:

  1. أنشِئ مشروعًا جديدًا على Google Cloud Console أو اختَر مشروعًا حاليًا لاستخدامه. باستخدام Driver SDK. انتظر بضع دقائق حتى المشروع الجديد مرئيًا على Google Cloud Console.

  2. من أجل تشغيل التطبيق التجريبي، يجب أن يمتلك مشروعك إذن الوصول إلى حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". لأجهزة Android. في Google Cloud Console، اختَر واجهات برمجة التطبيقات الخدمات > المكتبة، ثم ابحث عن حزمة تطوير البرامج (SDK) للخرائط وفعّلها في Android

  3. احصل على مفتاح واجهة برمجة تطبيقات للمشروع من خلال النقر واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد > إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات. لمزيد من المعلومات حول الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على الحصول على مفتاح واجهة برمجة التطبيقات

إضافة حزمة تطوير البرامج (SDK) لبرنامج التشغيل إلى تطبيقك

تتوفّر حزمة Driver SDK في مستودع Google Maven. تشير رسالة الأشكال البيانية يتضمّن المستودع ملفات نموذج كائن المشروع (pom.) في حزمة تطوير البرامج (SDK) ومستندات Javadocs. لإضافة حزمة تطوير البرامج (SDK) لبرنامج التشغيل إلى تطبيقك، يُرجى اتّباع الخطوات التالية:

  1. أضِف التبعية التالية إلى إعداد 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>
    
  2. تعتمد حزمة تطوير البرامج (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

لتثبيت المكوّن الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:

  1. افتح ملف build.gradle على مستوى الجذر وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

    رائع

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

    Kotlin

    buildscript {
        dependencies {
            // ...
            classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
        }
    }
    
  2. افتح ملف build.gradle على مستوى التطبيق وأضِف الرمز التالي إلى العنصر plugins

    رائع

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

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. إذا كنت تستخدم "استوديو Android" مزامنة مشروعك مع Gradle

  4. افتح local.properties في دليل مستوى المشروع، ثم أضِف العنصر الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك.

    MAPS_API_KEY=YOUR_API_KEY
    
  5. في ملف 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:

  1. الحصول على كائن 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
        }
      },
    )
    
  2. أنشِئ عنصر 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()
    
  3. استخدِم الكائن DriverContext لإعداد *DriverApi.

    Java

    RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
    

    Kotlin

    val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
    
  4. يمكنك الحصول على 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.