Aby rozpocząć sesję nawigacji, aplikacja musi dynamicznie utworzyć adres URL uruchamiania, który otworzy Mapy Google lub Waze. Z tego przewodnika dowiesz się, jak używać uwierzytelnionego tokena podróży z funkcji Tworzenie podróży, aby uruchamiać Mapy Google lub Waze i konfigurować powrót do aplikacji.
Jak uruchomić Mapy Google lub Waze
Aby uruchomić Mapy Google lub Waze, musisz umożliwić kierowcom rozpoczęcie sesji nawigacji z poziomu aplikacji, utworzyć adres URL uruchamiania z wymaganymi parametrami i podać identyfikator aplikacji, aby przypisać sesję.
Umożliwianie kierowcom rozpoczynania nawigacji z Twojej aplikacji
Zapewnij kierowcom możliwość rozpoczęcia nawigacji z poziomu Twojej aplikacji. Jeśli umożliwiasz kierowcom uruchamianie Map Google lub Waze za pomocą przycisku, zadbaj o odpowiednie oznaczenie i unikaj nieporozumień, wyraźnie opisując przycisk. Na przykład umieść tekst „Mapy Google” lub „Waze” na przycisku lub w jego pobliżu.
Tworzenie adresu URL uruchamiania
Aby rozpocząć sesję nawigacji, utwórz adres URL uruchamiania Navigation Connect. Ten adres URL to ciąg znaków zawierający miejsce docelowe, token podróży i wymagane parametry nawigacji. Działa podobnie jak standardowy adres URL Map Google lub link bezpośredni Waze.
Aby uruchomić Mapy Google lub Waze na urządzeniu kierowcy, użyj mechanizmu specyficznego dla platformy:
- Android: przekaż ciąg znaków adresu URL w
Intent. - iOS: użyj ciągu adresu URL jako linku uniwersalnego (lub precyzyjnego linku).
Formatowanie miejsca docelowego
Aby Mapy Google lub Waze mogły prawidłowo obliczyć trasę, podczas formatowania miejsca docelowego przestrzegaj tych zasad:
Określ dokładnie 1 miejsce docelowe, do którego można dotrzeć. Możesz przekazać miejsce docelowe jako ciąg znaków adresu, współrzędne szerokości i długości geograficznej lub identyfikator miejsca.
Nie używaj wielu punktów pośrednich. Jeśli w adresie URL podasz wiele punktów pośrednich, Mapy Google lub Waze wyświetlą błąd. Zamiast tego utwórz osobne wycieczki.
Dodawanie tokena przejazdu i parametrów nawigacji
Aby uzupełnić adres URL uruchomienia, musisz dodać uwierzytelniony token przejazdu, który został przesłany w odpowiedzi na żądanie utworzenia przejazdu. Musisz też podać parametry nawigacji, które informują Mapy Google lub Waze o rozpoczęciu aktywnej nawigacji.
Mapy Google
W przypadku Map Google w adresie URL uruchamiania umieść te parametry:
dir_action=navigate: ten parametr wymusza aktywną nawigację.action_token: Ten parametr dostarcza uwierzytelniony token przejazdu.
Poniższe przykłady pokazują, jak sformatować adres URL uruchamiania Map Google przy użyciu różnych formatów miejsca docelowego:
-
Współrzędne geograficzne:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
Ciąg znaków adresu:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
Identyfikator miejsca:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
W przypadku Waze w adresie URL uruchamiania umieść te parametry:
navigate=yes: ten parametr wymusza aktywną nawigację.external_trip_token: ten parametr zawiera uwierzytelniony token podróży.
Poniższe przykłady pokazują, jak sformatować adres URL uruchamiania Waze przy użyciu różnych formatów miejsca docelowego:
-
Współrzędne geograficzne:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
Ciąg znaków adresu:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
Identyfikator miejsca:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
Podaj identyfikator aplikacji (tylko na Androidzie)
Aby rozpocząć podróż za pomocą Navigation Connect, musisz przypisać sesję nawigacji do swojej aplikacji na Androidzie. Aby to zrobić, podaj zweryfikowany identyfikator aplikacji. Identyfikuje on Twoją aplikację jako źródło przejazdu, dzięki czemu Mapy Google lub Waze mogą połączyć aktywny przejazd z Twoją platformą. Brakujący lub nieprawidłowy identyfikator aplikacji powoduje niepowodzenie uwierzytelniania tokena przejazdu.
Podanie identyfikatora aplikacji umożliwia korzystanie z tych funkcji:
- Autoryzacja udostępniania danych: weryfikuje, czy Twoja aplikacja ma uprawnienia do otrzymywania danych o aktywnej podróży.
- Włączanie zgody kierowcy: na ekranie zgody wyświetlana jest nazwa firmy i polityka prywatności, dzięki czemu kierowca wie, kto otrzymuje jego lokalizację w czasie rzeczywistym i szacowany czas przyjazdu.
- Włącz przycisk powrotu: umożliwia Mapom Google lub Waze utworzenie przycisku powrotu z Twoim logo, aby kierowcy mogli wrócić do Twojej aplikacji.
Aby przekazać identyfikator aplikacji do Map Google lub Waze na Androidzie, dodaj nazwę pakietu do intencji uruchomienia (która zawiera ciąg adresu URL uruchomienia) za pomocą Intent.EXTRA_REFERRER_NAME.
W tym przykładzie pokazujemy, jak dodać nazwę pakietu do intencji:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Jak umożliwić kierowcom powrót do Twojej aplikacji
Navigation Connect wyświetla pasek dolny (Mapy Google) lub przycisk Wstecz z logo marki (Waze), dzięki czemu kierowca może w dowolnym momencie przejazdu lub po dotarciu do miejsca docelowego bezproblemowo wrócić do Twojej aplikacji.
Android
Musisz utworzyć PendingIntent, który będzie odsyłać do aktywności w aplikacji. Dołącz ten PendingIntent jako dodatkowy element do intencji uruchomienia
za pomocą dokładnego klucza "pendingIntent". Gdy użytkownik kliknie przycisk powrotu, Mapy Google lub Waze wykonają ten zamiar, aby wyświetlić Twoją aplikację na pierwszym planie.
intent.putExtra("pendingIntent", getPendingIntent())iOS (tylko Waze)
Aby włączyć przycisk powrotu, nie musisz niczego dodawać do adresu URL uruchomienia. Waze automatycznie używa uniwersalnego linku zarejestrowanego podczas weryfikacji aplikacji.
Przykładowe fragmenty kodu
Poniższe przykłady kodu pokazują, jak uruchomić Mapy Google lub Waze z aplikacji za pomocą Navigation Connect i włączyć przycisk „Wróć do aplikacji”.
Mapy Google (Android)
Poniższy kod w Kotlinie przedstawia przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami.
private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"
private fun launchNavConnect() {
val jwtToken = "TRIP_TOKEN"
try {
// URL Encode the destination
val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
val navConnectUrl = "https://www.google.com/maps/dir/?api=1" +
"&destination=$encodedDestination" +
"&dir_action=navigate" +
"&action_token=$jwtToken"
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
// Explicitly set GMM package to ensure it opens in Google Maps
intent.setPackage("com.google.android.apps.maps")
// Add your application ID to the intent
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
// set up the NavConnect back button
intent.putExtra("pendingIntent", getPendingIntent())
startActivity(intent)
} catch (e: Exception) {
// handle errors
}
}
private fun getPendingIntent(): PendingIntent? {
val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
val flags = PendingIntent.FLAG_IMMUTABLE
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
return PendingIntent.getActivity(application, 0, returnIntent, flags)
}
val options =
ActivityOptions.makeBasic()
.setPendingIntentCreatorBackgroundActivityStartMode(
ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
)
return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
}Waze (Android)
Poniższy kod w Kotlinie przedstawia przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami.
private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"
private fun launchNavConnect() {
val tripToken = "TRIP_TOKEN"
try {
// URL Encode the destination
val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
val navConnectUrl = "https://waze.com/ul?" +
"&q=$encodedDestination" +
"&navigate=yes" +
"&external_trip_token=$tripToken"
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
// Explicitly set package name to ensure it opens in Waze
intent.setPackage("com.waze")
// Add your application ID to the intent
val referrerName = "android-app://${application.packageName}"
intent.putExtra(Intent.EXTRA_REFERRER_NAME, referrerName)
// set up the NavConnect back button
intent.putExtra("pendingIntent", getPendingIntent())
startActivity(intent)
} catch (e: Exception) {
// handle errors
}
}
private fun getPendingIntent(): PendingIntent? {
val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
val flags = PendingIntent.FLAG_IMMUTABLE
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
return PendingIntent.getActivity(application, 0, returnIntent, flags)
}
val options =
ActivityOptions.makeBasic()
.setPendingIntentCreatorBackgroundActivityStartMode(
ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
)
return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
}Waze (iOS)
Poniższy kod w języku Swift pokazuje przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami.
openWazeUrl(queryItems: [URLQueryItem(name: "q", value: "1600 Amphitheatre Parkway")])
private func openWazeUrl(queryItems: [URLQueryItem]) {
var components = URLComponents()
components.scheme = "https"
components.host = "waze.com"
components.path = "/ul"
// Create a mutable copy of the queryItems.
var mutableQueryItems = queryItems
// Add Trip Token
guard let tokenText = tokenField.text, !tokenText.isEmpty else {
return
}
let token = URLQueryItem(name: "external_trip_token", value: tokenText)
mutableQueryItems.append(token)
// Add compulsory params
mutableQueryItems.append(URLQueryItem(name: "navigate", value: "yes"))
// Construct and Launch URL
components.queryItems = mutableQueryItems
guard let url = components.url else {
return
}
UIApplication.shared.open(url, options: [:], completionHandler: nil)
}
}