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

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

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

يوضّح هذا المستند طريقة عمل هذه العملية.

قبل البدء

يُرجى التأكّد من إعداد ما يلي:

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

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

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

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

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

جافا

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

   جافا

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

   جافا

   // 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 لإيقاف تتبُّع الرحلة كما هو موضّح في نموذج الرمز البرمجي التالي.

جافا

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

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

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

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

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

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

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

جافا

يمكنك استخراج رمز حالة 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) المخصّصة للمستهلك تلقائيًا من هذه الأخطاء.

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

أخطاء في تطبيق العميل

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

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