يتوفّر Last Mile Fleet Solution حاليًا لعملاء محدّدين فقط. يمكنك التواصل مع فريق المبيعات لمعرفة المزيد من المعلومات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

ملاحظة: توفّر إمكانية LMFS نموذجَين أمنيَين للاستخدام مع حزمة تطوير البرامج (SDK) لبرنامج التشغيل: موثوق بها وموثوق بها. كلا النوعين من الأمان تحدد نماذج السائق الطرق التي قد يوفر بها تطبيق السائق تحديثات بيانات المركبة إلى Fleet المحرك. يوفّر نموذج الأمان غير الموثوق به طبقة إضافية من البيانات. التحقق من تطبيق السائق. وفي النموذج غير الموثوق به، تشير يمكن لتطبيق السائق إرسال إشعارات حول الموقع الجغرافي للمركبة فقط إلى مجموعة المركبات مباشرةً. المحرك. يجب إجراء جميع التعديلات الأخرى لبيانات المركبات الواردة من تطبيق سائق غير موثوق به: إرسالها إلى الواجهة الخلفية للعميل، والتي تنقل البيانات إلى Fleet Engine.

يسمح النموذج الأمني الموثوق به لتطبيق السائق بإرسال بيانات المركبة. يتم تحديثها مباشرةً إلى Fleet Engine، بدون الحاجة إلى وسيط خدمة ما. تتضمن هذه البيانات إنشاء وتحديث المركبات والمهام ويتوقفون.

أمّا النموذج غير الموثوق به فهو يتوفّر بشكلٍ عام، في حين أنّ نموذج السائق الموثوق به متاح بشكلٍ عام. في المعاينة لمزيد من المعلومات حول طراز السائق الموثوق، يُرجى الاطّلاع على الأدوار الأخرى لحساب الخدمة:

الحد الأدنى لمتطلبات النظام

يجب أن يعمل الجهاز الجوّال بنظام التشغيل 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) لبرنامج التشغيل، يجب أن يستهدف تطبيقك minSdkVersion. 23 أو أعلى. لمزيد من المعلومات، يُرجى مراجعة ملاحظات الإصدار:

لتشغيل تطبيق تم إنشاؤه باستخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل، يجب أن يكون لدى جهاز Android خدمات Google Play مثبت.

إعداد مشروع التطوير

لإعداد مشروع التطوير والحصول على مفتاح واجهة برمجة التطبيقات للمشروع على Google Cloud Console:

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

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

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

أضِف التبعية التالية إلى إعدادات Gradle أو Maven، استبدال العنصر النائب VERSION_NUMBER بالإصدار المحدد من حزمة تطوير البرامج (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.driver</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 اتبع هذا الإجراء لتثبيت المكوّن الإضافي Secrets Gradle والتخزين الآمن مفتاح واجهة برمجة التطبيقات الخاص بك.

افتح ملف 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")
    }
}

افتح ملف build.gradle على مستوى التطبيق وأضِف الرمز التالي إلى العنصر plugins

رائع

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

Kotlin

id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")

مزامنة مشروعك مع 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. حول كيفية تضمين إشعارات البرامج المفتوحة المصدر.

التبعيات

تستخدم حزمة تطوير البرامج (SDK) لبرنامج التشغيل gRPC إلى الاتصال بخادم Fleet Engine. إذا لم يسبق لك استخدام gRPC، يمكنك الإفصاح عن التبعيات التالية:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

وبدون هذه التبعيات، قد لا تتوفر حزمة SDK لبرنامج التشغيل حدوث أخطاء أثناء وقت التشغيل أثناء محاولة الاتصال بخادم Fleet Engine.

إذا كنت تستخدم ProGuard لإجراء ما يلي: لتحسين الإصدارات، قد تحتاج إلى إضافة الأسطر التالية إلى ProGuard ملف الإعداد:

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

الحد الأدنى لمستوى واجهة برمجة التطبيقات المتوافق هو 23.

إعداد حزمة تطوير البرامج (SDK)

