כדי להתחיל את סשן הניווט, האפליקציה צריכה ליצור באופן דינמי כתובת URL להפעלה כדי לפתוח את מפות Google או את Waze. במדריך הזה מוסבר איך להשתמש באסימון הנסיעה המאומת מיצירת נסיעה כדי להפעיל את מפות Google או את Waze, ולהגדיר את חוויית החזרה לאפליקציה שלכם.
איך מפעילים את מפות Google או את Waze
כדי להפעיל את מפות Google או את Waze, אתם צריכים לספק דרך שתאפשר לנהגים להתחיל סשן ניווט מהאפליקציה שלכם, ליצור את כתובת ה-URL להפעלה עם הפרמטרים הנדרשים ולספק את מזהה האפליקציה כדי לשייך את הסשן.
איך מאפשרים לנהגים להתחיל ניווט מהאפליקציה
אתם צריכים לספק לנהגים דרך להתחיל את הניווט מהאפליקציה שלכם. אם אתם מאפשרים לנהגים להפעיל את מפות Google או את Waze באמצעות כפתור, הקפידו על שיוך נכון והימנעו מבלבול על ידי תיוג ברור. לדוגמה, אפשר להציב את הטקסט "מפות Google" או "Waze" על הכפתור או לידו.
יצירת כתובת ה-URL להפעלה
כדי להתחיל סשן ניווט, צריך ליצור כתובת URL להפעלה של Navigation Connect. כתובת ה-URL הזו היא מחרוזת שמכילה את היעד, את אסימון הנסיעה ואת הפרמטרים הנדרשים לניווט. הוא פועל באופן דומה לכתובת URL רגילה של מפות Google או לקישור עומק של Waze.
כדי להפעיל את מפות Google או את Waze במכשיר של הנהג, משתמשים במנגנון הספציפי לפלטפורמה:
- Android: מעבירים את מחרוזת כתובת ה-URL ב-
Intent. - iOS: משתמשים במחרוזת של כתובת ה-URL כקישור אוניברסלי (או קישור עומק).
עיצוב היעד
כדי לוודא שמפות Google או Waze יוכלו לחשב מסלול, צריך לפעול לפי הכללים הבאים כשמזינים את היעד:
צריך לציין בדיוק יעד אחד שאפשר להגיע אליו. אפשר להעביר את היעד כמחרוזת של כתובת, קואורדינטות של קו רוחב/קו אורך או מזהה מקום.
אל תשתמשו בכמה נקודות ציון. אם תעבירו כמה נקודות ציון ישירות בכתובת ה-URL, תוצג שגיאה במפות Google או ב-Waze. במקום זאת, צריך ליצור נסיעות נפרדות.
הוספת אסימון נסיעה ופרמטרים של ניווט
כדי להשלים את כתובת ה-URL להפעלה, צריך לכלול את אסימון הנסיעה המאומת שקיבלתם מהבקשה יצירת נסיעה. אתם צריכים גם לכלול את הפרמטרים של הניווט שמורים למפות Google או ל-Waze להתחיל ניווט פעיל.
מפות Google
במפות Google, צריך לכלול את הפרמטרים הבאים בכתובת ה-URL להפעלה:
-
dir_action=navigate: הפרמטר הזה מאלץ ניווט פעיל. -
action_token: הפרמטר הזה מספק את אסימון הנסיעה המאומת.
הדוגמאות הבאות מראות איך להגדיר את הפורמט של כתובת ה-URL להפעלה של מפות Google באמצעות פורמטים שונים של יעדים:
-
קואורדינטות של קו הרוחב/קו האורך:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
מחרוזת הכתובת:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
מזהה מקום:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
ב-Waze, צריך לכלול את הפרמטרים הבאים בכתובת ה-URL להפעלה:
-
navigate=yes: הפרמטר הזה מאלץ ניווט פעיל. -
external_trip_token: הפרמטר הזה מספק את אסימון הנסיעה המאומת.
הדוגמאות הבאות מראות איך להגדיר את הפורמט של כתובת ה-URL להפעלת Waze באמצעות פורמטים שונים של יעדים:
-
קואורדינטות של קו רוחב/קו אורך:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
מחרוזת הכתובת:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
מזהה מקום:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
מזהה האפליקציה (ב-Android בלבד)
כדי להתחיל נסיעה עם Navigation Connect, צריך לשייך סשן ניווט לאפליקציה ב-Android. כדי לעשות את זה, צריך לספק את מזהה האפליקציה המאומת. הפרמטר הזה מזהה את האפליקציה כמקור הנסיעה, כדי שמפות Google או Waze יוכלו לקשר את הנסיעה הפעילה חזרה לפלטפורמה שלכם. אם מזהה האפליקציה חסר או לא תקין, האימות של אסימון הנסיעה ייכשל.
אם תספקו את מזהה האפליקציה, תוכלו להשתמש בתכונות הבאות:
- אישור שיתוף נתונים: מוודא שהאפליקציה שלכם מורשית לקבל נתונים של נסיעות פעילות.
- הפעלת הסכמת הנהג: מאכלסת את מסך ההסכמה בשם העסק ובמדיניות הפרטיות שלכם, כדי שהנהג יידע מי מקבל את המיקום שלו בזמן אמת ואת זמן ההגעה המשוער.
- הפעלת כפתור החזרה: מאפשרת למפות Google או ל-Waze ליצור כפתור חזרה ממותג כדי שהנהגים יוכלו לחזור לאפליקציה שלכם.
כדי להעביר את מזהה האפליקציה למפות Google או ל-Waze ב-Android, מוסיפים את שם החבילה ל-Intent ההפעלה (שמכיל את מחרוזת כתובת ה-URL להפעלה) באמצעות Intent.EXTRA_REFERRER_NAME.
בדוגמה הבאה אפשר לראות איך מוסיפים את שם החבילה ל-Intent:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
איך לאפשר לנהגים לחזור לאפליקציה שלכם
ב-Navigation Connect מוצג סרגל תחתון (מפות Google) או הכפתור "הקודם" ממותג (Waze) כדי שהנהג יוכל לחזור לאפליקציה שלכם בצורה חלקה בכל שלב במהלך הנסיעה או כשהוא מגיע ליעד.
Android
צריך ליצור PendingIntent שמפנה חזרה לפעילות של האפליקציה. מצרפים את ה-PendingIntent הזה כתוספת ל-intent ההפעלה באמצעות המפתח המדויק "pendingIntent". כשהמשתמש לוחץ על כפתור החזרה, מפות Google או Waze מפעילות את ה-Intent הזה כדי להעביר את האפליקציה לחזית.
intent.putExtra("pendingIntent", getPendingIntent())iOS (רק ב-Waze)
לא צריך להוסיף שום דבר לכתובת ה-URL להפעלה כדי להפעיל את כפתור החזרה. אפליקציית Waze משתמשת באופן אוטומטי בקישור האוניברסלי שרשמתם כשאימתתם את האפליקציה.
דוגמאות קוד
דוגמאות הקוד הבאות מראות איך להפעיל את מפות Google או את Waze מהאפליקציה שלכם באמצעות Navigation Connect ולהפעיל את הכפתור "חזרה לאפליקציה".
מפות Google (ל-Android)
קוד Kotlin הבא מציג פונקציה לדוגמה שמפעילה סשן של Navigation Connect עם הפרמטרים הנדרשים.
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)
קוד Kotlin הבא מציג פונקציה לדוגמה שמפעילה סשן של Navigation Connect עם הפרמטרים הנדרשים.
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)
קוד ה-Swift הבא מציג פונקציה לדוגמה שמפעילה סשן של Navigation Connect עם הפרמטרים הנדרשים.
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)
}
}