הפעלת פיד נתונים מפורט

פיד נתונים של מסלול מפורט מספק מידע ניווט בלבד למכשירים שלא מיועדים לפעול לפי הנחיות ניווט מבוססות-מפה. היא כוללת תמרונים עתידיים עם רכיבים שאתם מספקים:

  • סמלים (שמאלה, ימינה, סיבוב פרסה)
  • הופכים מספרים בכיכרות
  • שמות של כבישים
  • המרחקים המשוערים והזמן המשוער עד לשלב הבא בניווט או ליעד הסופי

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

כדי להשתמש ב-SDK, יש ליצור שירות ולרשום אותו ב-Navigation SDK ל-Android, כך שיוכל לקבל פרטי ניווט חדשים בזמן אמת (בערך פעם שנייה במהלך הניווט).

במסמך הזה נסביר איך ליצור ולרשום שירות ניווט שמקבל פרטי ניווט מה-SDK ומספק את מצב הניווט למכשיר המקבל.

סקירה כללית

בקטע הזה נסביר איך להוסיף את הספרייה TurnByTurn לפרויקטים שלכם, ומסכמים את התהליך הכללי לבניית פונקציונליות של מסלול מפורט.

כדי לצרוך גרסה עצמאית של ספריית TurnByTurn, צריך לבצע את הפעולות הבאות:

  1. מגדירים את הסביבה כדי לגשת למאגר Maven המארח, כפי שמתואר במאמר תחילת העבודה עם ה-SDK של Drive במסמכי התיעוד בנושא נסיעות והזמנה.

  2. מוסיפים את התלות הבאה להגדרות של Maven או Gradle:

    Maven

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.maps</groupId>
    <artifactId>google_turnbyturn</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

    Gradle

    dependencies {
  ...
  implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
}

מוסיפים את ספריית TurnByTurn לפרויקט באמצעות קובץ JAR שהורדתם (חלופה)

ספריית TurnByTurn זמינה כקובץ JAR בתיקיית ה-SDK הזו. אם אין לכם גישה, פנו לנציג שלכם.

  1. מורידים את הקובץ google_turnbyturn_*.jar ומחלצים אותו.
  2. מעתיקים את קובץ ה-JAR שהורדתם אל ספריית app/libs של הפרויקט.

  3. כדי לכלול את ה-JAR ב-build, צריך להוסיף את הערכים הבאים ל-build.gradle.

    dependencies {
   ...
   api fileTree(include: ['*.jar'], dir: 'libs')
}

שימוש בספרייה TurnByTurn

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

  1. יוצרים שירות כדי לקבל עדכוני ניווט.

  2. רושמים את השירות.

  3. הסבר על מצבי הניווט

  4. דוגמה לתצוגת ניווט שמציגה את הרכיבים החיוניים.

