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

پلتفرم را انتخاب کنید: 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();
    }
  }
}

کاتلین 

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) {
      // ...
}

// ...
});

    کاتلین

    // 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);

    کاتلین 

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

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

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

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

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

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

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

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

خطاهای ارسال شده به callback معمولاً خطاهای 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();
}

کاتلین

شما می توانید یک کد وضعیت gRPC را استخراج کنید که جزئیات مربوط به خطا را از TripUpdateError برگردانده شده از onTripUpdateError() ارائه می دهد. 

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

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

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

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

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

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

خطاهای مشتری

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

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