대형 차량 경로 탐색

참고: 대형 차량 경로 지정은 일부 고객에게만 제공됩니다. 관심을 표현하려면 Google에 문의하세요.

이 가이드는 다음을 대상으로 합니다. 트럭, 버스 또는 기타 대형 상용 차량 운전자를 위한 세부 경로 안내 환경을 구축하는 모바일 개발자라면 이 가이드를 읽어보세요.

이 가이드에서 다루는 내용: 이 가이드에서는 Routes API 또는 Route Optimization API에서 생성된 트럭 전용 경로를 가져와 iOS용 Navigation SDK를 사용하여 세부 경로 안내 세션을 지원하는 방법을 설명합니다.

학습할 내용

다음 작업을 실행하는 방법을 알아봅니다.

• routeToken 사용: 백엔드 경로 계획을 인앱 탐색 환경과 연결합니다.
• Navigation SDK 구성 : 미리 계획된 트럭 경로를 사용합니다.
• 트럭 전용 제한사항이 탐색 UI에서 운전자에게 표시되는 방식 을 이해합니다.

기본 요건

시작하기 전에 다음 요구사항을 충족하는지 확인하세요.

1. 프로젝트 액세스 권한 요청

대형 차량 경로 지정은 일부 고객에게만 제공됩니다. 관심을 표현하고 Google Cloud 프로젝트에 대한 액세스 권한을 요청하려면 문의 양식을 작성하세요. Google 담당자가 다음 단계에 관해 연락드릴 예정입니다.

Google에서 액세스 권한을 부여하면 Google Cloud 프로젝트가 대형 차량 경로 지정을 위해 프로비저닝되었는지 확인합니다.

조직에서 백엔드 경로 지정 API와 모바일 Navigation SDK에 별도의 Google Cloud 프로젝트를 사용하는 경우 Google에 문의하여 각 프로젝트를 프로비저닝하세요.

2. 백엔드 경로 생성을 설정하고 경로 토큰 가져오기

기기에서 탐색을 시작하기 전에 백엔드 서버에서 다음 API 중 하나를 사용하여 트럭 경로를 생성하고 routeToken을 가져와야 합니다.

• Routes API: 출발지와 도착지 간의 단일 트럭 경로를 계산하는 데 권장됩니다. 설정 안내는 대형 차량 경로 및 예상 도착 시간 생성을 참고하세요.
• Route Optimization API: 다중 경유지 경로를 최적화하는 데 권장됩니다. 차량 전체. 자세한 내용은 Route Optimization API 대형 차량 경로 지정 가이드를 참고하세요.

백엔드 요청은 차량의 물리적 속성 (높이, 너비, 길이, 무게, 차축 수, 위험물 화물)과 함께 travelMode: TRUCK을 지정해야 합니다. 경로 지정 API는 응답에서 routeToken을 반환하며, 백엔드 서버는 이를 모바일 앱에 전달합니다.

3. 최소 SDK 및 시스템 요구사항 충족

앱은 최소 필수 Navigation SDK 버전 5.4.0 이상을 사용해야 합니다.

또한 프로젝트는 표준 Navigation SDK 설정 요구사항을 충족해야 합니다.

제한사항 및 운영 가이드라인

시작하기 전에 다음 제한사항 및 운영 가이드라인에 유의하세요.

• 지리적 가용성: 대형 차량 경로 지정은 미국 본토 48개 주 (정식 버전)와 일본 (실험용)에서 사용할 수 있습니다. 알래스카, 하와이 또는 미국령에서는 사용할 수 없습니다.
• 운전자 권고 및 안전: 운전자는 Navigation SDK에서 반환된 경로에만 의존하여 안전하거나 합법적이라고 생각해서는 안 됩니다. 경로는 모든 도로 상태에서 차량에 적합하지 않을 수 있으며, 경로를 따르는 경우 운전자가 낮은 통과 높이 또는 무게 제한 도로와 같은 위험에 노출될 수 있습니다. 운전자는 항상 주의를 기울이고 게시된 도로 표지판과 현지 규정을 준수해야 합니다.
• 최선을 다한 경로: 경로 지정 API에서 차량 제한사항을 완전히 준수하는 경로를 찾을 수 없는 경우 제한된 구간을 여전히 통과할 수 있는 "최선을 다한" 경로를 반환합니다. 예를 들어 Routes API는 응답에서 routeRestrictionsPartiallyIgnored 플래그를 설정합니다. 이러한 경로를 탐색할 때 Navigation SDK는 관련 제한사항을 강조하기 위해 경로 콜아웃을 표시합니다. 이러한 경우 경로를 신중하게 계획하고 플래그가 지정된 경로를 계획 또는 탐색의 단일 정보 소스로 사용하지 마세요.
• 지원되지 않는 기능: 대형 차량 경로 지정은 다음 기능을 지원하지 않습니다.
  • 트럭 통행료 가격 책정
  • 트럭 또는 대형 차량 전용 제한속도
  • 방사성 위험물의 경로 지정
• 사용량 한도: Navigation SDK에 대한 요청은 표준 사용량 및 할당량 한도를 따릅니다. 자세한 내용은 사용량 및 결제를 참고하세요.

트럭 전용 UI (경로 콜아웃) 표시

Navigation SDK는 지도에 경로 콜아웃이라는 시각적 경고를 자동으로 표시하여 운전자에게 다가오는 트럭 제한사항을 알립니다. 콜아웃은 계획된 경로를 따라 발생하는 제한사항에 대해 표시되지만 다른 인근 도로에는 표시되지 않습니다.

