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

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

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

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

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

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

סקירה כללית

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

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

  1. מגדירים את הסביבה כדי לגשת למאגר Maven המארח:

    Maven

    מוסיפים לקובץ pom.xml את הנתונים הבאים:

        <project>
      ...
      <repositories>
        <repository>
          <id>google-maven-repository</id>
          <url>https://maven.google.com</url>
        </repository>
      </repositories>
      ...
    </project>

    Gradle

    מוסיפים לקובץ build.gradle את הנתונים הבאים:

    repositories {
    ...
    google()
}
  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')
}

שימוש בספרייה של 'הוראות ניווט'

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

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

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

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

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

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

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

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

השירות בדוגמה הבאה מקבל מידע על ניווט ומשתמש ב-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.

רישום השירות לעדכוני ניווט

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

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

הפעלה והפסקה של השירות

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

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

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

navigator.unregisterServiceForNavUpdates();

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

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

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

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

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

איך מאכלסים את תצוגת הפיד

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

מסך בנייד שבו מוצגת פנייה שמאלה בקרוב, בעוד 30 מטר, לרחוב W Ahwanee. בתחתית המסך מוצגים הזמן שנותר להגיע ליעד (46 דקות) והמרחק שנותר (63 ק&quot;מ).

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

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

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

הנחיה לבחירת נתיב

‏Navigation 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 מגדיר כל תמרון אפשרי שיכול להתרחש במהלך הניווט, ואפשר לקבל את התמרון של שלב נתון מהשיטה StepInfo.getManeuver().

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

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

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

סמל לדוגמה תמרונים במסלול מפורט
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

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

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

כדי לאפשר לכם ליצור תרחישי שימוש ב-Android Auto, ערכת ה-Navigation SDK תומכת ביצירת סמלי הנחיה לתנועה ולנתיב. הסמלים האלה תואמים להנחיות לגבי גודל התמונות בספריית האפליקציות לרכבים של Android Auto, שבהן מומלץ לטרגט תיבת מלבנית בגודל 500 x 74dp. לפרטים נוספים, ראו 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 בסמלים.

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