تشغيل "خرائط Google" أو Waze

لبدء جلسة التنقّل، يجب أن ينشئ تطبيقك بشكل ديناميكي عنوان URL للتشغيل من أجل فتح "خرائط Google" أو Waze. يوضّح هذا الدليل كيفية استخدام الرمز المميّز للرحلة الذي تم التحقّق من صحته من إنشاء رحلة لتشغيل "خرائط Google" أو Waze وضبط تجربة العودة إلى تطبيقك.

كيفية تشغيل "خرائط Google" أو Waze

لبدء "خرائط Google" أو Waze، يجب توفير طريقة تتيح للسائقين بدء جلسة تنقّل من تطبيقك، وإنشاء عنوان URL للبدء يتضمّن المَعلمات المطلوبة، وتقديم رقم تعريف تطبيقك لتحديد مصدر الجلسة.

السماح للسائقين ببدء التنقّل من تطبيقك

يجب أن توفّر طريقة تتيح للسائقين بدء التنقّل من تطبيقك. وإذا كنت تسمح للسائقين بتشغيل "خرائط Google" أو Waze باستخدام زر، احرص على توفير المصدر المناسب وتجنُّب حدوث أي التباس من خلال وضع تصنيف واضح للزر. على سبيل المثال، ضَع النص "خرائط Google" أو "ويز" على الزر أو بالقرب منه.

إنشاء عنوان 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، أضِف اسم الحزمة إلى هدف التشغيل (الذي يتضمّن سلسلة عنوان 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 تلقائيًا رابط Universal Link الذي سجّلته عند إثبات ملكية تطبيقك.

عيّنات تعليمات برمجية

توضّح عيّنات الرموز البرمجية التالية كيفية تشغيل "خرائط 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)
        }
       }