تشغيل "خرائط 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)
        }
       }