יצירת שירות כדי לקבל עדכוני ניווט {#service}

ה-SDK של הניווט קשור לשירות TurnByTurn ושולח לו עדכוני ניווט באמצעות Android Messenger. תוכלו ליצור שירות ניווט חדש לעדכונים האלה, או להשתמש בשירות קיים.

היתרון של קבלת עדכוני ניווט בשירות הוא שהשירות יכול להתקיים בתהליך נפרד ברקע.

השירות בדוגמה הבאה מקבל פרטי ניווט ומשתמש ב-TurnByTurnManager כדי להמיר את הנתונים לאובייקט NavInfo שמכיל את פרטי הניווט.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

קודים של הודעות

ניתן לזהות הודעות NavInfo באמצעות השדה Message.what במחלקה Message, שמוגדר לערך TurnByTurnManager.MSG_NAV_INFO.

רישום השירות לעדכוני ניווט {#register}

קטעי הקוד הבאים רושמים את שירות הניווט.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

הפעלה ועצירה של השירות

שירות הניווט פעיל כל עוד ה-SDK של הניווט קשור אליו. אפשר לבצע קריאה ידנית אל startService() ואל stopService() כדי לשלוט במחזור החיים של שירות הניווט, אבל כשרושמים את השירות ב-Navigation SDK, השירות מתחיל באופן אוטומטי ומפסיק רק כשמבטלים את הרישום. בהתאם לאופן שבו מגדירים את האפליקציה, יכול להיות שתרצו להפעיל שירות שפועל בחזית, כפי שמתואר בסקירה הכללית על השירותים במסמכי התיעוד של Android.

ביטול הרישום של השירות

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

navigator.unregisterServiceForNavUpdates();

הסבר על מצבי הניווט {#states}

משתמשים ב-NavInfo.getNavState() כדי לקבל את מצב הניווט הנוכחי, שהוא אחד מהמצבים הבאים:

  • Enroute – המצב ENROUTE מציין שהניווט המודרך פעיל כרגע והמשתמש נמצא במסלול שצוין. יש מידע על השלב הנוכחי בתמרון.

  • ניתוב מחדש – REROUTING המשמעות היא שהניווט מתבצע אבל הניווט מחפש מסלול חדש. שלב התמרון הקרוב לא זמין, כי עדיין אין מסלול חדש. באפליקציה לדוגמה תופיע ההודעה "ניתוב מחדש..." במסך פרטי הניווט. אחרי שנמצא מסלול, נשלחת הודעת NavInfo עם המצב ENROUTE.

  • נעצר – STOPPED המשמעות היא שהניווט הסתיים. לדוגמה, הניווט מפסיק כשהמשתמש יוצא מהניווט באפליקציה. באפליקציה לדוגמה, מצב STOPPED מנקה את תצוגת פרטי הניווט כדי למנוע הצגה של ההוראות לשלבים.

אכלוס של תצוגת הפיד

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

מסך של נייד שבו מוצגת פנייה שמאלה קרובה בעוד 30 מטר אל W Ahvanee Ave. בתחתית המסך, הזמן שנותר עד ליעד הוא 46 דקות והמרחק שנותר הוא 59 ק&quot;מ.

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

בטבלה הזו מוצגים השדות לפרטי הניווט והמקומות שבהם הם מוצגים.

השדות לכל שלב בניווט שדות לנסיעה הכוללת
נמצא בStepInfo נמצא בNavInfo
השם המלא של הכביש הזמן שנותר
סמל התמרון מרחק ליעד
המרחק לשלב הבא
שדות הנחייה בין נתיבים

הנחייה בין נתיבים

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

דוגמה להגדרה של הנחייה בין נתיבים.

הכיוון המומלץ שנהג צריך לנסוע בנתיב מסומן בשדה isRecommended (מומלץ).

דוגמה להנחייה בין נתיבים

הקטע הבא מדגים את ייצוג הנתונים של הנתיבים המוצגים למעלה.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

יצירת סמלים לתמרונים

התו Maneuver מגדיר כל תמרון אפשרי שיכול להתרחש בזמן הניווט, ואפשר לקבל את התמרון עבור שלב נתון מ-method StepInfo.getManeuver().

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

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

אפשר להרחיב כדי לראות דוגמאות לסמלים שונים לתמרונים שונים

סמל לדוגמה תמרוני TurnByTurn
DEPART
UNKNOWN
STRAIGHT
ON_RAMP_UNSPECIFIED
OFF_RAMP_UNSPECIFIED
NAME_CHANGE
TURN_RIGHT
ON_RAMP_RIGHT
TURN_LEFT
ON_RAMP_LEFT
TURN_SLIGHT_RIGHT
ON_RAMP_SLIGHT_RIGHT
OFF_RAMP_SLIGHT_RIGHT
TURN_SLIGHT_LEFT
ON_RAMP_SLIGHT_LEFT
OFF_RAMP_SLIGHT_LEFT
TURN_SHARP_RIGHT
ON_RAMP_SHARP_RIGHT
OFF_RAMP_SHARP_RIGHT
TURN_SHARP_LEFT
ON_RAMP_SHARP_LEFT
OFF_RAMP_SHARP_LEFT
TURN_U_TURN_COUNTERCLOCKWISE
ON_RAMP_U_TURN_COUNTERCLOCKWISE
OFF_RAMP_U_TURN_COUNTERCLOCKWISE
TURN_U_TURN_CLOCKWISE
ON_RAMP_U_TURN_CLOCKWISE
OFF_RAMP_U_TURN_CLOCKWISE
ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_RIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
ROUNDABOUT_STRAIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
ROUNDABOUT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_LEFT_CLOCKWISE
ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_LEFT_CLOCKWISE
ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
ROUNDABOUT_U_TURN_CLOCKWISE
ROUNDABOUT_COUNTERCLOCKWISE
ROUNDABOUT_CLOCKWISE
ROUNDABOUT_EXIT_COUNTERCLOCKWISE
ROUNDABOUT_EXIT_CLOCKWISE
MERGE_RIGHT
OFF_RAMP_RIGHT
MERGE_LEFT
OFF_RAMP_LEFT
FORK_RIGHT
TURN_KEEP_RIGHT
ON_RAMP_KEEP_RIGHT
OFF_RAMP_KEEP_RIGHT
FORK_LEFT
TURN_KEEP_LEFT
ON_RAMP_KEEP_LEFT
OFF_RAMP_KEEP_LEFT
MERGE_UNSPECIFIED
DESTINATION
DESTINATION_RIGHT
DESTINATION_LEFT
FERRY_BOAT
FERRY_TRAIN

שימוש בסמלים שנוצרו

רשימה קטנה של סמלים שנוצרו על ידי ה-SDK של הניווט.

כדי להקל על תרחישים לדוגמה של Android Auto, ערכת הניווט ב-SDK תומכת ביצירת סמלים של תמרון והנחיה בין נתיבים. הסמלים האלה מתאימים להנחיות של מידות התמונה שזמינות בספריית האפליקציות לרכב ל-Android Auto, שמומלץ לטרגט תיבה עם הפרדה של 500 x 74 dp. למידע נוסף, אפשר לעיין ב-setsLaneImage וב-CarIcon במסמכי התיעוד של Android.

דוגמה ליצירת סמלים

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

אחרי שמפעילים את יצירת הסמלים, האובייקט StepInfo TurnbyTurn מאכלס את הסמלים maneuverBitmap ו-lanesBitmap.

המאמרים הבאים