Membuka Google Maps atau Waze

Untuk memulai sesi navigasi, aplikasi Anda harus membuat URL peluncuran secara dinamis untuk membuka Google Maps atau Waze. Panduan ini menjelaskan cara menggunakan token perjalanan yang diautentikasi dari Buat perjalanan untuk meluncurkan Google Maps atau Waze dan mengonfigurasi pengalaman kembali ke aplikasi Anda.

Cara meluncurkan Google Maps atau Waze

Untuk meluncurkan Google Maps atau Waze, Anda harus menyediakan cara agar pengemudi dapat memulai sesi navigasi dari aplikasi Anda, membuat URL peluncuran dengan parameter yang diperlukan, dan memberikan ID aplikasi Anda untuk mengatribusikan sesi.

Mengizinkan pengemudi memulai navigasi dari aplikasi Anda

Anda harus menyediakan cara bagi pengemudi untuk memulai navigasi dari aplikasi Anda. Jika Anda mengizinkan pengemudi meluncurkan Google Maps atau Waze menggunakan tombol, pastikan atribusi yang tepat dan hindari kebingungan dengan memberi label yang jelas. Misalnya, tempatkan teks "Google Maps" atau "Waze" di atau di dekat tombol.

Buat URL peluncuran

Untuk memulai sesi navigasi, buat URL peluncuran Navigation Connect. URL ini adalah string yang berisi tujuan, token perjalanan, dan parameter navigasi yang diperlukan. Fungsinya mirip dengan URL Google Maps standar atau Deep Link Waze.

Untuk meluncurkan Google Maps atau Waze di perangkat pengemudi, gunakan mekanisme khusus platform:

• Android: Teruskan string URL dalam Intent.
• iOS: Gunakan string URL sebagai Link Universal (atau deep link).

Memformat tujuan

Untuk memastikan Google Maps atau Waze dapat menghitung rute dengan berhasil, patuhi aturan berikut saat memformat tujuan Anda:

• Tentukan tepat satu tujuan yang dapat dijangkau. Anda dapat meneruskan tujuan sebagai string alamat, koordinat lintang/bujur, atau ID tempat.

• Jangan gunakan beberapa titik jalan. Jika Anda meneruskan beberapa titik jalan langsung di URL, Google Maps atau Waze akan menampilkan error. Sebagai gantinya, buat perjalanan terpisah.

Catatan: Jangan teruskan origin awal kustom di URL peluncuran. Google Maps atau Waze otomatis menggunakan lokasi pengemudi saat ini saat sesi dimulai. Untuk mencegah error "Asal tidak ditemukan", minta pengemudi Anda untuk mengaktifkan pelacakan lokasi presisi.

Menambahkan token perjalanan dan parameter navigasi

Untuk melengkapi URL peluncuran, Anda harus menyertakan token perjalanan yang diautentikasi yang Anda terima dari permintaan Buat perjalanan. Anda juga harus menyertakan parameter navigasi yang memberi tahu Google Maps atau Waze untuk memulai navigasi aktif.

Google Maps

Untuk Google Maps, sertakan parameter berikut dalam URL peluncuran Anda:

• dir_action=navigate: Parameter ini memaksa navigasi aktif.
• action_token: Parameter ini menyediakan token perjalanan terautentikasi Anda.

Contoh berikut menunjukkan cara memformat URL peluncuran untuk Google Maps menggunakan format tujuan yang berbeda:

• Koordinat lintang/bujur:

  https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN

• String alamat:

  https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN

• ID Tempat:

  https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

Untuk Waze, sertakan parameter berikut dalam URL peluncuran Anda:

• navigate=yes: Parameter ini memaksa navigasi aktif.
• external_trip_token: Parameter ini menyediakan token perjalanan terautentikasi Anda.

Contoh berikut menunjukkan cara memformat URL peluncuran untuk Waze menggunakan format tujuan yang berbeda:

• Koordinat lintang/bujur:

  https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN

• String alamat:

  https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN

  Catatan: Waze menavigasi ke hasil penelusuran pertama untuk string alamat.
• ID Tempat:

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Berikan ID aplikasi Anda (khusus Android)

Untuk mengatribusikan sesi navigasi ke aplikasi Anda di Android, berikan ID aplikasi terverifikasi Anda. Hal ini mengidentifikasi aplikasi Anda sebagai sumber perjalanan sehingga Google Maps atau Waze dapat menautkan perjalanan aktif kembali ke platform Anda.

Catatan: Untuk iOS, Anda seharusnya memberikan ID aplikasi dalam pesan CreateTripRequest. Lihat Membuat perjalanan untuk mengetahui detailnya.

Dengan memberikan ID aplikasi, Anda dapat menggunakan fitur berikut:

• Mengizinkan berbagi data: Memverifikasi bahwa aplikasi Anda diizinkan untuk menerima data perjalanan aktif.
• Aktifkan izin pengemudi: Mengisi layar izin dengan nama bisnis dan kebijakan privasi Anda, sehingga pengemudi mengetahui siapa yang menerima lokasi real-time dan perkiraan waktu tiba mereka.
• Mengaktifkan tombol kembali: Memungkinkan Google Maps atau Waze membuat tombol kembali bermerek sehingga pengemudi dapat beralih kembali ke aplikasi Anda.

Untuk meneruskan ID aplikasi ke Google Maps atau Waze di Android, tambahkan nama paket Anda ke intent peluncuran (yang membawa string URL peluncuran) menggunakan Intent.EXTRA_REFERRER_NAME.

Contoh berikut menunjukkan cara menambahkan nama paket ke intent:

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

Cara mengizinkan pengemudi kembali ke aplikasi Anda

Navigation Connect menampilkan panel bawah (Google Maps) atau tombol kembali bermerek (Waze) sehingga pengemudi dapat beralih kembali ke aplikasi Anda dengan lancar kapan saja selama perjalanan atau saat mereka tiba di tujuan.

Android

Anda harus membuat PendingIntent yang mengarah kembali ke aktivitas aplikasi Anda. Lampirkan PendingIntent ini sebagai ekstra ke peluncuran intent menggunakan kunci "pendingIntent" yang sama persis. Saat pengguna mengetuk tombol kembali, Google Maps atau Waze akan menjalankan intent ini untuk menampilkan aplikasi Anda di latar depan.

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

iOS (Khusus Waze)

Anda tidak perlu menambahkan apa pun ke URL peluncuran untuk mengaktifkan tombol kembali. Waze secara otomatis menggunakan Link Universal yang Anda daftarkan saat Anda memverifikasi aplikasi Anda.

Contoh kode

Contoh kode berikut menunjukkan cara meluncurkan Google Maps atau Waze dari aplikasi Anda menggunakan Navigation Connect dan mengaktifkan tombol "Kembali ke aplikasi".

Google Maps (Android)

Kode Kotlin berikut menunjukkan contoh fungsi yang meluncurkan sesi Navigation Connect dengan parameter yang diperlukan.

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)

Kode Kotlin berikut menunjukkan contoh fungsi yang meluncurkan sesi Navigation Connect dengan parameter yang diperlukan.

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)

Kode Swift berikut menunjukkan contoh fungsi yang meluncurkan sesi Navigation Connect dengan parameter yang diperlukan.

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