يجب إدخال رقم تعريف مزوِّد (عادةً ما يكون رقم تعريف مشروع Google Cloud) من أجل لإعداد كائن DriverContext. لمزيد من التفاصيل حول إعداد مشروع Google Cloud، يُرجى الاطّلاع على المصادقة والتفويض.

قبل استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل، عليك أولاً إعداد حزمة SDK للتنقل. لإعداد حزمة SDK:

الحصول على كائن Navigator من NavigationApi.

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;
      }
    }
);

أنشِئ عنصر DriverContext، مع تعبئة الحقول المطلوبة.

DriverContext driverContext = DriverContext.builder(application)
    .setProviderId(providerId)
    .setVehicleId(vehicleId)
    .setAuthTokenFactory(authTokenFactory)
    .setNavigator(navigator)
    .setRoadSnappedLocationProvider(
        NavigationApi.getRoadSnappedLocationProvider(application))
    .build();

استخدِم الكائن DriverContext لإعداد *DriverApi.

DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);

يمكنك الحصول على DeliveryVehicleReporter من كائن واجهة برمجة التطبيقات. (تمتد DeliveryVehicleReporter إلى NavigationVehicleReporter.)
```
DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
```

المصادقة مع `AuthTokenFactory`

عندما تنشئ حزمة تطوير البرامج (SDK) لبرنامج التشغيل تحديثات الموقع الجغرافي، يجب أن يرسل هذه التحديثات إلى خادم Fleet Engine. لمصادقة هذه الطلبات، يجب استدعاء "حزمة تطوير البرامج (SDK) لبرنامج التشغيل" إلى مكالمة يوفّرها المتصل مثيل لـ AuthTokenFactory. المصنع مسؤول عن إنشاء رموز المصادقة المميزة في الموقع وقت التحديث.

وتعتمد كيفية إنشاء الرموز المميزة بدقة على حالة كل مطور. مع ذلك، من المحتمل أن تحتاج عملية التنفيذ إلى:

جلب رمز مصادقة مميز، ربما بتنسيق JSON، من خادم HTTPS
تحليل الرمز المميز وتخزينه مؤقتًا
إعادة تحميل الرمز المميّز عند انتهاء صلاحيته

للحصول على تفاصيل الرموز المميّزة التي يتوقعها خادم Fleet Engine، يُرجى الاطّلاع على إنشاء رمز JSON المميّز للويب (JWT) للتفويض:

في ما يلي شرح أساسي لـ AuthTokenFactory:

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // initially null
  private long expiryTimeMs = 0;
  private String vehicleId;

  // 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) {
    String vehicleId = requireNonNull(context.getVehicleId());

    if (System.currentTimeMillis() > expiryTimeMs || !vehicleId.equals(this.vehicleId)) {
      // The token has expired, go get a new one.
      fetchNewToken(vehicleId);
    }

    return vehicleServiceToken;
  }

  private void fetchNewToken(String vehicleId) {
    String url = "https://yourauthserver.example/token/" + vehicleId;

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      vehicleServiceToken = obj.get("VehicleServiceToken").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;
      this.vehicleId = vehicleId;
    } 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);
    }
  }
}

يستخدم هذا التنفيذ تحديدًا عميل Java HTTP المضمن لجلب رمز مميز بتنسيق JSON من خادم مصادقة المطوِّر. الرمز المميز هو لإعادة استخدامها. تتم إعادة استرجاع الرمز المميّز إذا كان الرمز القديم في غضون 10 دقائق. وقت انتهاء صلاحيته

قد تختلف آلية التنفيذ لديك، مثل استخدام سلسلة محادثات في الخلفية. لتحديث الرموز المميزة.

يتم التعامل مع الاستثناءات في AuthTokenFactory على أنّها مؤقتة ما لم تحدث بشكل متكرر. بعد عدد من المحاولات، قرّرَت حزمة تطوير البرامج (SDK) لبرنامج التشغيل أن الخطأ دائم ويتوقف عن محاولة إرسال التحديثات.

الإبلاغ عن الحالة والأخطاء في "`StatusListener`"

