Gdy pobierasz dane o podróży, Twój backend otrzymuje ładunki JSON zawierające szczegółowe informacje o postępach kierowcy. Analizuj te ładunki, aby monitorować przejazd, aktualizować systemy dyspozytorskie 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 do serwerów Navigation Connect, gdy kierowca rozpoczyna nawigację, okresowo w trakcie trasy (domyślnie co 60 sekund) oraz gdy kierowca dociera do miejsca docelowego. Każda wiadomość JSON zawiera odpowiednie dane o podróży, w tym współrzędne kierowcy przyciągnięte do drogi, przebyty dystans i szacowany czas dotarcia (ETA). Ponieważ te aktualizacje odzwierciedlają aktywną trasę kierowcy w czasie rzeczywistym, mogą się różnić od tras wstępnie obliczonych przez Twój backend (więcej informacji znajdziesz w sekcji Najczęstsze pytania).
Poniższy przykładowy kod pokazuje ładunek danych o podróży, gdy kierowca rozpoczyna nawigację do miejsca docelowego 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 stanów aktywnych przejazdów
Aby potwierdzić pomyślne rozpoczęcie i monitorować postępy, sprawdź pole stanu w każdym ładunku.
| 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 przejazd został uwierzytelniony i rozpoczęty. |
Obsługa dodanych przystanków
Kierowcy mogą dodawać przystanki do trasy podczas nawigacji. Jeśli to zrobią, Navigation Connect ustawi w ładunku danych JSON pole execution.stopAddedInRoute na true. Interfejs Navigation Connect API nadal będzie śledzić kierowcę w kierunku pierwotnego miejsca docelowego. Wskaźniki takie jak szacowany czas dotarcia (ETA), odległość i czas trwania zwiększają się, aby uwzględnić dodane przystanki.
Zachowanie podczas dodawania przystanków zależy od aplikacji do nawigacji i jest zgodne 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 stanu ENROUTE, prawdopodobnie wystąpił błąd uwierzytelniania. Typowe przyczyny to m.in. błędnie wpisane parametry interfejsu API lub wygasły token przejazdu. 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 trasy podczas tworzenia przejazdu, Twój backend będzie otrzymywać linię łamaną pozostałej trasy oraz informacje o warunkach drogowych w czasie rzeczywistym od bieżącej lokalizacji kierowcy do miejsca docelowego.
Możesz przetwarzać te dane, aby korzystać z kilku funkcji w swoich aplikacjach, np.:
- Mapy śledzenia na żywo: renderuj linię łamaną pozostałej trasy na mapie internetowej lub mobilnej widocznej dla klienta, aby zapewnić wgląd w podróż kierowcy.
- Zwiększanie dokładności ETA: połącz linię łamaną przyciągniętą do drogi i prędkości w przedziałach ruchu , aby poprawić logistykę wewnętrzną lub prognozy przyjazdu.
- Analizowanie zgodności z wyznaczaniem trasy: porównaj geometrię pozostałej trasy z oczekiwanymi trasami dyspozytorskimi, aby ocenić przestrzeganie zasad przez kierowcę (szczegółowe informacje o tym, dlaczego trasy w czasie rzeczywistym i wstępnie obliczone mogą się różnić, znajdziesz w sekcji Najczęstsze pytania ).
Navigation Connect zwraca szczegóły pozostałej trasy w polu execution.remainingRoute, niezależnie od tego, czy wysyłasz żądanie GetTrip, 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żywanej metody pobierania.
Metoda GetTrip
Gdy wywołasz metodę GetTrip, format odpowiedzi dla linii łamanej zależy od parametru routePolylineFormat określonego w żądaniu. Więcej
informacji znajdziesz w sekcji Dostosowywanie formatów linii łamanej.
W przypadku wszystkich formatów linii łamanej Navigation Connect zwraca informacje o ruchu jako oddzielną listę obiektów SpeedReadingInterval w polu execution.remainingRoute.trafficInformation. Te obiekty mapują kategorie ruchu na indeksy linii łamanej 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 przejazdu za pomocą Pub/Sub,
aktualizacje zawsze zwracają dane pozostałej trasy w ujednoliconym formacie GeoJSON
FeatureCollection 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.
Przykład ładunku Pub/Sub
Poniższy fragment kodu 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" } } ] }
Optymalizowanie rozmiaru ładunku
Ponieważ tablice współrzędnych są duże, uwzględnienie danych pozostałej trasy w wiadomościach Pub/Sub może znacznie zwiększyć rozmiar ładunku (nawet o 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 zakończenia. Użyj tych stanów, aby wywołać odpowiednie następne 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 dojazdu pieszo. |
SUSPENDED |
Kierowca ręcznie opuścił nawigację krok po kroku przed dotarciem
do miejsca docelowego. Ponieważ Mapy Google ani Waze nie wracają automatycznie do Twojej aplikacji, gdy kierowca przedwcześnie opuści sesję, 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, aby wznowić przejazd lub przełączyć się na
tryb pieszy. |
FAILED |
Błąd techniczny przerwał połączenie. Dzieje się tak, gdy aplikacja nie może obliczyć trasy lub pojawia się ostrzeżenie dotyczące bezpieczeństwa. Kierowca może nadal nawigować, 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. |