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

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

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

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

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

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

סקירה

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

הוספת ספריית TurnByTurn לפרויקט באמצעות Maven (מומלץ)

הערה: אפשר לדלג על השלב הזה אם כבר הגדרתם את האפליקציה עם ה-Navigation 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()
   }
       

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

2. 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. דוגמה לתצוגת ניווט שמציגה רכיבים חיוניים.

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

ערכת ה-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.

הערה: הקפידו להוסיף את טווח הערכים 7200-7299 לקודים של הודעות, כי בעתיד ה-Navigation SDK עשוי להשתמש בקודי הודעות בטווח הזה.

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

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

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

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

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

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

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

navigator.unregisterServiceForNavUpdates();

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

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

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

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

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

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

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

שדות מידע של כרטיס ניווט

כשהמשתמשים עוברים לניווט מודרך, מופיע בחלק העליון כרטיס ניווט שמכיל נתוני ניווט שאוכלסו מ-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 יכולים למפות לסמל הפנייה שמאלה.

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

חלק מהתמרונים מכילים תווית נוספת של clockwise או counterclockwise, ש-SDK קובעת לפי הצד הנהיגה של המדינה. לדוגמה, במדינות שבהן הנסיעה היא בצד שמאל של הכביש, הנהגים פונים לכיכר או לפניית פרסה בכיוון השעון, ואילו מדינות אחרות בצד ימין בכביש פונים בכיוון השעון. ה-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

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

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

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

מה עושים אחר כך

• באפליקציות ל-Android Auto:
  • משרטטים את המפה ומפעילים את הניווט.