نظرًا لأن حزمة تطوير البرامج (SDK) لبرنامج التشغيل تنفّذ إجراءات في الخلفية، يمكنك استخدام StatusListener لتفعيل الإشعارات عند التأكّد الأحداث، مثل الأخطاء أو التحذيرات أو رسائل تصحيح الأخطاء. قد تكون الأخطاء عابر بطبيعة الحال (مثل BACKEND_CONNECTIVITY_ERROR)، أو قد إلى إيقاف تحديثات الموقع الجغرافي نهائيًا (مثل VEHICLE_NOT_FOUND أو إلى خطأ في التهيئة).

يتم تقديم عملية تنفيذ StatusListener اختيارية على النحو التالي:

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.
  }
}

ملاحظات حول طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS)

داخليًا، يستخدم تنفيذ حزمة تطوير البرامج (SDK) لبرنامج التشغيل SSL/TLS للاتصال بخادم Fleet Engine بأمان. الإصدارات الأقدم من نظام التشغيل Android (إصدار واجهة برمجة التطبيقات 23 أو سابقًا) قد تتطلب رمز تصحيح SecurityProvider للتواصل مع الخادم. لمزيد من المعلومات حول استخدام طبقة المقابس الآمنة (SSL) في Android، راجع موفّر "خدمات Google للأجهزة الجوّالة" (GMS) للأمان تحتوي المقالة أيضًا على عيّنات تعليمات برمجية لتصحيح إعدادات موفِّر الأمان.

تفعيل تحديثات الموقع الجغرافي

بعد تفعيل مثيل "*VehicleReporter"، ستكون ميزة تفعيل تعديلات الموقع الجغرافي مفعّلة. مباشر:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

يتم إرسال تحديثات الموقع الجغرافي على فترات زمنية منتظمة، إن أمكن. كل موقع جغرافي تحديث إلى أن المركبة متصلة بالإنترنت.

بشكل افتراضي، يبلغ الفاصل الزمني لإعداد التقارير 10 ثوانٍ. يمكنك تغيير التقارير فاصل زمني مع reporter.setLocationReportingInterval(long, TimeUnit). تشير رسالة الأشكال البيانية الحد الأدنى للفاصل الزمني للتحديث هو 5 ثوانٍ. قد يتم إجراء تحديثات أكثر تكرارًا تؤدي إلى إبطاء الطلبات والأخطاء.

إيقاف تحديثات الموقع الجغرافي

عند انتهاء وردية السائق، يمكنك إيقاف تعديلات الموقع الجغرافي من خلال الاتصال DeliveryVehicleReporter.disableLocationTracking

حالات استخدام النماذج الموثوقة

يوضِّح هذا القسم كيفية استخدام حزمة Driver SDK لتنفيذ حالات الاستخدام الشائعة. عند استخدام النموذج الموثوق به.

إنشاء مركبة

يمكنك إنشاء مركبة من حزمة Driver SDK.

قبل إنشاء مركبة، تأكد من إعداد Delivery Driver API يجب إنشاء رقم تعريف المركبة مع استخدام رقم تعريف المركبة ومقدّم الخدمة المستخدَم. أثناء إعداد حزمة تطوير البرامج (SDK) لبرنامج التشغيل. بعد ذلك، أنشئ المركبة على النحو الموضّح. في المثال التالي:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

إنشاء مهمة استلام الشحنة

يمكنك إنشاء مهمة استلام الشحنة من "حزمة تطوير البرامج (SDK) لبرنامج التشغيل".

قبل إنشاء مهمة، تأكد من إعداد Delivery Driver API يجب إنشاء المهمة باستخدام رقم تعريف الموفّر المحدد في Driver SDK. التهيئة. بعد ذلك، أنشِئ مهمة استلام الشحنة على النحو الموضّح في ما يلي: مثال. للحصول على معلومات حول معرّفات المهام، يُرجى الاطّلاع على أمثلة على معرّفات المهام.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_PICKUP)
   .build();

try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

إنشاء مهمة تسليم شحنة

