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

בחירת פלטפורמה: Android iOS JavaScript

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

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

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

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

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

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

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

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

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

Java

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.

   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, כמו שמוצג בקוד לדוגמה הבא.

Java

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	הכנסה לקליק	תיאור
400	INVALID_ARGUMENT	הלקוח ציין שם נסיעה לא חוקי. שם הנסיעה חייב להיות בפורמט providers/{provider_id}/trips/{trip_id}. הערך של provider_id חייב להיות המזהה של הפרויקט ב-Cloud שבבעלות ספק השירות.
401	UNAUTHENTICATED	השגיאה הזו מופיעה אם אין פרטי כניסה תקפים לאימות. לדוגמה, אם אסימון ה-JWT חתום ללא מזהה נסיעה או אם תוקף אסימון ה-JWT פג.
403	PERMISSION_DENIED	השגיאה הזו מתקבלת אם ללקוח אין הרשאה מספקת (לדוגמה, אם משתמש עם תפקיד צרכן מנסה להתקשר אל updateTrip), אם אסימון ה-JWT לא תקין או אם ה-API לא מופעל בפרויקט של הלקוח. יכול להיות שאסימון ה-JWT חסר או שהאסימון חתום עם מזהה נסיעה שלא תואם למזהה הנסיעה המבוקש.
429	RESOURCE_EXHAUSTED	המכסה של המשאב היא אפס או שקצב התנועה חורג מהמגבלה.
503	UNAVAILABLE	השירות לא זמין. בדרך כלל השרת מושבת.
504	DEADLINE_EXCEEDED	המועד האחרון לשליחת הבקשה חלף. השגיאה הזו מתרחשת רק אם המתקשר מגדיר מועד אחרון שהוא קצר יותר מהמועד האחרון שמוגדר כברירת מחדל לשיטה (כלומר, המועד האחרון שנדרש לא מספיק לשרת כדי לעבד את הבקשה), והבקשה לא הסתיימה לפני המועד האחרון.

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

ה-SDK לצרכנים שולח שגיאות בעדכוני נסיעות לאפליקציה למשתמשים באמצעות מנגנון של קריאה חוזרת (callback). פרמטר הקריאה החוזרת הוא סוג החזרה ספציפי לפלטפורמה (‎ TripUpdateError‎ ב-Android ו-‎ NSError‎ ב-iOS).

חילוץ קודי סטטוס

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

Java

אפשר לחלץ קוד סטטוס של 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()
}

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

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

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

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

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

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

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

קוד סטטוס	תיאור
INVALID_ARGUMENT	באפליקציה למשתמשים צוין שם נסיעה לא תקין. שם הנסיעה חייב להיות בפורמט providers/{provider_id}/trips/{trip_id}.
NOT_FOUND	הנסיעה לא נוצרה.
PERMISSION_DENIED	לאפליקציה למשתמשים אין מספיק הרשאות. השגיאה הזו מתרחשת במקרים הבאים: לאפליקציה למשתמשים אין הרשאות ה-SDK לצרכנים לא מופעל בפרויקט במסוף Google Cloud. אסימון ה-JWT חסר או לא תקין. אסימון ה-JWT חתום עם מזהה נסיעה שלא תואם לנסיעה המבוקשת.
RESOURCE_EXHAUSTED	מכסת המשאבים היא אפס, או שקצב זרימת התנועה חורג ממגבלת המהירות.
UNAUTHENTICATED	האימות של הבקשה נכשל בגלל אסימון JWT לא תקין. השגיאה הזו מתרחשת כשאסימון ה-JWT נחתם ללא מזהה נסיעה, או כשתוקף אסימון ה-JWT פג.