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 딥 링크와 비슷하게 작동합니다.

중요: Navigation Connect는 운전만 지원합니다. 실행 URL에서 운전 이외의 이동 모드 (예: 도보, 자전거, 대중교통)를 구성하지 마세요. 운전자가 운전 이외의 모드로 내비게이션하는 경우 Navigation Connect는 원격 분석 업데이트 또는 교통정보를 반환하지 않습니다.

운전자 기기에서 Google 지도 또는 Waze를 실행하려면 플랫폼별 메커니즘을 사용하세요.

• Android: Intent에서 URL 문자열을 전달합니다.
• iOS: URL 문자열을 범용 링크 (또는 딥 링크)로 사용합니다.

대상 형식 지정

Google 지도 또는 Waze에서 경로를 계산할 수 있도록 하려면 대상을 형식 지정할 때 다음 규칙을 준수하세요.

• 도착 가능한 대상을 정확히 하나 지정합니다. 대상을 주소 문자열, 위도/경도 좌표 또는 장소 ID로 전달할 수 있습니다.

• 경유지를 여러 개 사용하지 마세요. URL에서 직접 경유지를 여러 개 전달하면 Google 지도 또는 Waze에 오류가 표시됩니다. 대신 별도의 이동을 만드세요.

참고: 실행 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

  참고: 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의 경우 메시지에 애플리케이션 ID를 제공해야 합니다.CreateTripRequest 자세한 내용은 이동 만들기 를 참고하세요.

애플리케이션 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)
        }
       }