Gdy pobierasz dane o przejeździe, Twój backend otrzymuje ładunki JSON ze szczegółowymi informacjami o postępach kierowcy. Przeanalizuj te ładunki, aby monitorować przejazd, aktualizować systemy wysyłania i interpretować bieżące stany przejazdu, aby określić następny krok kierowcy w miarę postępów lub po zakończeniu przejazdu.
Odczytywanie ładunku danych
Mapy Google lub Waze wysyłają ładunki danych o podróży na serwery Navigation Connect, gdy kierowca rozpoczyna nawigację, okresowo na trasie (domyślnie co 60 sekund) i gdy kierowca dociera do miejsca docelowego. Każdy komunikat JSON zawiera odpowiednie dane o podróży, w tym współrzędne kierowcy dopasowane do drogi, przebyty dystans i szacowany czas dotarcia na miejsce. Te aktualizacje odzwierciedlają aktywną trasę kierowcy w czasie rzeczywistym, dlatego mogą się różnić od tras wstępnie obliczonych przez backend (patrz Najczęstsze pytania).
Poniższy przykładowy kod pokazuje ładunek danych przejazdu, gdy kierowca rozpoczyna nawigację na trasie 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ć, że proces został pomyślnie rozpoczęty, i monitorować postępy, sprawdź pole state 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 tak, Navigation Connect ustawia pole execution.stopAddedInRoute na true w ładunku danych JSON. Interfejs Navigation Connect API nadal śledzi kierowcę w kierunku pierwotnego miejsca docelowego. Dane takie jak szacowany czas dotarcia na miejsce, odległość i czas trwania zostaną zwiększone, aby uwzględnić dodane przystanki.
Sposób dodawania przystanków zależy od aplikacji do nawigacji i jest zgodny z jej standardowymi funkcjami:
- Mapy Google: kierowcy mogą dodawać do trasy wiele przystanków.
- Waze: kierowcy mogą dodać tylko 1 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.
Nie musisz dostosowywać danych wejściowych backendu, aby obsługiwać tę funkcję.
Rozwiązywanie problemów z uwierzytelnianiem i uruchamianiem
Jeśli nie otrzymasz stanu ENROUTE, prawdopodobnie wystąpił błąd uwierzytelniania. Najczęstsze przyczyny to błędy w pisowni parametrów interfejsu API lub wygaśnięcie tokena przejazdu. Sprawdź czas ważności 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. Potwierdź te informacje:
- 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.
Postępowanie z pozostałymi danymi o trasach
Jeśli podczas tworzenia podróży włączysz raportowanie pozostałej trasy, Twój backend będzie otrzymywać łamaną pozostałej trasy i informacje o warunkach na drodze w czasie rzeczywistym od bieżącej lokalizacji kierowcy do miejsca docelowego. Kierowcy muszą mieć Waze w wersji 5.20.0.2 lub nowszej na Androidzie, 5.20.0.1 lub nowszej na iOS albo Mapy Google na Androida w wersji 26.27 lub nowszej.
Możesz pozyskiwać i przetwarzać te dane, aby zasilać kilka funkcji w aplikacjach, takich jak:
- Mapy śledzenia na żywo: renderuj pozostałą część trasy na mapie internetowej lub mobilnej dla klienta, aby zapewnić mu widoczność trasy kierowcy.
- Zwiększanie dokładności szacowanego czasu dotarcia na miejsce: połącz linię łamaną dopasowaną do drogi i prędkości w interwałach ruchu, aby ulepszyć wewnętrzną logistykę lub prognozy dotyczące czasu dostawy.
- Analizowanie zgodności trasy: porównaj geometrię pozostałej trasy z oczekiwanymi trasami wysyłki, aby ocenić, czy kierowca przestrzega trasy (szczegółowe informacje o tym, dlaczego trasy w czasie rzeczywistym i wstępnie obliczone mogą się różnić, znajdziesz w najczęstszych pytaniach).
Navigation Connect zwraca pozostałe szczegóły 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 format i struktura tych danych w ładunku zależą od używanej metody pobierania.
GetTrip metoda
Gdy wywołujesz 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 natężeniu ruchu jako osobną listę obiektów SpeedReadingInterval w polu execution.remainingRoute.trafficInformation. Te obiekty mapują kategorie natężenia ruchu na indeksy linii łamanej za pomocą tych wartości:
startPolylinePointIndex: indeks początkowy interwału ruchu na linii łamanej.endPolylinePointIndex: indeks końcowy interwału natężenia ruchu.speed: kategoria ruchu dla tego segmentu:NORMAL,SLOWlubTRAFFIC_JAM.
Aktualizacje Google Cloud Pub/Sub
Gdy pobierasz dane o przejazdach za pomocą Pub/Sub, aktualizacje zawsze zwracają dane o pozostałej trasie w ujednoliconym formacie GeoJSON FeatureCollection w polu execution.remainingRoute.
Ten format łączy geometrię linii łamanej bezpośrednio z prędkością ruchu, eliminując potrzebę ręcznego mapowania indeksów.
Przykładowy ładunek Pub/Sub
Poniższy przykładowy kod pokazuje strukturę GeoJSON zwracaną 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
Tablice współrzędnych są duże, więc uwzględnienie pozostałych danych trasy w wiadomościach Pub/Sub może znacznie zwiększyć rozmiar ładunku (do 13–14 KB na wiadomość). Jeśli otrzymujesz częste aktualizacje, może to zwiększyć obciążenie przetwarzania backendu i koszty użytkowania.
Aby zoptymalizować strumień, podczas tworzenia podróży użyj parametru pubsubFieldMask w obiekcie TripConfig, aby wykluczyć duże pola. Szczegółowe informacje znajdziesz w sekcji Konfiguracje opcjonalne.
Obsługa zjechania z trasy (tylko Waze)
Kierowcy muszą mieć Waze w wersji 5.22 lub nowszej.
Jeśli podczas tworzenia podróży włączysz raportowanie o zjechaniu z trasy, gdy kierowca zjedzie z trasy, interfejs API zwróci metadane dotyczące zjechania z trasy. Dostęp do tych danych możesz uzyskać na te sposoby:
- Na żądanie: wywołaj metodę
GetTrip. Serwer zachowuje ostatni znany stan odchylenia. - W czasie rzeczywistym: zasubskrybuj Google Cloud Pub/Sub. Usługa publikuje aktualizacje dotyczące odchyleń, korzystając z istniejącego zdarzenia
updated_tripw ciągu 5 sekund od wykrycia.
Odczytywanie ładunku odchylenia
Obiekt last_route_deviation udostępnia te metadane, które ułatwiają analizę zdarzenia.
| Pole | Typ | Opis |
|---|---|---|
location |
LatLng |
Współrzędne szerokości i długości geograficznej, w których urządzenie klienta zarejestrowało odchylenie. |
source |
TriggerSource |
Powód odchylenia. Użyj tej opcji, aby sprawdzić, czy kierowca podjął nieoczekiwane działanie lub postępował zgodnie ze wskazówkami systemu:
|
client_timestamp |
Timestamp |
Czas, w którym urządzenie klienta wykryło odchylenie. |
server_timestamp |
Timestamp |
Czas przetworzenia przez serwer aktualizacji odchylenia. |
Obsługa stanów zakończenia przejazdu
Gdy kierowca dotrze do miejsca docelowego lub zatrzyma nawigację, ładunek zwraca jeden z tych stanów końcowych. Użyj tych stanów, aby wywołać odpowiednie dalsze kroki w aplikacji.
| Stan | Opis | Zalecane działanie |
|---|---|---|
ARRIVED |
Kierowca dotarł do miejsca docelowego. | Zapoznaj się z: remainingDistanceMeters. Jeśli kierowca zaparkował w pobliżu, ale nie dokładnie we wskazanych współrzędnych, rozważ podanie w aplikacji trasy pieszej. |
SUSPENDED |
Kierowca ręcznie wyłączył szczegółowe wskazówki dojazdu przed dotarciem do celu. Mapy Google i Waze nie przekierowują automatycznie kierowców do Twojej aplikacji, gdy przedwcześnie zakończą sesję, dlatego kierowca musi ręcznie kliknąć przycisk powrotu. |
Aby pomóc kierowcom dotrzeć do celu, porównaj execution.location z miejscem docelowym. Jeśli odległość pozostaje, udostępnij przycisk lub link, aby wznowić przejazd lub przełączyć się na tryb pieszy. |
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. |