یک سفر را در اندروید دنبال کنید

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

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

قبل از اینکه شروع کنی

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

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

• شما یک نقشه برای برنامه خود تنظیم کرده‌اید .

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

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

به‌روزرسانی پیشرفت سفر

برای به‌روزرسانی جزئیات پیشرفت سفر، مانند مسافتی که وسیله نقلیه باید قبل از رسیدن طی کند و زمان تخمینی رسیدن، برنامه شما باید یک شنونده (listener) را همانطور که در مثال‌های زیر نشان داده شده است، ثبت و پیکربندی کند.

1. یک شنونده (listener) را روی یک شیء 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) {
         // ...
   }
   
   // ...
   });
   

   کاتلین

   // 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 شنونده (listener) سفر خود را پیکربندی کنید.

   جاوا

   // Set refresh interval to 2 seconds.
   TripModelOptions tripOptions =
         TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
   tripModel.setTripModelOptions(tripOptions);
   

   کاتلین

   // Set refresh interval to 2 seconds.
   val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
   tripModel.setTripModelOptions(tripOptions)
   

دنبال کردن یک سفر را متوقف کنید

مطمئن شوید که برنامه شما پس از یک سفر، زمانی که دیگر نیازی به آن نیست، متوقف می‌شود، مانند زمانی که سفر توسط راننده در backend به عنوان «کامل» علامت‌گذاری شده است. متوقف کردن اشتراک‌گذاری سفر، از درخواست‌های غیرضروری شبکه به 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 پیروی می‌کنند. برای تعاریف دقیق پیام‌های خطا و تمام کدهای خطا، به مستندات خطاهای Google Cloud مراجعه کنید.

در اینجا به برخی از خطاهای رایجی که ممکن است هنگام نظارت بر سفر رخ دهد، اشاره می‌کنیم:

مدیریت خطاهای SDK مصرف‌کننده

کیت توسعه نرم‌افزار مصرف‌کننده (Consumer SDK) با استفاده از مکانیزم فراخوانی، خطاهای به‌روزرسانی سفر را به برنامه مصرف‌کننده ارسال می‌کند. پارامتر فراخوانی، یک نوع بازگشتی مختص پلتفرم است ( TripUpdateError در اندروید و 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()
}

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

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

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

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

خطاهای کلاینت

کدهای وضعیت زیر مربوط به خطاهای کلاینت هستند و شما باید برای رفع آنها اقدام کنید. تا زمانی که اشتراک‌گذاری سفر را پایان ندهید، Consumer SDK به تلاش مجدد برای به‌روزرسانی سفر ادامه می‌دهد، اما تا زمانی که اقدامی نکنید، بازیابی نمی‌شود.