راه‌اندازی Google Maps یا Waze

برای شروع جلسه ناوبری، برنامه‌تان باید به‌طور پویا نشانی وب راه‌اندازی بسازد تا Google Maps یا Waze را باز کند. این راهنما شرح می‌دهد چگونه از کد سفر اصالت‌سنجی‌شده از ایجاد سفر برای راه‌اندازی Google Maps یا Waze استفاده کنید و تجربه بازگشت به برنامه‌تان را پیکربندی کنید.

نحوه راه‌اندازی Google Maps یا Waze

برای راه‌اندازی Google Maps یا Waze، باید روشی ارائه دهید که به رانندگان اجازه دهد جلسه ناوبری را از برنامه شما شروع کنند، نشانی وب راه‌اندازی را با پارامترهای لازم بسازید، و شناسه برنامه‌تان را برای نسبت دادن جلسه ارائه دهید.

به رانندگان اجازه دهید ناوبری را از برنامه‌تان شروع کنند

باید راهی برای رانندگان فراهم کنید تا بتوانند ناوبری را از برنامه‌تان شروع کنند. اگر به رانندگان اجازه می‌دهید Google Maps یا Waze را بااستفاده از دکمه‌ای راه‌اندازی کنند، از ارجاع مناسب مطمئن شوید و با برچسب‌گذاری واضح از سردرگمی جلوگیری کنید. برای مثال، نوشتار «Google Maps» یا «Waze» را روی دکمه یا نزدیک آن قرار دهید.

ساختن نشانی وب راه‌اندازی

برای شروع جلسه ناوبری، نشانی وب راه‌اندازی Navigation Connect را بسازید. این نشانی وب رشته‌ای است که شامل مقصد، کد سفر، و پارامترهای ناوبری موردنیاز است. عملکرد آن مشابه نشانی وب Google Maps استاندارد یا پیوند عمیق Waze است.

برای راه‌اندازی Google Maps یا Waze در دستگاه راننده، از سازوکار مختص پلاتفرم استفاده کنید:

  • Android: رشته نشانی وب را در Intent ارسال کنید.
  • iOS: از رشته نشانی وب به‌عنوان «پیوند جامع» (یا پیوند عمیق) استفاده کنید.

قالب‌بندی مقصد

برای اطمینان از اینکه Google Maps یا Waze می‌توانند مسیر را با موفقیت محاسبه کنند، هنگام قالب‌بندی مقصد خود از قوانین زیر پیروی کنید:

  • دقیقاً یک مقصد قابل‌دسترس را مشخص کنید. می‌توانید مقصد را به‌صورت رشته نشانی، مختصات عرض جغرافیایی/طول جغرافیایی، یا شناسه مکان ارسال کنید.

  • از چند نقطه‌مسیر استفاده نکنید. اگر چند نقطه‌مسیر را مستقیماً در نشانی وب رد کنید، Google Maps یا Waze خطایی را نمایش می‌دهد. درعوض، سفرهای جداگانه ایجاد کنید.

افزودن کد سفر و پارامترهای پیمایش

برای تکمیل نشانی وب راه‌اندازی، باید کد سفر اصالت‌سنجی‌شده‌ای را که از درخواست ایجاد سفر دریافت کرده‌اید اضافه کنید. همچنین باید پارامترهای ناوبری را که به Google Maps یا Waze می‌گوید ناوبری فعال را شروع کند اضافه کنید.

Google Maps

برای Google Maps، پارامترهای زیر را در نشانی وب راه‌اندازی‌تان اضافه کنید:

  • dir_action=navigate: این پارامتر ناوبری فعال را اجباری می‌کند.
  • action_token: این پارامتر نماد سفر اصالت‌سنجی‌شده شما را ارائه می‌دهد.

مثال‌های زیر نشان می‌دهد که چگونه نشانی وب راه‌اندازی Google Maps را بااستفاده از قالب‌های مقصد مختلف قالب‌بندی کنید:

  • مختصات طول/عرض جغرافیایی:
    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، پارامترهای زیر را در نشانی وب راه‌اندازی‌تان بگنجانید:

  • navigate=yes: این پارامتر ناوبری فعال را اجباری می‌کند.
  • external_trip_token: این پارامتر نماد سفر اصالت‌سنجی‌شده شما را ارائه می‌دهد.

مثال‌های زیر نشان می‌دهند که چگونه می‌توان نشانی وب راه‌اندازی را برای 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 Maps یا Waze بتوانند سفر فعال را به پلاتفرم شما پیوند دهند. نبودن شناسه برنامه یا نامعتبر بودن آن منجر به ناموفق بودن اصالت‌سنجی کد سفر می‌شود.

با ارائه شناسه برنامه، ویژگی‌های زیر فعال می‌شود:

  • مجاز کردن هم‌رسانی داده: تأیید می‌کند که برنامه شما برای دریافت داده‌های سفر فعال مجاز است.
  • فعال کردن رضایت راننده: صفحه رضایت را با نام کسب‌وکار و خط‌مشی رازداری شما پر می‌کند تا راننده بداند چه کسی مکان هم‌زمان و زمان تخمینی ورود او را دریافت می‌کند.
  • فعال کردن دکمه برگشت: به Google Maps یا Waze امکان می‌دهد دکمه برگشت با نمانام بسازد تا رانندگان بتوانند به برنامه شما برگردند.

برای ارسال شناسه برنامه به Google Maps یا Waze در Android، نام بسته‌تان را بااستفاده از Intent.EXTRA_REFERRER_NAME به هدف راه‌اندازی (که رشته نشانی وب راه‌اندازی را حمل می‌کند) اضافه کنید.

مثال زیر نحوه افزودن نام بسته به قصد را نشان می‌دهد:

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

نحوه اجازه دادن به رانندگان برای بازگشت به برنامه شما

برنامه Google Maps با نوار پایینی که دکمه برگشت، نام برنامه، و نماد هم‌رسانی داده را در سمت راست دارد. برنامه Waze با دکمه برگشتن نمانام‌دار، در سمت راست.

Navigation Connect نوار پایینی (Google Maps) یا دکمه برگشتن نمانام‌دار (Waze) را نمایش می‌دهد تا راننده بتواند در هر نقطه‌ای از سفر یا هنگام رسیدن به مقصد، به‌طور یکپارچه به برنامه شما برگردد.

Android

باید PendingIntent ایجاد کنید که به فعالیت برنامه‌تان اشاره کند. این PendingIntent را به‌عنوان یک مورد اضافی به هدف راه‌اندازی بااستفاده از کلید دقیق "pendingIntent" پیوست کنید. وقتی کاربر روی دکمه بازگشت ضربه می‌زند، Google Maps یا Waze این هدف را اجرا می‌کند تا برنامه شما را به پیش‌زمینه بیاورد.

intent.putExtra("pendingIntent", getPendingIntent())

iOS (فقط Waze)

برای فعال کردن دکمه بازگشت، لازم نیست چیزی به نشانی وب راه‌اندازی اضافه کنید. Waze به‌طور خودکار از «پیوند جامعی» که هنگام درستی‌سنجی برنامه‌تان ثبت کرده‌اید استفاده می‌کند.

نمونه‌های کد

نمونه کدهای زیر نشان می‌دهند که چگونه Google Maps یا Waze را از برنامه‌تان بااستفاده از Navigation Connect راه‌اندازی کنید و دکمه «بازگشت به برنامه» را فعال کنید.

Google Maps (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)
        }
       }