Gdy pobierzesz dane o podróży, Twój backend otrzyma ładunki JSON zawierające szczegółowe informacje o postępach kierowcy w trakcie przejazdu. Analizuj te ładunki, aby monitorować przejazd, aktualizować systemy wysyłki i interpretować bieżące stany przejazdu, aby określić następny krok dla kierowcy w trakcie przejazdu lub po jego zakończeniu.
Odczytywanie ładunku danych
Mapy Google lub Waze wysyłają ładunki danych o podróży na serwery Navigation Connect, gdy kierowca rozpoczyna nawigację, okresowo w trakcie podróży (domyślnie co 60 sekund) i gdy dociera do celu. Każda wiadomość JSON zawiera odpowiednie dane o podróży, w tym współrzędne kierowcy przypisane do drogi, przebytą odległość i szacowany czas przyjazdu.
Poniższy przykładowy kod pokazuje ładunek danych o podróży, gdy kierowca rozpoczyna nawigację w przypadku podróży z King's Cross do Central St. Giles.
{
"name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
"state": "ENROUTE",
"execution": {
"origin": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
}
},
"destination": {
"point": {
"latitude": 51.515598,
"longitude": -0.1277623
}
},
"location": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
},
"sourceTime": "2025-05-30T12:37:26Z",
"serverTime": "2025-05-30T12:37:26.221069Z"
},
"traveledDuration": "0s",
"remainingDuration": "990s",
"traveledDistanceMeters": 0,
"remainingDistanceMeters": 2879,
"stopAddedInRoute": false
}
}
Monitorowanie stanu aktywnych przejazdów
Aby potwierdzić, że rozpoczęcie się powiodło, i monitorować postępy, sprawdź pole stanu w każdym pakiecie.
| Stan | Opis |
|---|---|
NEW |
Przejazd został utworzony, ale kierowca nie rozpoczął jeszcze nawigacji. |
ENROUTE |
Kierowca aktywnie nawiguje do miejsca docelowego. Użyj tego stanu, aby potwierdzić, że podróż została uwierzytelniona i rozpoczęła się prawidłowo. |
Obsługa dodanych przystanków
Kierowcy mogą dodawać przystanki do trasy podczas nawigacji. Jeśli tak jest, Navigation Connect ustawia w ładunku danych JSON pole execution.stopAddedInRoute na true. Interfejs Navigation Connect API
nadal śledzi kierowcę w drodze do pierwotnego miejsca docelowego. Dane takie jak szacowany czas dotarcia na miejsce, odległość i czas trwania zwiększają się, aby uwzględnić dodane przystanki.
Sposób dodawania przystanków zależy od aplikacji do nawigacji i jest zgodny z jej standardową funkcjonalnością:
- Mapy Google: kierowcy mogą dodawać do trasy wiele przystanków.
- Waze: kierowcy mogą dodać tylko jeden przystanek. Jeśli kierowca spróbuje dodać kolejny przystanek, Waze poprosi go o rozpoczęcie nowej sesji nawigacji zamiast dodawania przystanku do bieżącej trasy.
Aby obsługiwać tę funkcję, nie musisz dostosowywać danych wejściowych backendu.
Rozwiązywanie problemów z uwierzytelnianiem i uruchamianiem
Jeśli nie otrzymasz statusu ENROUTE, prawdopodobnie wystąpił błąd uwierzytelniania. Typowe przyczyny to m.in. błędnie napisane parametry interfejsu API lub wygaśnięcie tokena podróży. Sprawdź czas wygaśnięcia tokena w początkowej odpowiedzi CreateTrip.
Jeśli stan nie zmieni się z NEW na ENROUTE, urządzenie kierowcy może uniemożliwiać uwierzytelnianie. W takich przypadkach Navigation Connect nie wysyła komunikatów o błędach. Sprawdź, czy:
- Kierowca ma zainstalowaną aplikację Waze w wersji 5.15.5 lub nowszej albo Mapy Google w wersji 26.14 lub nowszej.
- Kierowca nie korzysta z Androida Auto ani Apple CarPlay.
- Kierowca ma aktywne połączenie z internetem.
Obsługa pozostałych danych trasy (tylko Waze)
Jeśli podczas tworzenia przejazdu włączysz raportowanie pozostałej części trasy, Twój backend będzie otrzymywać polilinię aktywnej trasy i informacje o natężeniu ruchu w czasie rzeczywistym z bieżącej lokalizacji kierowcy do miejsca docelowego.
Możesz przetwarzać te dane i wykorzystywać je w różnych funkcjach aplikacji, np. w tych:
- Umożliwiać korzystanie z map śledzenia na żywo: renderować pozostałą część trasy na mapie internetowej lub mobilnej widocznej dla klienta, aby zapewnić wgląd w przebieg podróży kierowcy.
- Zwiększanie dokładności szacowanego czasu dotarcia: połączenie polilinii dopasowanej do drogi i prędkości w interwałach ruchu, aby poprawić wewnętrzną logistykę lub prognozy czasu dotarcia dostawy.
- Analizowanie zgodności z wyznaczaniem tras: porównaj pozostałą geometrię trasy z oczekiwanymi trasami przejazdu, aby ocenić, czy kierowca się do nich stosuje.
Navigation Connect zwraca pozostałe szczegóły trasy w polu execution.remainingRoute, niezależnie od tego, czy wysyłasz GetTrip żądanie, czy otrzymujesz aktualizacje oparte na zdarzeniach za pomocą Google Cloud Pub/Sub. Jednak sposób formatowania i strukturyzowania tych danych w ładunku zależy od użytej metody pobierania.
GetTrip metoda
Gdy wywołasz metodę GetTrip, format odpowiedzi dotyczący linii łamanej zależy od parametru routePolylineFormat określonego w żądaniu. Więcej informacji znajdziesz w artykule Dostosowywanie formatów linii łamanych.
W przypadku wszystkich formatów polilinii Navigation Connect zwraca informacje o ruchu jako osobną listę obiektów w polu
SpeedReadingInterval.execution.remainingRoute.trafficInformation Te obiekty przypisują kategorie ruchu do indeksów linii łamanych za pomocą tych wartości:
startPolylinePointIndex: indeks początkowy przedziału ruchu na linii łamanej.endPolylinePointIndex: indeks końcowy przedziału ruchu.speed: kategoria ruchu w tym segmencie:NORMAL,SLOWlubTRAFFIC_JAM.
Aktualizacje Google Cloud Pub/Sub
Gdy pobierasz dane o podróży za pomocą Pub/Sub, aktualizacje zawsze zwracają pozostałe dane trasy w ujednoliconym formacie GeoJSONFeatureCollection w polu execution.remainingRoute.
Ten format łączy geometrię linii łamanej bezpośrednio z prędkościami ruchu, eliminując potrzebę ręcznego mapowania indeksów.
Zobacz przykładowy ładunek Pub/Sub
Poniższy przykładowy kod pokazuje strukturę GeoJSON zwróconą w polu execution.remainingRoute w obiekcie updatedTrip wiadomości Pub/Sub:
{ "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.3934, 37.7955], [-122.4010, 37.7980] ] }, "properties": { "speed": "SLOW" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.4010, 37.7980], [-122.4058, 37.8025], [-122.4187, 37.8021] ] }, "properties": { "speed": "NORMAL" } } ] }
Optymalizacja rozmiaru ładunku
Tablice współrzędnych są duże, więc uwzględnienie w wiadomościach Pub/Sub pozostałych danych trasy może znacznie zwiększyć rozmiar ładunku (nawet do 13–14 KB na wiadomość). Jeśli otrzymujesz aktualizacje o wysokiej częstotliwości, ta ilość może zwiększyć obciążenie przetwarzania backendu i koszty użytkowania.
Aby zoptymalizować strumień, podczas tworzenia przejazdu użyj parametru pubsubFieldMask w obiekcie TripConfig, aby wykluczyć duże pola. Więcej informacji znajdziesz w sekcji Konfiguracje opcjonalne.
Obsługa stanów zakończenia przejazdu
Gdy kierowca dotrze do miejsca docelowego lub zatrzyma nawigację, ładunek zwróci jeden z tych stanów końcowych: Używaj tych stanów, aby wywoływać odpowiednie kolejne kroki w aplikacji.
| Stan | Opis | Zalecane działanie |
|---|---|---|
ARRIVED |
Kierowca dotarł do miejsca docelowego. | Sprawdź remainingDistanceMeters. Jeśli kierowca zaparkował w pobliżu, ale nie w dokładnych współrzędnych, rozważ podanie w aplikacji wskazówek dotyczących trasy pieszej. |
SUSPENDED |
Kierowca ręcznie zamknął szczegółowe wskazówki dojazdu przed dotarciem do celu. Gdy kierowca przedwcześnie zakończy sesję, Mapy Google lub Waze nie przekierują go automatycznie z powrotem do Twojej aplikacji. Musi on ręcznie kliknąć przycisk powrotu. |
Aby pomóc kierowcom w ukończeniu podróży, porównaj execution.location z miejscem docelowym. Jeśli odległość nadal jest duża, udostępnij przycisk lub link umożliwiający wznowienie podróży lub przejście do trybu pieszego. |
FAILED |
Połączenie zostało przerwane z powodu błędu technicznego. Dzieje się tak, gdy aplikacja nie może obliczyć trasy lub pojawia się ostrzeżenie dotyczące bezpieczeństwa. Kierowca może nadal korzystać z nawigacji, ale nie będziesz otrzymywać aktualizacji. | Wróć do ręcznego śledzenia stanu w aplikacji. |
CLIENT_ERROR |
Ten stan pojawia się z jednego z tych powodów:
|
Wróć do ręcznego śledzenia stanu w aplikacji. |