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

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

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

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

navigator.unregisterServiceForNavUpdates();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Maneuver 'טיפוסים בני מנייה (enum)' מגדיר כל תמרון אפשרי שעשוי להתרחש במהלך ניווט, הוא יכול לקבל את התמרון לשלב נתון מהשיטה StepInfo.getManeuver().

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

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

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

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

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