Navigation SDK에는 다음 제한사항에 대한 콜아웃이 포함되어 있습니다.

제한사항	콜아웃 아이콘 및 텍스트	표시 조건
키	노란색 = 경고, 차량이 허용된 최대 높이에 가까움 빨간색 = 차량이 허용된 최대 높이보다 높음	차량의 높이가 제한사항에 가까워지면 노란색 콜아웃이 표시됩니다. 경로가 규정을 준수하지 않고 높이 제한을 위반하는 경우 빨간색 콜아웃이 표시됩니다.
무게		차량의 무게가 도로의 제한을 초과하면 빨간색 콜아웃이 표시됩니다.
트럭 금지		상용 트럭 제한이 있는 도로 구간을 이동할 때 빨간색 콜아웃이 표시됩니다.
위험물		차량의 위험물 적재가 도로 구간에서 금지된 경우 빨간색 콜아웃이 표시됩니다.

경로 토큰의 작동 방식

routeToken은 Google의 경로 지정 백엔드에서 생성된 경로의 암호화된 스냅샷입니다. 계획된 경로 도형과 차량의 물리적 크기 및 제한사항 프로필을 캡슐화합니다.

워크플로는 다음 단계를 따릅니다.

1. 경로 요청: 백엔드 서버가 Routes API (또는 Route Optimization API)에서 트럭 경로를 요청합니다.
2. 토큰 수신: 경로 지정 API가 규정을 준수하는 경로를 계산하고 routeToken을 백엔드 서버에 반환합니다.
3. 토큰 전달: 백엔드 서버가 routeToken 및 도착지 좌표를 모바일 앱에 전달합니다.
4. SDK에 전달: 모바일 앱이 routeToken을(를) Navigation SDK에 전달합니다.
5. 안내 시작: Navigation SDK는 세부 경로 안내 환경의 모든 측면을 처리합니다. 여기에는 경로 콜아웃 렌더링 및 차량의 제한사항에 따른 동적 경로 재지정 처리가 포함됩니다.

동적 재계산 및 경로 재지정

활성 탐색 중에 교통 상황, 도로 폐쇄 또는 놓친 회전으로 인해 차량이 계획된 경로에서 벗어날 수 있습니다.

경로 재지정이 발생하면 다음이 실행됩니다.

• Navigation SDK가 도착지까지의 경로를 자동으로 재계산합니다.
• SDK는 원래 routeToken에 인코딩된 차량 속성 및 크기를 유지합니다.
• 새로 재계산된 경로는 낮은 통과 높이, 무게 제한 다리, 상용 트럭이 금지된 도로를 피합니다.

구현: 트럭 전용 이동 시작

다음 단계에 따라 대형 차량 경로 토큰으로 세부 경로 안내 내비게이션을 초기화하고 시작합니다.

1단계: 백엔드에서 경로 토큰 가져오기

모바일 앱은 백엔드 서버에서 도착지 좌표와 함께 routeToken 문자열을 수신합니다. 서버에서 이 토큰을 생성하는 방법에 관한 자세한 내용은 대형 차량 경로 및 예상 도착 시간 생성 을 Routes API 문서에서 참고하세요.

다음 코드는 경로 토큰의 예입니다.

{
  "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}

2단계: 토큰을 Navigator에 전달

routeToken 및 도착지 경유지를 mapView.navigator setDestinations 메서드에 전달합니다.

경유지를 구성하고 경로 토큰을 전달할 때는 다음 고려사항에 유의하세요.

• 도착지 일치 요구사항: setDestinations에 전달된 도착지 좌표는 을 생성할 때 사용된 도착지 좌표와 일치해야 합니다.routeToken 다른 도착지를 지정하면 오류가 발생합니다.
• 도로 측면 경로 지정: 대형 상용 차량은 좁은 도로에서 쉽게 유턴할 수 없습니다. 트럭이 도로의 올바른 측면에서 도착지에 접근하도록 하려면 경유지에서 preferSameSideOfRoad = true를 설정하세요.
• 차량 정차: 트럭을 정차 또는 하역에 적합한 위치로 안내하려면 경유지에서 vehicleStopover = true를 설정하세요.
• 탐색 지점: 도착지에 지정된 화물 입구 또는 하역장이 있는 경우 탐색 지점 토큰을 사용하여 지정합니다.

3단계: 경로 상태 처리 및 안내 시작

setDestinations 콜백에서 반환된 GMSRouteStatus를 평가합니다. 상태가 .OK (GMSRouteStatusOK)이면 isGuidanceActive = true(guidanceActive = YES)를 설정하여 활성 세부 경로 안내를 시작합니다.

코드 예

경로 토큰을 만들 때 사용한 것과 동일한 도착지 경유지를 지정하여 mapView.navigator setDestinations 메서드를 사용하여 경로 토큰을 Navigation SDK에 전달합니다.

// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

차량 내 디스플레이

CarPlay용 내비게이션을 사용하여 대형 차량 탐색 세션을 대시보드 화면에 표시할 수 있습니다.

다음 단계

• 탐색 UI 수정: 기본 제공 UI 컨트롤 및 시각적 요소(예: 나침반, 재설정 버튼, 카메라 시점)를 맞춤설정합니다.
• 탐색 이벤트 수신 대기: 경로 진행률, 도착예정시간 변경, 경로 재지정 등 탐색 업데이트 및 수명 주기 이벤트를 처리합니다.