מפעילים את מפות 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.

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

כדי להפעיל את מפות Google או את Waze במכשיר של הנהג, משתמשים במנגנון הספציפי לפלטפורמה:

• ‫Android: מעבירים את מחרוזת כתובת ה-URL ב-Intent.
• ‫iOS: השתמשו במחרוזת כתובת ה-URL כקישור אוניברסלי (או כקישור עומק).

עיצוב היעד

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

• צריך לציין בדיוק יעד אחד שאפשר להגיע אליו. אפשר להעביר את היעד כמחרוזת כתובת, כקואורדינטות של קו אורך וקו רוחב או כמזהה מקום.

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

הערה: אל תעבירו מקור התחלה מותאם אישית בכתובת ה-URL להפעלה. מפות Google או Waze משתמשות אוטומטית במיקום הנוכחי של הנהג כשהסשן מתחיל. כדי למנוע שגיאות מסוג 'מקור לא נמצא', צריך לדרוש מהנהגים להפעיל מעקב מדויק אחר המיקום.

הוספת טוקן נסיעה ופרמטרים של ניווט

כדי להשלים את כתובת ה-URL להפעלה, צריך לכלול בה את אסימון הנסיעה המאומת שקיבלתם מהבקשה Create a trip. צריך גם לכלול את פרמטרי הניווט שמנחים את מפות Google או את Waze להתחיל ניווט פעיל.

מפות Google

במקרה של Google Maps, צריך לכלול את הפרמטרים הבאים בכתובת ה-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

  הערה: Waze מנווט לתוצאת החיפוש הראשונה של מחרוזות כתובות.
• מזהה מקום:

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

צריך לציין את מזהה האפליקציה (ב-Android בלבד)

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

הערה: במערכת iOS, צריך לציין את מזהה האפליקציה בהודעה CreateTripRequest. פרטים נוספים זמינים במאמר בנושא יצירת נסיעה.

כשמספקים את מזהה האפליקציה, אפשר להשתמש בתכונות הבאות:

• אישור שיתוף הנתונים: מוודא שהאפליקציה שלכם מורשית לקבל נתונים של נסיעות פעילות.
• הפעלת הסכמה של הנהג: במסך ההסכמה יופיעו שם העסק ומדיניות הפרטיות שלו, כדי שהנהג ידע מי מקבל את המיקום בזמן אמת ואת זמן ההגעה המשוער שלו.
• הפעלת לחצן החזרה: מאפשרת למפות Google או ל-Waze ליצור לחצן חזרה ממותג, כדי שהנהגים יוכלו לחזור לאפליקציה שלכם.

כדי להעביר את מזהה האפליקציה אל Google Maps או אל 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.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)
        }
       }