פיד הנתונים של מסלול מפורט מספק מידע על ניווט בלבד למכשירים, שלא מיועד להנחיות ניווט מבוססות-מפה. היא כוללת תמרונים עתידיים עם הרכיבים שאתם מספקים:
- סמלים (שמאלה, ימינה, פניית U)
- פנייה מספרים בכיכרות
- שמות של דרכים
- מרחקים וזמן משוערים עד לשלב הניווט הבא או ליעד הסופי
תוכלו להשתמש בפיד המסלול המפורט כדי ליצור חוויות שבהן ממשק המשתמש המלא של ה-Navigation SDK לא מתאים, למשל ל-Android Auto או למסכים קטנים שבהם אין סטאק מלא של Android. לדוגמה, אפשר להשתמש באפשרות הזו במקרה של נהגים דו-גלגליים, שבהם אפשר לצפות בהנחיות ניווט בלבד כדי שיעזרו להם להגיע ליעד מהר יותר ובצורה בטוחה יותר, עם כמה שפחות הסחות דעת.
כדי להשתמש ב-SDK, צריך ליצור שירות ולרשום אותו ב-Navigation SDK ל-Android כדי שיוכל לקבל מידע ניווט חדש בזמן אמת (בערך פעם שנייה במהלך הניווט).
במסמך הזה מוסבר איך ליצור ולרשום שירות ניווט שמקבל פרטי ניווט מה-SDK ומספק את מצב הניווט למכשיר המקבל.
סקירה
הקטע הזה מתאר איך להוסיף את הספרייה TurnByTurn לפרויקטים, ומסכם את התהליך ברמה הכללית ליצירת פונקציונליות של מסלול מפורט.
הוספת ספריית TurnByTurn לפרויקט באמצעות Maven (מומלץ)
כדי לצרוך גרסה עצמאית של הספרייה TurnByTurn, מבצעים את השלבים הבאים:
- מגדירים את הסביבה כדי לגשת למאגר 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:
-
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 הזו. אם אין לכם גישה, פנו לנציג שלכם.
- מורידים את
google_turnbyturn_*.jar
ומחלצים אותו. - מעתיקים את קובץ ה-JAR שהורדתם לספריית
app/libs
של הפרויקט. כדי לכלול את ה-JAR ב-build, צריך להוסיף את קטעי הקוד הבאים ל-
build.gradle
.dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
שימוש בספריית TurnByTurn
אלה השלבים הכלליים להפעלת פונקציונליות של מסלול מפורט. בקטעים הבאים תמצאו פרטים לגבי כל שלב.
צריך ליצור שירות כדי לקבל עדכוני ניווט
ערכת ה-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 – המשמעות של המצב
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
יכולים למפות לסמל הפנייה שמאלה.
חלק מהתמרונים מכילים תווית נוספת של 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: