تشغيل "خرائط 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، أضِف اسم الحزمة إلى هدف الإطلاق (الذي يحمل سلسلة عنوان URL للإطلاق) باستخدام Intent.EXTRA_REFERRER_NAME.

يوضّح المثال التالي كيفية إضافة اسم الحزمة إلى الهدف:

intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")

كيفية السماح للسائقين بالعودة إلى تطبيقك

تطبيق "خرائط Google" مع شريط سفلي يتضمّن زر الرجوع واسم التطبيق ورمز مشاركة البيانات، على اليمين تطبيق Waze مع زر رجوع يحمل علامة تجارية، على اليسار

تعرض Navigation Connect شريطًا سفليًا (خرائط Google) أو زر الرجوع يحمل علامتك التجارية (Waze) ليتمكّن السائق من العودة بسلاسة إلى تطبيقك في أي وقت أثناء الرحلة أو عند وصوله إلى الوجهة.

Android

يجب إنشاء PendingIntent يشير إلى نشاط تطبيقك. أرفِق هذا PendingIntent كإضافة إلى هدف الإطلاق باستخدام المفتاح "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)
        }
       }