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 przejazdu z sekcji Tworzenie przejazdu, 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 zapewnić kierowcom możliwość rozpoczęcia sesji nawigacji z poziomu aplikacji, utworzyć adres URL uruchamiania z wymaganymi parametrami i podać identyfikator aplikacji, aby przypisać sesję.
Zezwalanie kierowcom na rozpoczynanie nawigacji z poziomu aplikacji
Powinnaś zapewnić kierowcom możliwość rozpoczęcia nawigacji z poziomu aplikacji. Jeśli umożliwiasz kierowcom uruchamianie Map Google lub Waze za pomocą przycisku, zadbaj o odpowiednie oznaczenie i unikaj nieporozumień, wyraźnie go opisując. 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 przejazdu i wymagane parametry nawigacji. Działa podobnie do standardowego adresu URL Map Google lub precyzyjnego linku Waze.
Aby uruchomić Mapy Google lub Waze na urządzeniu kierowcy, użyj mechanizmu odpowiedniego dla danej platformy:
- Android: przekaż ciąg adresu URL w obiekcie
Intent. - iOS: użyj ciągu adresu URL jako uniwersalnego linku (lub precyzyjnego linku).
Formatowanie miejsca docelowego
Aby mieć pewność, że Mapy Google lub Waze będą mogły obliczyć trasę, podczas formatowania miejsca docelowego przestrzegaj tych zasad:
Określ dokładnie jedno osiągalne miejsce docelowe. Miejsce docelowe możesz przekazać 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 przekażesz wiele punktów pośrednich bezpośrednio w adresie URL, Mapy Google lub Waze wyświetlą błąd. Zamiast tego utwórz osobne podróże.
Dodawanie tokena przejazdu i parametrów nawigacji
Aby uzupełnić adres URL uruchamiania, musisz dołączyć uwierzytelniony token przejazdu otrzymany w odpowiedzi na żądanie Utwórz przejazd. Musisz też uwzględnić parametry nawigacji, które informują Mapy Google lub Waze o rozpoczęciu aktywnej nawigacji.
Mapy Google
W przypadku Map Google dodaj do adresu URL uruchamiania 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 miejsc docelowych:
-
Współrzędne geograficzne: szerokość/długość geograficzna
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 dodaj do adresu URL uruchamiania te parametry:
navigate=yes: ten parametr wymusza aktywną nawigację.external_trip_token: ten parametr dostarcza uwierzytelniony token przejazdu.
Poniższe przykłady pokazują, jak sformatować adres URL uruchamiania Waze przy użyciu różnych formatów miejsca docelowego:
-
Współrzędne geograficzne: szerokość/długość geograficzna
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ąć przejazd za pomocą Navigation Connect, musisz przypisać sesję nawigacji do aplikacji na Androidzie. Aby to zrobić, podaj zweryfikowany identyfikator aplikacji. Dzięki temu Mapy Google lub Waze będą mogły zidentyfikować Twoją aplikację jako źródło przejazdu i powiązać aktywną podróż 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: sprawdza, czy aplikacja ma uprawnienia do otrzymywania danych o aktywnej podróży.
- Włącz zgodę kierowcy: na ekranie zgody wyświetla się nazwa Twojej firmy i polityka prywatności, dzięki czemu kierowca wie, kto otrzymuje jego bieżącą lokalizację i szacowany czas dotarcia na miejsce.
- Włącz przycisk powrotu: umożliwia Mapom Google lub Waze utworzenie przycisku powrotu z logo marki, dzięki któremu kierowcy mogą 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.
Ten przykład pokazuje, jak dodać nazwę pakietu do intencji:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Jak umożliwić kierowcom powrót do aplikacji
Navigation Connect wyświetla dolny pasek (Mapy Google) lub przycisk Wstecz z logo (Waze), dzięki czemu kierowca może w każdej chwili podczas podróży lub po dotarciu do celu płynnie przełączyć się z powrotem do Twojej aplikacji.
Android
Musisz utworzyć element PendingIntent, który wskazuje aktywność aplikacji. Dołącz ten obiekt PendingIntent jako dodatek do intencji uruchomienia, używając dokładnego klucza "pendingIntent". Gdy użytkownik kliknie przycisk powrotu, Mapy Google lub Waze wykonają tę intencję, aby wyświetlić Twoją aplikację na pierwszym planie.
intent.putExtra("pendingIntent", getPendingIntent())iOS (tylko Waze)
Aby włączyć przycisk powrotu, nie musisz nic dodawać do adresu URL uruchamiania. Waze automatycznie używa uniwersalnego linku zarejestrowanego podczas weryfikacji aplikacji.
Przykładowe fragmenty kodu
Poniższe przykładowe kody 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 języku Kotlin pokazuje 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 języku Kotlin pokazuje 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 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)
}
}