دنبال کردن سفر در Android

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

این سند نحوه عملکرد این فرایند را پوشش می‌دهد.

قبل‌از شروع

مطمئن شوید موارد زیر را راه‌اندازی کرده‌اید:

• سرویس‌های پسین برای برنامه مصرف‌کننده شما آماده است و سرویس‌های شما برای مطابقت دادن مصرف‌کنندگان با خودروها عملیاتی است.

• نقشه‌ای برای برنامه‌تان راه‌اندازی کرده‌اید.

شروع دنبال کردن سفر

وقتی سرور زیرینه شما مصرف‌کننده را با خودرویی مطابقت می‌دهد، از 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();
    }
  }
}

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

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

رسیدگی به خطاهای سفر

روش onTripRefreshError خطاهایی را که درطول پایش سفر رخ می‌دهد نشان می‌دهد. پیام‌های خطا از استاندارد Google Cloud Error پیروی می‌کنند. برای مشاهده تعاریف دقیق پیام‌های خطا و همه کدهای خطا، به سند خطاهای Google Cloud مراجعه کنید.

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

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

«کیت توسعه نرم‌افزار مصرف‌کننده» خطاهای به‌روزرسانی سفر را بااستفاده از سازوکار فراخوانی برگشتی به برنامه مصرف‌کننده ارسال می‌کند. پارامتر callback یک نوع پاسخ مختص پلاتفرم است ( TripUpdateError در Android، و NSError در iOS).

استخراج کدهای وضعیت

خطاهای ارسال‌شده به فراخوان برگشتی معمولاً خطاهای gRPC هستند و همچنین می‌توانید اطلاعات بیشتری را به‌صورت کد وضعیت از آن‌ها استخراج کنید. برای فهرست کامل کدهای وضعیت، به کدهای وضعیت و کاربرد آن‌ها در gRPC مراجعه کنید.

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

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

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

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

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

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

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

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