Google マップまたは Waze を起動する

ナビゲーション セッションを開始するには、アプリで Google マップまたは Waze を開くための起動 URL を動的に構築する必要があります。このガイドでは、乗車を作成するで取得した認証済み乗車トークンを使用して、Google マップまたは Waze を起動し、アプリに戻るエクスペリエンスを構成する方法について説明します。

Google マップまたは Waze を起動する方法

Google マップまたは Waze を起動するには、ドライバーがアプリからナビゲーション セッションを開始できるようにする方法を提供し、必要なパラメータを使用して起動 URL を作成し、セッションを帰属させるためのアプリケーション ID を指定する必要があります。

アプリからナビを開始できるようにする

ドライバーがアプリからナビゲーションを開始できるようにする必要があります。ボタンを使用して Google マップまたは Waze を起動できるようにする場合は、適切なアトリビューションを確保し、明確なラベル付けで混乱を避けてください。たとえば、「Google マップ」や「Waze」というテキストをボタンの上または近くに配置します。

起動 URL を作成する

ナビゲーション セッションを開始するには、Navigation Connect の起動 URL を作成します。この URL は、目的地、乗車トークン、必要なナビゲーション パラメータを含む文字列です。標準の Google マップの URL や Waze ディープリンクと同様に機能します。

重要: ナビゲーション接続は運転のみに対応しています。起動 URL で、運転以外の移動手段（徒歩、自転車、公共交通機関など）を設定しないでください。運転以外のモードでドライバーがナビゲーションを行う場合、Navigation Connect はテレメトリーの更新や交通情報を返しません。

運転者のデバイスで Google マップまたは Waze を起動するには、プラットフォーム固有のメカニズムを使用します。

• Android: Intent で URL 文字列を渡します。
• iOS: URL 文字列をユニバーサル リンク（またはディープリンク）として使用します。

宛先をフォーマットする

Google マップや Waze がルートを正しく計算できるように、目的地をフォーマットする際は次のルールに従ってください。

• 到達可能な宛先を 1 つだけ指定します。目的地は、住所文字列、緯度と経度の座標、プレイス ID として渡すことができます。

• 複数の経由地は使用しないでください。複数の経由地を URL で直接渡すと、Google マップまたは Waze にエラーが表示されます。代わりに、個別のルートを作成してください。

注: 起動 URL でカスタムの開始オリジンを渡さないでください。セッションが開始されると、Google マップまたは Waze はドライバーの現在地を自動的に使用します。「Origin not found」エラーを防ぐため、ドライバーに正確な位置情報の追跡を有効にするよう要求します。

乗車トークンとナビゲーション パラメータを追加

起動 URL を完成させるには、乗車ルートの作成リクエストから受け取った認証済みの乗車ルート トークンを含める必要があります。また、Google マップまたは Waze にアクティブなナビゲーションを開始するよう指示するナビゲーション パラメータも指定する必要があります。

Google マップ

Google マップの場合は、起動 URL に次のパラメータを含めます。

• dir_action=navigate: このパラメータはアクティブ ナビゲーションを強制します。
• action_token: このパラメータは、認証済みの乗車トークンを提供します。

次の例は、さまざまな宛先形式を使用して Google マップの起動 URL をフォーマットする方法を示しています。

• 緯度と経度の座標:

  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

• プレイス ID:

  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: このパラメータは、認証済みの乗車トークンを提供します。

次の例は、さまざまな宛先形式を使用して Waze の起動 URL をフォーマットする方法を示しています。

• 緯度と経度の座標:

  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

  注: Waze は、住所文字列の最初の検索結果に移動します。
• プレイス ID:

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

アプリケーション ID を指定する（Android のみ）

Android でナビゲーション セッションをアプリに帰属させるには、確認済みのアプリケーション ID を指定します。これにより、アプリがルートのソースとして識別され、Google マップまたは Waze でアクティブなルートをプラットフォームにリンクできるようになります。

注: iOS の場合、CreateTripRequest メッセージでアプリケーション ID を指定する必要があります。詳しくは、旅行を作成するをご覧ください。

アプリケーション ID を指定すると、次の機能が有効になります。

• データ共有を承認する: アプリがアクティブなルートデータを受信することを承認されていることを確認します。
• ドライバーの同意を有効にする: 同意画面にビジネスの名前とプライバシー ポリシーが表示され、ドライバーはリアルタイムの位置情報と到着予定時刻を誰が受け取っているかを確認できます。
• [戻るボタンを有効にする]: Google マップまたは Waze でブランドの戻るボタンを作成し、ドライバーがアプリに戻れるようにします。

Android でアプリケーション ID を Google マップまたは Waze に渡すには、Intent.EXTRA_REFERRER_NAME を使用して、起動インテント（起動 URL 文字列を保持）にパッケージ名を追加します。

次の例は、インテントにパッケージ名を追加する方法を示しています。

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

ドライバーがアプリに戻る方法

Navigation Connect は、ボトムバー（Google マップ）またはブランドの付いた [戻る] ボタン（Waze）を表示します。これにより、ドライバーは移動中や目的地に到着したときに、いつでもシームレスにアプリに戻ることができます。

Android

アプリのアクティビティに戻る PendingIntent を作成する必要があります。この PendingIntent を、正確なキー "pendingIntent" を使用して、起動インテントの追加としてアタッチします。ユーザーが戻るボタンをタップすると、Google マップまたは Waze がこのインテントを実行して、アプリをフォアグラウンドに表示します。

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

iOS（Waze のみ）

戻るボタンを有効にするために、起動 URL に何かを追加する必要はありません。Waze は、アプリを検証したときに登録したユニバーサル リンクを自動的に使用します。

コードサンプル

次のコードサンプルは、Navigation Connect を使用してアプリから Google マップまたは Waze を起動し、[アプリに戻る] ボタンを有効にする方法を示しています。

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