מעקב אחר נסיעה ב-Android

כשעוקבים אחרי נסיעה, מיקום הרכב הרלוונטי מוצג לצרכן באפליקציה לצרכן. כדי לעשות את זה, האפליקציה צריכה להתחיל לעקוב אחרי נסיעה, לעדכן את ההתקדמות בנסיעה ולהפסיק לעקוב אחרי נסיעה כשהיא מסתיימת.

במאמר הזה מוסבר איך התהליך הזה פועל.

לפני שמתחילים

חשוב לוודא שהגדרתם את הפריטים הבאים:

• שירותי ה-Backend של אפליקציית הצרכנים שלכם מוכנים, והשירותים שלכם להתאמת צרכנים לכלי רכב פועלים.

• הגדרתם מפה לאפליקציה.

התחלת מעקב אחרי נסיעה

כשהשרת העורפי מתאים בין צרכן לרכב, צריך להשתמש ב-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.

   Java

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

   Java

   // 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. הגדרות מפורטות של הודעות שגיאה וכל קודי השגיאה מופיעים במסמכי התיעוד של Google Cloud Errors.

ריכזנו כאן כמה שגיאות נפוצות שיכולות להתרחש במהלך מעקב אחר נסיעה:

טיפול בשגיאות ב-Consumer SDK

ערכת Consumer SDK שולחת שגיאות בעדכוני נסיעה לאפליקציית הצרכן באמצעות מנגנון של קריאה חוזרת (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()
}

הסבר על קודי סטטוס

קודי סטטוסים כוללים שני סוגים של שגיאות: שגיאות שקשורות לשרת ולרשת, ושגיאות בצד הלקוח.

שגיאות בחיבור לשרת ולרשת

קודי הסטטוס הבאים מציינים שגיאות ברשת או בשרת, ולא צריך לבצע פעולה כלשהי כדי לפתור אותן. ה-SDK לצרכנים מתאושש מהם באופן אוטומטי.

שגיאות בצד הלקוח

קודי הסטטוס הבאים הם שגיאות בצד הלקוח, וצריך לבצע פעולה כדי לפתור אותן. ערכת ה-SDK לצרכנים ממשיכה לנסות לרענן את הנסיעה עד שמפסיקים את שיתוף הנסיעה, אבל היא לא תפעל שוב עד שתבצעו פעולה.