מדריך להעברת נתונים (מיגרציה)

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

השינוי הגדול ביותר ש-Google ביצעה ב-Navigation SDK לגרסה 2 הוא החלפת כמה מחלקות של Navigation SDK ב-Maps SDK ל-Android.

החל מגרסה 2.2, ה-SDK של הניווט הוא תחליף (כמעט) ל-Google Play Services Maps API. במקום לארוז מחדש את כל ממשקי ה-API ב-com.google.android.libraries.maps, הם נארזים ב-com.google.android.gms.maps בדיוק כמו ב-Google Play Services. כך המעבר בין גרסה של Google Play Services ל-SDK של הניווט יכול להיות הרבה יותר פשוט.

אזהרה: ההוראות האלה תקפות רק לגרסה 2.2 ואילך.

יתרונות

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

עם זאת, תכונות כמו Street View ומצב Lite אינן נתמכות.

נקודה חשובה: ה-SDK של הניווט יחליף את SDK של מפות Google ל-Android ותצטרכו להסיר את כל ההפניות ללקוח.

דרישות מוקדמות

• גרסה 2 של Navigation SDK כוללת את Android Jetpack – חבילה של ספריות, כלים והנחיות שבעזרתם קל יותר לכתוב אפליקציות באיכות גבוהה. המשמעות של המעבר הזה היא שאתם צריכים להעביר את האפליקציה מספריות תמיכה כדי להשתמש ב-AndroidX. אפשר לקרוא מידע נוסף במאמר העברה ל-AndroidX.

שלב 1. העברה מה-SDK של מפות Google ל-Android

רוב הפונקציונליות ב-SDK של מפות Google ל-Android כלולה עכשיו בגרסה 2 של הניווט SDK. כמה תכונות הוסרו כי לא היה בהן צורך בהקשר של הניווט.

הבדלים חשובים

ה-SDK של מפות Google ל-Android היה בשירותי Google Play.

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

השמות של חלק מהכיתות שונו

בטבלה הבאה מפורטות הכיתות שהשם שלהן שונה. המטרה של האפליקציה הזו הייתה להבדיל בינם לבין הפלטפורמה של מפות Google ל-Android SDK.

שם המחלקה של מפות Google ל-Android	שם המחלקה של ה-SDK של הניווט
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

במחלקות האלה יש שילוב של השיטות שזמינות בכיתה NavigationView הישנה ובכיתה הנוכחית MapView. אפשר לחשוב עליהם כמו הכיתות MapView ו-MapFragment, אבל עם תמיכה בניווט.

תכונות שהוסרו

חלק מהתכונות של מפות Google הוסרו כי הן לא היו הגיוניות בהקשר של הניווט, או כי היו אי התאמות טכניות. התכונות שהוסרו כוללות:

• Street View.
• מצב בסיסי, שלא מספיק לניווט.
• לא ניתן להגדיר LocationProvider כשהמצלמה נמצאת במצב מעקב. הסיבה לכך היא שהניווט מבוסס על RoadSnappedLocationProvider, ומעבר לספק הזה עלול לגרום לבעיות במהלך הניווט.
• להחלת הגבולות של LatLng או של מינימום/מקסימום אין השפעה כשהמצלמה נמצאת במצב מעקב.
• אם התכונות החסרות גורמות לך לבעיות, מומלץ לפנות לנציג הלקוח.

שלבי ההעברה

1. מסירים את השילוב של Maps SDK ל-Android מה-build שלכם (כלומר gradle). שימוש בשתי ערכות ה-SDK יגרום לשגיאות הידור.
2. מחליפים את המופעים של MapView במופעים של NavigationView.
3. מחליפים את המופעים של MapFragment במופעים של NavigationSupportFragment.

אם האפליקציה לא השתמשה בעבר ב-Navigation SDK, ההעברה הושלמה.

שלב 2. מעבר מגרסה v1.x של Navigation SDK

בצע את השלבים הבאים כדי להעביר את שילוב v1.x של ה-SDK של הניווט לגרסה 2.

1. הצגת המפה בשיטות חדשות

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

השיטה הישנה	שיטה חדשה
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

הערה: הכיתה NavigationFragment הוסרה כי הכיתה Fragment הוצאה משימוש לטובת הכיתה SupportFragment.