يمكنك إنشاء مهمة تسليم شحنة من "حزمة تطوير البرامج (SDK) لبرنامج التشغيل".

قبل إنشاء مهمة، تأكد من إعداد Delivery Driver API بعد ذلك، أنشِئ مهمة تسليم الشحنة على النحو الموضّح في المثال التالي. للحصول على معلومات حول معرّفات المهام، يُرجى الاطّلاع على أمثلة على معرّفات المهمة

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

عدم التوفّر المجدوَل

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

قبل إنشاء مهمة، تأكد من إعداد Delivery Driver API بعد ذلك، أنشئ مهمة "عدم التوفّر" كما هو موضّح في المثال التالي. للحصول على معلومات حول معرّفات المهام، يُرجى الاطّلاع على أمثلة على معرّفات المهمة

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
   .setTaskType(TaskType.UNAVAILABLE)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

محطّات توقّف مجدولة

يمكنك إنشاء مهمة إيقاف مجدوَلة إما من حزمة تطوير البرامج (SDK) لبرنامج التشغيل. جدول إيقاف المهمة رقم تعريف تتبع.

قبل إنشاء مهمة، تأكد من إعداد Delivery Driver API بعد ذلك، أنشئ مهمة الإيقاف المُجدوَلة كما هو موضّح في المثال التالي. للحصول على معلومات حول معرّفات المهام، يُرجى الاطّلاع على أمثلة على معرّفات المهمة

    static final String TASK_ID = "task-8241890"; //  Avoid auto-incrementing IDs.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
    CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
       .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
       .setTaskDurationSeconds(2 * 60)
       .setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
       .build();
    try {
       DeliveryTask task = taskManager.createTask(request).get();
       // Handle CreateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle CreateTaskRequest error.
    }

تعديل ترتيب المهام

يمكنك تحديث ترتيب تنفيذ المهام المعينة لمركبة من SDK لبرنامج التشغيل.

يؤدي تحديث ترتيب المهام أيضًا إلى تعيين المهام لمركبة إذا لم تكن المخصصة سابقًا لمركبة. كما أنه يغلق المهام التي كانت المخصصة لمركبة ما واستبعادها من الطلب المحدث. تعيين مهمة إلى مركبة مختلفة إذا تم تعيينها سابقًا لمركبة أخرى حدوث خطأ في المركبة. قبل تعيين مهمة للمركبة الجديدة، أغلِق المهمة الحالية ثم إنشاء مهمة جديدة.

يمكنك تعديل ترتيب المهام في أي وقت.

قبل تحديث طلب المهمة لمركبة، تأكد من أن المركبة التي تم إنشاؤها بالفعل في Fleet Engine. ثم تحديث ترتيب المهمة للمركبة كما هو موضح في المثال التالي.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    try {
       List<VehicleStop> stops = reporter.setVehicleStops(
         ImmutableList.of(
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.ARRIVED)
                 .setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
                 .setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
                 .setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
                 .setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW)
                 .setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
                 .setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
                 .build())).get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
       // errors.
    }

قد يحدث استثناء قد يمنع التحديث إلى الحالة الداخلية لحزمة تطوير البرامج (SDK) لبرنامج التشغيل. فإذا حدث ذلك، قم بحل المشكلة ثم يجب الاتصال بـ setVehicleStops مرة أخرى حتى تتم المكالمة بنجاح.

يمكن أن تشمل المشاكل المحتملة ما يلي:

إنّ نقاط إيقاف السيارة المحدّدة لا تتّبع نمطًا صالحًا. الأولى فقط يمكن أن تكون حالة السيارة في أي من حالات إيقاف المركبات: NEW أو ENROUTE أو ARRIVED. يجب أن تكون "محطات إيقاف المركبات" بعد المحطة الحالية في "حالة إيقاف السيارة" الجديدة.
إنّ المهام غير متوفّرة أو أنّها تنتمي إلى مركبة مختلفة.
المركبة غير موجودة.

مركبة في طريقها إلى المحطة التالية

