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

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

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

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

ドライバーがアプリからナビゲーションを開始できるようにする

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

起動 URL を作成する

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

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

  • Android: Intent で URL 文字列を渡します。
  • 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 のみ)

Navigation Connect でトリップを開始するには、Android でナビゲーション セッションをアプリに割り振る必要があります。そのためには、確認済みのアプリケーション ID を指定します。これにより、アプリがルートのソースとして識別され、Google マップまたは Waze がアクティブなルートをプラットフォームにリンクできるようになります。アプリケーション ID がないか無効な場合、ルート トークンの認証に失敗します。

アプリケーション 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)
        }
       }