2. העברת הספריות

גרסה v1.x של ה-API של הניווט כללה הטמעה עצמאית של מספר SDK של מפות Google למחלקות Android. המחלקות האלה היו שייכות לחבילה com.google.android.libraries.navigation.

בגרסה 2, המחלקות האלה הוחלפו בהטמעות של מפות Google ל-Android, שנמצאות בחבילה com.google.android.gms.maps.model. אפשר להעביר את האפליקציה כדי לשלב את הכיתות החדשות על ידי ביצוע חיפוש והחלפה.

בטבלה הבאה מפורטות הכיתות הישנות והכיתות החדשות.

כיתה ישנה	כיתה חדשה
com.google.android.libraries.navigation.LatLng	com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds	com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker	com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions	com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion	com.google.android.gms.maps.model.VisibleRegion

3. יישום השינויים בממשקי API קיימים

בטבלה הבאה מפורטים השינויים העיקריים ש-Google ביצעה בגרסה 2 של ה-SDK של הניווט.

שיטה	שינוי
NavigationApi.cleanup()	הנושא הוסר. השיטה הזו לא שימשה לפעולה רגילה, והיא עלולה לגרום להתנהגות בלתי צפויה. צריך להסיר שיחות לשיטה הזו.
RoadSnappedLocationProvider.requestLocationUpdates()	הנושא הוסר. במקום זאת, השתמשו ב-addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	הנושא הוסר. במקום זאת, השתמשו ב-removeLocationListener().

4. מעבר למחלקה החדשה של כלי הסימון

בגרסה 2 של ה-API לניווט נעשה עכשיו שימוש באותו יישום של המחלקה Marker כמו ה-SDK של מפות Google ל-Android. בעקבות זאת נעשים השינויים הבאים.

שיטות שקשורות לסמנים

שיטה	שינוי
addMarker(MarkerOptions markerOptions)	עכשיו נעשה שימוש במחלקה com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	השיטה הזו כבר לא קיימת. במקום זאת, לכיתת הסמן יש עכשיו שיטה marker.remove().
removeAllMarkers()	השיטה הזו לא קיימת יותר, למרות שיש שיטה clear() שמסירה את כל הסמנים, הקווים הפוליגוניים, הפוליגונים ושכבות-העל מהמפה.

הבדלים באפשרויות הסימון

• השיטה describeContents() לא קיימת בגרסה 2 של הניווט SDK. אפשר היה לשמור את נתוני התצוגה על ידי התקשרות אל onSaveInstanceState(). עכשיו עליך לעקוב אחרי פרטי התצוגה כדי שתהיה לך אפשרות לשחזר אותה אם יהיו שינויים בהגדרה.
• השיטה navMarker#icon(BitMap) השתנתה ועכשיו היא mapMarker#icon(BitmapDescriptor). השינוי הזה מחייב לעבור משימוש ב-BitMap כדי להשתמש ב-BitmapDescriptor.

שיטות סימון

עכשיו תשתמשו במחלקה Marker מהחבילה com.google.android.gms.maps.model. בטבלה הבאה מפורטים ההבדלים בשימוש במחלקה החדשה של Marker.

שיטה	שינוי
getAnchorU()	כבר לא קיים.
getAnchorV()	כבר לא קיים.
getIcon()	לא קיים יותר. עליך לשמור הפניה לסמל בעצמך, לשימוש לאחר שינוי הגדרה כאשר עליך ליצור מחדש את מצב המפה.
getPosition()	עדיין קיים.
getTitle()	עדיין קיים.

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

5. בקרת המצלמה

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

הבדלים עיקריים

• המחלקה com.google.android.libraries.navigation.Camera הוסרה בגרסה 2.
  • הפריט Camera.showRouteOverview() הועבר אל NavigationView ואל SupportNavigationFragment.
  • שיטת הבידינג Camera.followMyLocation() הועברה אל GoogleMap.
• אפשר להחליף את השיחות אל Camera.setLocation() ב-GoogleMap.moveCamera() או ב-GoogleMap.animateCamera().
• setOnFollowMyLocationCallback() ו-isCameraFollowingMyLocation() נוספו אל GoogleMap כדי לספק מידע נוסף על מצב המעקב.

שלב 3. מיזוג תהליכי פעילות

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