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

כדי להתחיל את סשן הניווט, האפליקציה צריכה ליצור באופן דינמי כתובת 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}")

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

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

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