يجب إرسال إشعار إلى مجموعة المركبات عندما تغادر مركبة من المحطة، وعندها بدء التنقل. يمكنك إشعار Fleet Engine من خلال حزمة Driver SDK.

قبل إبلاغ Fleet Engine بانطلاق مركبة من المحطة، تأكد من محطات المركبة وإعدادها. بعد ذلك، أبلغ Fleet Engine مغادرة مركبة كما هو موضح في المثال التالي.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // Create Vehicle, VehicleStops, and DeliveryTasks.
    // Set VehicleStops on Vehicle.

    navigator.setDestination(vehicleStop.getWaypoint());
    try {
       List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
       // VehicleStop updated to ENROUTE state.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

قد يحدث استثناء قد يمنع تحديث حزمة Driver SDK الحالة الداخلية. وفي حال حدوث ذلك، يُرجى حل المشكلة ثم الاتصال enrouteToNextStop مرة أخرى إلى أن تتم عملية النقل بنجاح.

يمكن أن تشمل المشاكل المحتملة ما يلي:

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

وصول مركبة إلى محطة

يجب إرسال إشعار إلى مجموعة المركبات عند وصول مركبة إلى محطة. يمكنك إخطار Fleet Engine من Driver SDK.

قبل إبلاغ Fleet Engine بوصول مركبة إلى محطة معيّنة، تأكد من تم تحديد محطّات توقّف للمركبة. بعد ذلك، أبلغ Fleet Engine بوصول المركبة. في المحطة كما هو موضح في المثال التالي.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.

try {
   List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ARRIVED state.
   navigator.clearDestinations();
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

قد يحدث استثناء قد يمنع إجراء تحديث للإصدار الداخلي لحزمة تطوير البرامج (SDK) لبرنامج التشغيل الولاية. وفي حال حدوث ذلك، يجب حلّ المشكلة ثم الاتصال بالرقم arrivedAtStop مرة أخرى. إلى أن يتم تحقيق النجاح.

قد تشمل المشاكل المحتملة ما يلي:

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

تكمل مركبة محطة

يجب إعلام Fleet Engine عند اكتمال توقّف أي مركبة. هذا الإشعار يؤدي إلى ضبط جميع المهام المرتبطة بالمحطة على حالة "مغلق". يمكنك إخطار Fleet Engine من Driver SDK.

إرسال إشعار إلى فريق Fleet Engine بأنّ المركبة قد أكملت عملية إيقاف السيارة على النحو الموضّح في المثال التالي.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // After completing the tasks at the VehicleStop, remove it from the
    // the current list of VehicleStops.

    try {
       List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
       // Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
       // Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

قد يحدث استثناء قد يمنع إجراء تحديث للإصدار الداخلي لحزمة تطوير البرامج (SDK) لبرنامج التشغيل الولاية. وفي حال حدوث ذلك، يجب حلّ المشكلة ثم الاتصال بالرقم completedStop مرة أخرى. إلى أن يتم تحقيق النجاح.

يمكن أن تشمل المشاكل المحتملة ما يلي:

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

إغلاق مهمة

لإغلاق مهمة تم تعيينها لمركبة، ينبغي إما إعلام Fleet Engine أن المركبة قد أكملت المحطة التي تحدث فيها المهمة، أو إزالتها من قائمة محطات توقّف المركبات للقيام بذلك، يمكنك تعيين قائمة تتوقف المركبة المتبقية كما هو الحال عندما تعديل ترتيب المهام لمركبة

إذا لم يتم تعيين مركبة لإحدى المهام بعد، وينبغي إغلاقها، فقم بتحديث مهمة إلى حالة "مغلق". ومع ذلك، لا يمكنك إعادة فتح مهمة تم إغلاقها.

لا يشير إغلاق المهمة إلى النجاح أو الفشل. يشير إلى أن المهمة لم يعد قيد التنفيذ. لتتبع الشحن، من المهم تشير إلى النتيجة الفعلية للمهمة بحيث يمكن عرض نتيجة التسليم.

يجب تعيين مهمة لمركبة لتتمكّن من استخدام "حزمة تطوير البرامج (SDK) للسائق" لإغلاق المهمة. لإغلاق مهمة تم تعيينها لمركبة، يُرجى إرسال إشعار محرك الأسطول أن تكون المركبة قد أكملت المحطة التي تتم فيها المهمة.

بدلاً من ذلك، يمكنك تعديل ترتيب المهام للمركبة. التي تم إسناد المهمة إليها، ثم أزِل المهمة من قائمة التوقف.

تحديد نتيجة المهمة وموقع النتيجة

لا يشير إغلاق المهمة إلى النجاح أو الفشل. يشير إلى أن المهمة لم يعد قيد التنفيذ. لتتبع الشحن، من المهم تشير إلى النتيجة الفعلية للمهمة بحيث يمكن عرض نتيجة التسليم، وبالتالي وجود فوترة مناسبة للخدمات. بمجرد تعيينها، لا يمكنك تغيير لنتائج المهمة. ولكن يمكنك تعديل وقت نتيجة المهمة وموقع نتيجة المهمة بعد تعيينها.

يمكن ضبط نتائج المهام في الحالة "مغلقة" على إما "تم بنجاح" أو "تعذّر الإجراء". يتقاضى Fleet Engine مهام التسليم فقط بالحالة تم بنجاح.

عند وضع علامة على نتيجة مهمة، يملأ Fleet Engine تلقائيًا موقع نتيجة المهمة مع آخر موقع معروف للمركبة. يمكنك إلغاء هذا السلوك.

يوضِّح لك المثال التالي كيفية استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل لتحديد نتيجة مَهمّة. والطابع الزمني. لا يمكنك ضبط موقع نتيجة المهمة باستخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل.

    static final String TASK_ID = "task-8241890";

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();

    // Updating an existing DeliveryTask which is already CLOSED. Manually
    // setting TaskOutcomeLocation with Driver SDK is not supported at this time.
    UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
        .setTaskOutcome(TaskOutcome.SUCCEEDED)
        .setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
        .build();

    try {
       DeliveryTask updatedTask = taskManager.updateTask(req);
       // Handle UpdateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle UpdateTaskRequest error.
    }

البحث عن مركبة

يمكنك البحث عن مركبة من خلال حزمة تطوير البرامج (SDK) الخاصة بالسائق. قبل البحث عن مركبة، والتأكد من أنك إعداد Delivery Driver API يمكنك بعد ذلك البحث عن المركبة كما هو موضح في المثال التالي.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
    try {
       DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
       // Handle GetVehicleRequest DeliveryVehicle response.
    } catch (Exception e)  {
       // Handle GetVehicleRequest error.
    }

بإمكان DeliveryVehicleManager البحث فقط عن DeliveryVehicle لمعرّف المركبة الذي تم تقديمه أثناء إعداد Delivery Driver API.

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

الحد الأدنى لمتطلبات النظام

تكوين الإصدار والتبعيات

Gradle

Maven

إعدادات المشروع

إعداد مشروع التطوير

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

Gradle

Maven

Gradle

Maven

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

رائع

Kotlin

رائع

Kotlin

إدراج عمليات تحديد المصدر المطلوبة في تطبيقك

التبعيات

إعداد حزمة تطوير البرامج (SDK)

المصادقة مع AuthTokenFactory

الإبلاغ عن الحالة والأخطاء في "StatusListener"

ملاحظات حول طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS)

تفعيل تحديثات الموقع الجغرافي

إيقاف تحديثات الموقع الجغرافي

حالات استخدام النماذج الموثوقة

إنشاء مركبة

إنشاء مهمة استلام الشحنة

إنشاء مهمة تسليم شحنة

عدم التوفّر المجدوَل

محطّات توقّف مجدولة

تعديل ترتيب المهام

مركبة في طريقها إلى المحطة التالية

وصول مركبة إلى محطة

تكمل مركبة محطة

إغلاق مهمة

تحديد نتيجة المهمة وموقع النتيجة

البحث عن مركبة

المصادقة مع `AuthTokenFactory`

الإبلاغ عن الحالة والأخطاء في "`StatusListener`"