מפעילים את מפות Google או את Waze

כדי להתחיל את פעילות הניווט, האפליקציה צריכה ליצור באופן דינמי כתובת URL להפעלה כדי לפתוח את מפות Google או את Waze. במדריך הזה מוסבר איך להשתמש בטוקן מאומת של נסיעה מהשיטה Create a trip כדי להפעיל את מפות 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 להפעלת הנסיעה, צריך לכלול בה את אסימון הנסיעה המאומת שקיבלתם מהבקשה Create a trip. צריך גם לכלול את פרמטרי הניווט שמנחים את מפות 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 בלבד)

כדי לשייך פעילות ניווט לאפליקציה שלכם ב-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}")

איך מאפשרים לנהגים לחזור לאפליקציה שלכם

אפליקציית מפות Google עם סרגל תחתון שכולל את הכפתור "הקודם", שם האפליקציה וסמל שיתוף הנתונים, בצד ימין. אפליקציית Waze עם הכפתור "הקודם" ממותג, בצד ימין.

ב-Navigation Connect מוצג סרגל תחתון (מפות Google) או לחצן חזרה עם מיתוג (Waze), כך שהנהג יכול לחזור לאפליקציה שלכם בכל שלב במהלך הנסיעה או כשהוא מגיע ליעד.

Android

צריך ליצור PendingIntent שמפנה חזרה לפעילות באפליקציה. מצרפים את PendingIntent כתוספת ל-Intent של ההפעלה באמצעות המפתח המדויק "pendingIntent". כשהמשתמש מקיש על לחצן החזרה, אפליקציית מפות Google או Waze מבצעת את הכוונה הזו כדי להעביר את האפליקציה שלכם לחזית. 

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)
        }
       }