متابعة رحلة على جهاز Android

اختيار النظام الأساسي: Android iOS JavaScript

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

يتناول هذا المستند كيفية عمل هذه العملية.

قبل البدء

تأكد من إعداد العناصر التالية:

• توفُّر خدمات الخلفية لتطبيقك المستهلِك، كما أنّ خدماتك لمطابقة المستهلكين مع المركبات.

• لقد أعددت خريطة لتطبيقك.

بدء متابعة رحلة

عندما يتطابق خادم الخلفية مع مستهلك مع مركبة، استخدِم JourneySharingSession لبدء متابعة الرحلة باستخدام مشاركة الرحلة.

يوضح الرمز النموذجي التالي كيفية بدء مشاركة الرحلة بعد عدد مرات المشاهدة.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Create a TripModel instance to listen for 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) {
        // ...
      }

      // ...
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create a TripModel instance to listen for 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?,
        ) {
          // ...
        }

      // ...
    })
  }

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

تعديل تقدُّم الرحلة

لتعديل تفاصيل تقدُّم الرحلة، مثل المسافة التي يجب أن قطعها المركبة السفر قبل الوصول والوقت المقدر للوصول، يجب على التطبيق تسجيل المستمع وإعداده كما هو موضح في الأمثلة التالية.

1. تسجيل أداة استماع على كائن 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?,
       ) {
         // ...
       }
   
     // ...
   })
   

2. ضبط خدمة المستمع لرحلتك باستخدام "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 وتمنع الذاكرة التسريبات.

يمكنك استخدام JourneySharingSession لإيقاف متابعة الرحلة كما هو موضّح في باتباع نموذج التعليمة البرمجية.

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 الأخطاء التي تحدث أثناء الرحلة. المراقبة. تتّبع رسائل الخطأ معيار الأخطاء في Google Cloud. للحصول على تفاصيل وتعريفات رسائل الخطأ وجميع رموز الأخطاء، يمكنك الرجوع إلى أخطاء Google Cloud ذات الصلة.

في ما يلي بعض الأخطاء الشائعة التي يمكن أن تحدث أثناء تتبُّع الرحلات:

HTTP	متوسط عائد النقرة	الوصف
400	قيمة غير صالحة	حدّد العميل اسم رحلة غير صالح. يجب أن يتّبع اسم الرحلة التنسيق providers/{provider_id}/trips/{trip_id}. تشير رسالة الأشكال البيانية يجب أن يكون provider_id هو معرّف مشروع Cloud الذي يملكه مقدم الخدمة.
401	غير مصدَّق عليها	يظهر لك هذا الخطأ إذا لم تكن هناك بيانات اعتماد مصادقة صالحة. على سبيل المثال، إذا تم توقيع رمز JWT المميز بدون معرّف الرحلة أو رمز JWT منتهي الصلاحية.
403	PERMISSION_DENIED	يظهر لك هذا الخطأ إذا لم يكن لدى العميل الإذن الكافي (على سبيل المثال، يحاول مستخدم لديه دور المستهلك استدعاء updateTrip)، إذا رمز JWT غير صالح، أو لم يتم تفعيل واجهة برمجة التطبيقات لمشروع العميل. قد يكون رمز JWT غير متوفّر أو قد يتم توقيع الرمز المميّز باستخدام معرّف رحلة لا يتطابق مع معرّف الرحلة المطلوب.
429	RESOURCE_EXHAUSTED	حصة الموارد هي صفر أو أن معدل الزيارات يتجاوز الحد.
503	UNAVAILABLE	الخدمة غير متاحة. يكون الخادم معطلاً في العادة.
504	DEADLINE_EXCEEDED	تجاوزت الموعد النهائي للطلب. لا يحدث هذا الخطأ إلا إذا ضبط المتصل موعد نهائي أقصر من الموعد النهائي الافتراضي للطريقة (أي الموعد النهائي المطلوب غير كافٍ لمعالجة الخادم للطلب) لم ينتهِ الطلب خلال الموعد النهائي.

التعامل مع أخطاء حِزم تطوير البرامج (SDK) للمستهلك

تُرسِل "حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين" الأخطاء المتعلّقة بتعديل الرحلات إلى تطبيق المستهلك باستخدام معاودة الاتصال. الآلية. معلمة رد الاتصال هي نوع إرجاع خاص بالنظام الأساسي ( TripUpdateError على Android، NSError على iOS).

استخراج رموز الحالة

عادةً ما تكون الأخطاء التي يتم تمريرها إلى معاودة الاتصال أخطاء gRPC، ويمكنك أيضًا واستخراج المعلومات الإضافية منها في شكل رمز حالة. بالنسبة إلى قائمة كاملة برموز الحالة، فراجع رموز الحالة واستخدامها في gRPC

Java

يمكنك استخراج رمز حالة gRPC يوفر تفاصيل حول الخطأ من TripUpdateError تم إرجاعه من onTripUpdateError().

// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
  Status.Code code = error.getStatusCode();
}

Kotlin

يمكنك استخراج رمز حالة gRPC يوفر تفاصيل حول الخطأ من TripUpdateError تم إرجاعه من onTripUpdateError().

// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
  val code = error.getStatusCode()
}

تفسير رموز الحالة

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

أخطاء في الخادم والشبكة

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

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

أخطاء العميل

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

رمز الحالة	الوصف
قيمة غير صالحة	استخدم تطبيق المستهلك اسم رحلة غير صالح. يجب أن يكون اسم الرحلة اتبع التنسيق providers/{provider_id}/trips/{trip_id}.
NOT_FOUND	لم يتم إنشاء الرحلة مطلقًا.
PERMISSION_DENIED	أذونات تطبيق المستهلك غير كافية. يحدث هذا الخطأ في الحالات التالية: لا يملك تطبيق المستهلك أذونات لم يتم تفعيل حزمة تطوير البرامج (SDK) الخاصة بالمستهلك للمشروع في Google Cloud. وحدة التحكم. رمز JWT المميز إما مفقود أو غير صالح. يتم توقيع رمز JWT باستخدام معرّف رحلة لا يتطابق مع طلب الرحلة.
RESOURCE_EXHAUSTED	تصبح حصة الموارد صفرًا، أو أن معدل تدفق الزيارات يتجاوز حد السرعة.
غير مصدَّق عليها	تعذّرت مصادقة الطلب بسبب رمز JWT المميز غير الصالح. هذا النمط عندما يتم توقيع رمز JWT المميز بدون معرّف الرحلة عند انتهاء صلاحية رمز JWT المميز.