האזנה לאירועי ניווט

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

סקירה כללית

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

הצגת הקוד

זיהוי הגעה ליעד

המונח "יעד" מתייחס ליעד הסופי או לנקודת עצירה. כדי לזהות הגעה, צריך להפעיל את Navigator.addArrivalListener(), שרושם קריאה חוזרת (callback) כשהמכשיר מגיע ליעד.

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

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

כדי למנוע דליפות זיכרון, צריך להפעיל את removeArrivalListener(listener) כשכבר לא צריך את המאזין.

mNavigator.addArrivalListener(new Navigator.ArrivalListener() {
    @Override
    public void onArrival(ArrivalEvent arrivalEvent) {
        displayMessage("onArrival: You've arrived at a waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_BOTH);
        // Start turn-by-turn guidance for the next leg of the route.
        if (arrivalEvent.isFinalDestination()) {
            displayMessage("onArrival: You've arrived at the final destination.",
                    DISPLAY_BOTH);
        } else {
            mNavigator.continueToNextDestination();
            mNavigator.startGuidance();
        }
    }
});

קבלת עדכונים לגבי מיקום

מקבלים RoadSnappedLocationProvider מ-NavigationApi, ואז קוראים ל-RoadSnappedLocationProvider.addLocationListener() כדי להירשם לקריאה חוזרת (callback) כשהמיקום או הכיוון של המכשיר משתנים. שימו לב שהמיקום הזה מוצמד לכביש, ולכן הוא עשוי להיות שונה מהמיקום שמוחזר על ידי ספק המיקום המשולב בממשקי ה-API של המיקום ב-Google Play Services.

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

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

mRoadSnappedLocationProvider =
        NavigationApi.getRoadSnappedLocationProvider(getApplication());
if (mRoadSnappedLocationProvider != null) {
    mRoadSnappedLocationProvider.addLocationListener(
            new RoadSnappedLocationProvider.LocationListener() {
                @Override
                public void onLocationChanged(Location location) {
                    displayMessage("onLocationUpdated: Navigation engine has provided a new"
                                    +   " road-snapped location: "
                                    +   location.toString(),
                            DISPLAY_LOG);
                }
            });
} else {
    displayMessage("ERROR: Failed to get a location provider", DISPLAY_LOG);
}

קבלת עדכונים על זמן ומרחק

קוראים לפונקציה Navigator.addRemainingTimeOrDistanceChangedListener() כדי להירשם לקריאה חוזרת (callback) כשהזמן שנותר (בשניות) או המרחק שנותר (במטרים) משתנים בערך שגבוה מסף מסוים.

כשהשינוי בזמן או במרחק חורג מהכמות שצוינה, ה-Navigation SDK מפעיל את הקריאה החוזרת (callback) onRemainingTimeOrDistanceChanged().

כדי לברר את הזמן והמרחק שנותרו, אומרים Navigator.getTimeAndDistanceList(). שימו לב שהזמנים והמרחקים ברשימה הם מצטברים: הם מציגים את הזמן והמרחק מהמיקום הנוכחי לכל נקודת דרך, ולא מנקודת דרך אחת לאחרת. האובייקט TimeAndDistance מחזיר גם את delaySeverity. הערכים האפשריים של הטיפוס הזה הם HEAVY,‏ MEDIUM,‏ LIGHT או UNKNOWN. הוא תואם לצבע שמוצג בזמן ההגעה המשוער בממשק המשתמש של מפות Google (עומס כבד = אדום, עומס בינוני = צהוב, עומס קל = ירוק). האפשרות הזו שימושית אם אתם צריכים ליצור כותרת תחתונה משלכם לזמן ההגעה המשוער.

כדי למנוע דליפות זיכרון, צריך להפעיל את Navigator.removeRemainingTimeOrDistanceChangedListener(listener) כשכבר לא צריך את המאזין.

הדוגמה הבאה מבקשת קריאה חוזרת (callback) אם הזמן שנותר משתנה ביותר מ-60 שניות או אם המרחק שנותר משתנה ביותר מ-100 מטרים.

mNavigator.addRemainingTimeOrDistanceChangedListener(60, 100,
        new Navigator.RemainingTimeOrDistanceChangedListener() {
            @Override
            public void onRemainingTimeOrDistanceChanged() {
                displayMessage("onRemainingTimeOrDistanceChanged: Time or distance estimate"
                        +   " has changed.",
                        DISPLAY_LOG);
            }
        });

כדי להציג את הזמן והמרחק שנותרו באמצעות המסך המובנה, משתמשים ב-method‏ setEtaCardEnabled() ומעבירים פרמטר עם הערך TRUE. כדי להסתיר את תצוגת הזמן והמרחק, מגדירים את הערך הזה כ-FALSE.

אפשר גם להציג את זמן ההגעה המשוער לכמה נקודות ציון באמצעות השיטה getTimeAndDistanceList().

קבלת עדכונים על המסלול

מתקשרים למספר Navigator.addRouteChangedListener() כדי להירשם לקבלת שיחה חוזרת כשהמסלול משתנה.

כשהמסלול משתנה, ה-Navigation SDK מפעיל את פונקציית ה-callback‏ onRouteChanged(). אתם יכולים להתקשר אל Navigator.getRouteSegments ואל Navigator.getCurrentRouteSegment() כדי למצוא את המסלול החדש.

כדי למנוע דליפות זיכרון, צריך להפעיל את removeRouteChangedListener(listener) כשכבר לא צריך את המאזין.

mNavigator.addRouteChangedListener(new Navigator.RouteChangedListener() {
    @Override
    public void onRouteChanged() {
        displayMessage("onRouteChanged: The driver's route has changed. Current waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_LOG);
    }
});

זיהוי שינויים במצב לילה

אפשר להתקשר למספר NavigationView.addOnNightModeChangedListener או NavigationFragment.addOnNightModeChangedListener כדי להירשם לשיחה חוזרת כשהמצב ישתנה.

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

mNavFragment.addOnNightModeChangedListener(new NavigationView.OnNightModeChangedListener() {
    @Override
    public void onNightModeChanged(NightModeChangedEvent nightModeChangedEvent) {
        displayMessage("Night mode is active: " + nightModeChangedEvent.inNightMode(),
        DISPLAY_LOG);
    }
});

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