دنبال کردن سفر در 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 پیروی می‌کنند. برای مشاهده تعاریف دقیق پیام‌های خطا و همه کدهای خطا، به اسناد خطاهای Google Cloud مراجعه کنید.

در اینجا برخی‌از خطاهای رایجی که ممکن است درطول پایش سفر رخ دهد آورده شده است:

HTTP	RPC	شرح
۴۰۰	INVALID_ARGUMENT	کارخواه نام سفر نامعتبری را مشخص کرده است. نام سفر باید از قالب providers/{provider_id}/trips/{trip_id} پیروی کند. provider_id باید شناسه پروژه Cloud متعلق به ارائه‌دهنده خدمات باشد.
401	اصالت‌سنجی‌نشده	اگر اطلاعات اعتباری اصالت‌سنجی معتبری وجود نداشته باشد، این خطا را دریافت می‌کنید. برای مثال، اگر نشان JWT بدون شناسه سفر امضا شده باشد یا نشان JWT منقضی شده باشد.
403	PERMISSION_DENIED	اگر مشتری اجازه کافی نداشته باشد (برای مثال، کاربری با نقش مصرف‌کننده سعی کند updateTrip را فراخوانی کند)، اگر نشان JWT نامعتبر باشد، یا اگر API برای پروژه مشتری فعال نباشد، این خطا را دریافت می‌کنید. ممکن است کد JWT وجود نداشته باشد یا کد با شناسه سفری امضا شده باشد که با شناسه سفر درخواست‌شده مطابقت ندارد.
429	RESOURCE_EXHAUSTED	سهمیه منبع صفر است یا نرخ ترافیک از حد مجاز فراتر رفته است.
۵۰۳	دردسترس نیست	سرویس دردسترس نیست. معمولاً سرور ازکار افتاده است.
504	DEADLINE_EXCEEDED	مهلت درخواست تمام شد. این خطا فقط زمانی رخ می‌دهد که تماس‌گیرنده مهلتی را تعیین کند که کوتاه‌تر از مهلت پیش‌فرض روش باشد (یعنی مهلت درخواست‌شده برای پردازش درخواست توسط سرور کافی نباشد) و درخواست در مهلت مقرر تکمیل نشود.

رسیدگی به خطاهای کیت توسعه نرم‌افزار مصرف‌کننده

«کیت توسعه نرم‌افزار مصرف‌کننده» خطاهای به‌روزرسانی سفر را بااستفاده از سازوکار بازخوانی به برنامه مصرف‌کننده ارسال می‌کند. پارامتر callback نوع پاسخ مختص پلاتفرم است ( 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()
}

تفسیر کدهای وضعیت

کدهای وضعیت دو نوع خطا را پوشش می‌دهند: خطاهای مربوط به سرور و شبکه، و خطاهای سمت کارخواه.

خطاهای سرور و شبکه

کدهای وضعیت زیر مربوط به خطاهای شبکه یا سرور است و برای رفع آن‌ها نیازی به انجام هیچ اقدامی ندارید. «کیت توسعه نرم‌افزار مصرف‌کننده» به‌طور خودکار از این خطاها بازیابی می‌کند.

رمز وضعیت	شرح
لغو شد	سرور ارسال پاسخ را متوقف کرد. این مشکل معمولاً به‌دلیل مشکل سرور رخ می‌دهد.
لغو شد	سرور پاسخ خروجی را خاتمه داد. این معمولاً زمانی اتفاق می‌افتد که برنامه به پس‌زمینه ارسال می‌شود، یا زمانی که تغییری در وضعیت برنامه «مصرف‌کننده» رخ می‌دهد.
قطع‌شده
DEADLINE_EXCEEDED	پاسخ دادن سرور خیلی طول کشید.
دردسترس نیست	سرور دردسترس نبود. این مشکل معمولاً به‌دلیل مشکل شبکه رخ می‌دهد.

خطاهای کارخواه

کدهای وضعیت زیر مربوط به خطاهای کارخواه است و باید برای رفع آن‌ها اقدام کنید. «کیت توسعه نرم‌افزار مصرف‌کننده» تا زمانی که هم‌رسانی سفر را پایان دهید، به تلاش مجدد برای بازآوری سفر ادامه می‌دهد، اما تا زمانی که اقدامی انجام ندهید، بازیابی نخواهد شد.

رمز وضعیت	شرح
INVALID_ARGUMENT	برنامه «مصرف‌کننده» نام سفر نامعتبری را مشخص کرده است؛ نام سفر باید از قالب providers/{provider_id}/trips/{trip_id} پیروی کند.
NOT_FOUND	سفر هرگز ایجاد نشد.
PERMISSION_DENIED	برنامه «مصرف‌کننده» اجازه‌های کافی ندارد. این خطا در موارد زیر رخ می‌دهد: برنامه «مصرف‌کننده» اجازه ندارد «کیت توسعه نرم‌افزار مصرف‌کننده» برای پروژه در «کنسول Google Cloud» فعال نشده است. کد JWT وجود ندارد یا نامعتبر است. نشان JWT با شناسه سفری امضا شده است که با سفر درخواستی مطابقت ندارد.
RESOURCE_EXHAUSTED	سهمیه منبع صفر است یا نرخ جریان ترافیک از حد مجاز سرعت فراتر رفته است.
اصالت‌سنجی‌نشده	درخواست به‌دلیل نامعتبر بودن نمودار اصالت‌سنجی ناموفق بود. این خطا زمانی رخ می‌دهد که کد JWT بدون شناسه سفر امضا شده باشد، یا زمانی که کد JWT منقضی شده باشد.