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 ディープリンクと同様に機能します。

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

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

目的地の形式を設定する

Google マップまたは Waze でルートを正しく計算できるようにするには、目的地の形式を設定する際に次のルールに従ってください。

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

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

ルートトークンとナビゲーション パラメータを追加する

起動 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
  • プレイス ID: 
    https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

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

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

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

  • データ共有を承認する: アプリがアクティブなルートデータを受信することを承認します。
  • ドライバーの同意を有効にする: 同意画面にビジネス名とプライバシー ポリシーを入力し、ドライバーがリアルタイムの位置情報と到着予定時刻を受信するユーザーを把握できるようにします。
  • 戻るボタンを有効にする: Google マップまたは Waze でブランド設定された戻るボタンを作成し、ドライバーがアプリに戻れるようにします。

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

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

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 は、アプリの確認時に登録したユニバーサル リンクを自動的に使用します。

コードサンプル

次のコードサンプルは、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)
        }
       }