라스트 마일 Fleet 솔루션은 현재 일부 고객에게만 제공됩니다. 자세한 내용은 영업팀에 문의하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

자바스크립트 배송 추적 라이브러리로 배송 추적

JavaScript 배송 추적 라이브러리를 사용하면 Fleet Engine에서 추적된 차량 위치 및 관심 위치를 시각화할 수 있습니다. 라이브러리에는 Fleet Engine과 연결하기 위한 표준 google.maps.Map 항목 및 데이터 구성요소의 드롭인 대체 구성요소인 JavaScript 맵 구성요소가 포함되어 있습니다. JavaScript 배송 추적 라이브러리를 사용하면 웹 애플리케이션에서 맞춤설정이 가능한 애니메이션 배송 추적 환경을 제공할 수 있습니다.

구성요소

JavaScript 배송 추적 라이브러리는 목적지까지 이동하는 차량 및 경로를 시각화하기 위한 구성요소와 운전자의 도착예정시간 또는 남은 운전 거리에 관한 원시 데이터 피드를 제공합니다.

배송 추적 지도 보기

지도뷰 구성요소는 차량과 목적지의 위치를 시각화합니다. 차량의 경로를 알고 있는 경우 지도뷰 구성요소는 차량이 예상 경로를 따라 이동할 때 해당 차량을 애니메이션으로 표시합니다.

배송 위치 제공업체

배송 위치 제공업체는 최초 및 라스트 마일 배송 추적을 위해 추적된 객체의 위치 정보를 배송 추적 지도에 제공합니다.

배송 위치 제공업체를 통해 다음을 추적할 수 있습니다.

배송의 수령 또는 배송 위치입니다.
배송 차량의 위치와 경로입니다.

추적된 위치 객체

위치 정보 제공자는 차량 및 목적지와 같은 객체의 위치를 추적합니다.

대상 위치

목적지 위치는 여정이 끝나는 위치입니다. 배송 추적의 경우 계획된 작업 위치입니다.

차량 위치

차량 위치는 차량이 추적된 위치입니다. 선택적으로 차량의 경로를 포함할 수 있습니다.

인증 토큰 가져오기 도구

Fleet Engine에 저장된 위치 데이터에 대한 액세스를 제어하려면 서버에서 Fleet Engine용 JSON 웹 토큰 (JWT) 발급 서비스를 구현해야 합니다. 그런 다음 JavaScript 여정 공유 라이브러리를 사용하여 위치 데이터 액세스를 인증하고 웹 애플리케이션의 일부로 인증 토큰 가져오기 프로그램을 구현합니다.

스타일 지정 옵션

마커 및 다중선 스타일은 지도에서 추적된 위치 객체의 디자인과 분위기를 결정합니다. 맞춤 스타일 지정 옵션을 사용하면 웹 애플리케이션의 스타일에 맞게 기본 스타일을 변경할 수 있습니다.

추적된 위치의 공개 상태 관리

이 섹션에서는 지도에서 추적된 객체의 공개 상태 컨트롤에 대해 설명합니다. 이러한 규칙은 두 가지 객체 카테고리에 적용됩니다.

위치 마커
할 일 데이터

위치 마커 공개 상태

출발지와 목적지의 모든 위치 마커가 항상 지도에 표시됩니다. 예를 들어 배송 현황은 배송 상태와 관계없이 항상 지도에 표시됩니다.

작업 데이터 공개 상태

이 섹션에서는 차량 위치 및 남은 경로와 같은 작업 데이터에 적용되는 기본 공개 상태 규칙을 설명합니다. 많은 작업을 맞춤설정할 수 있지만 전부 맞춤설정할 수는 없습니다.

사용 불가 작업 -- 이 작업의 공개 상태는 맞춤설정할 수 없습니다.
활성 차량 작업 -- 이러한 유형의 작업을 맞춤설정할 수 있습니다.
비활성 차량 작업: 이러한 작업의 공개 상태를 맞춤설정할 수 없습니다.

사용할 수 없는 작업

추적 중인 작업으로 가는 경로에 사용 불가 작업이 하나 이상 있는 경우 (예: 운전자가 휴식 중이거나 차량에 연료를 주입하는 경우) 차량이 표시되지 않습니다. 예상 도착 시간과 예상 작업 완료 시간은 계속 사용할 수 있습니다.

활성 차량 작업

TaskTrackingInfo 객체는 배송 추적 라이브러리 내에 표시할 수 있는 여러 데이터 요소를 제공합니다. 기본적으로 이러한 필드는 작업이 차량에 할당되었을 때와 차량이 작업에서 정류장 5개 이내에 있을 때 표시됩니다. 작업이 완료되거나 취소되면 공개 상태가 종료됩니다. 필드는 다음과 같습니다.

다중선 경로
예상 도착 시간
예상 작업 완료 시간
작업 위치까지 남은 운전 거리
남은 정류장 수
차량 위치

Fleet Engine 내에서 태스크를 만들거나 업데이트할 때 태스크에 TaskTrackingViewConfig를 설정하여 태스크별로 공개 상태 구성을 맞춤설정할 수 있습니다. 이렇게 하면 다음 기준 (아래의 공개 상태 옵션이라고 함)에 따라 개별 데이터 요소를 사용할 수 있는 시점에 관한 규칙이 만들어집니다.

남은 정류장 수
예상 도착 시간까지 남은 시간
남은 운전 거리
항상 표시
표시 안함

각 데이터 요소는 하나의 공개 상태 옵션에만 연결될 수 있습니다. OR 또는 AND를 사용하여 기준을 결합할 수 없습니다.

맞춤설정의 예는 다음과 같습니다. 맞춤설정 규칙은 다음과 같습니다.

차량이 3개 정류장 내에 있는 경우 경로 다중선을 표시합니다.
남은 운전 거리가 5,000m 미만인 경우 도착예정시간을 표시합니다.
나머지 정류장 수를 표시하지 않습니다.
다른 각 필드는 차량이 작업의 정류장 5개 이내에 있을 때 표시되는 기본 공개 상태를 유지합니다.

"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

또한 지원팀에 문의하여 프로젝트의 기본 공개 상태 구성을 맞춤설정할 수도 있습니다.

경로 다중선 및 차량 위치 공개 상태 규칙:

경로 다중선이 표시되면 차량 위치도 표시되어야 합니다. 그렇지 않으면 차량 위치를 다중선의 끝으로 표시할 수 있습니다. 즉, 경로 다중선에는 덜 제한적인 공개 상태 옵션이 있을 수 없습니다.

유효한 경로 다중선과 차량 위치 공개 상태 조합을 제공하려면 다음 규칙을 따라야 합니다.

경로 다중선과 차량 위치의 공개 상태 옵션 유형이 동일한 경우:
- 공개 상태 옵션이 남은 정류장 수, 도착예정시간까지 소요 시간 또는 남은 운전 거리인 경우 경로 다중선은 차량 위치에 대해 이 공개 상태 옵션에 설정된 값보다 작거나 같은 값을 제공해야 합니다. 예를 들면 다음과 같습니다.
```
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
```
- 경로 다중선에 항상 표시되는 공개 상태 옵션이 있는 경우 차량 위치는 항상 표시되는 공개 상태 옵션도 제공해야 합니다.
- 차량 위치에 표시되지 않는 공개 상태 옵션이 있는 경우 경로 다중선은 표시되지 않는 공개 상태 옵션도 제공해야 합니다.
경로 다중선과 차량 위치의 공개 상태 옵션 유형이 다른 경우 차량 위치는 공개 상태 옵션이 모두 충족되는 경우에만 표시됩니다.

예를 들면 다음과 같습니다.
```
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingDrivingDistanceMetersThreshold": 3000
  },
}
```
이 예에서 차량 위치는 남은 정류장 수가 3개 이상이고 그리고 남은 운전 거리가 3, 000미터 이상인 경우에만 표시됩니다.

JavaScript Journey 공유 라이브러리 시작하기

JavaScript 여정 공유 라이브러리를 사용하기 전에 Fleet Engine과 API 키 가져오기를 잘 알고 있어야 합니다.

배송을 추적하려면 먼저 추적 ID 소유권 주장을 만드세요.

추적 ID 소유권 주장 만들기

배송 위치 제공업체를 통해 배송을 추적하려면 추적 ID 클레임이 포함된 JSON 웹 토큰 (JWT)을 만듭니다.

JWT 페이로드를 만들려면 trackingid 키를 사용하여 승인 섹션에 추가 클레임을 추가합니다. 값을 배송 추적 ID로 설정합니다.

다음 예는 추적 ID로 추적하기 위한 토큰을 만드는 방법을 보여줍니다.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "trackingid": "tid_54321",
   }
}

인증 토큰 가져오기 도구 만들기

인증 토큰 가져오기 프로그램을 만들면 프로젝트의 서비스 계정 인증서를 사용하여 서버에서 적절한 클레임으로 발급된 토큰을 가져올 수 있습니다. 서버에서만 토큰을 발급하고 클라이언트에서 인증서를 공유하지 않는 것이 중요합니다. 그렇지 않으면 시스템의 보안이 손상됩니다.

가져오기 프로그램은 프로미스로 래핑된 두 개의 필드가 있는 데이터 구조를 반환해야 합니다.

문자열 token.
숫자 expiresInSeconds입니다. 토큰은 가져온 후 이 시간 내에 만료됩니다.

JavaScript 배송 추적 라이브러리는 다음 중 하나에 해당하면 인증 토큰 가져오기 프로그램을 통해 토큰을 요청합니다.

새 페이지 로드 시 가져오기 프로그램을 호출하지 않았거나 가져오기 도구가 토큰과 함께 반환하지 않은 경우와 같이 유효한 토큰이 없습니다.
이전에 가져온 토큰이 만료되었습니다.
이전에 가져온 토큰이 만료 후 1분 이내에 있습니다.

그렇지 않으면 라이브러리는 이전에 발행된 여전히 유효한 토큰을 사용하고 가져오기 프로그램을 호출하지 않습니다.

다음 예시에서는 인증 토큰 가져오기 프로그램을 만드는 방법을 보여줍니다.

JavaScript

function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

토큰을 발급하기 위해 서버 측 엔드포인트를 구현할 때는 다음 사항에 유의하세요.

엔드포인트는 토큰의 만료 시간을 반환해야 합니다. 위 예시에서는 data.ExpiresInSeconds로 지정됩니다.
인증 토큰 가져오기 프로그램은 예와 같이 만료 시간 (가져온 시간부터 초 단위)을 라이브러리에 전달해야 합니다.
SERVER_TOKEN_URL은 백엔드 구현에 따라 다르며 샘플 앱 백엔드의 URL은 다음과 같습니다.
- https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
- https://SERVER_URL/token/delivery_consumer/TRACKING_ID
- https://SERVER_URL/token/fleet_reader

HTML에서 지도 로드

다음 예는 지정된 URL에서 JavaScript 배송 추적 라이브러리를 로드하는 방법을 보여줍니다. 콜백 매개변수는 API가 로드된 후 initMap 함수를 실행합니다. defer 속성을 사용하면 API가 로드되는 동안 브라우저에서 페이지의 나머지 부분을 계속 렌더링할 수 있습니다.

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

배송 팔로우

이 섹션에서는 JavaScript 배송 추적 라이브러리를 사용하여 배송 수령 또는 배송을 추적하는 방법을 보여줍니다. 코드를 실행하기 전에 스크립트 태그에 지정된 콜백 함수에서 라이브러리를 로드해야 합니다.

배송 위치 제공업체 인스턴스화

JavaScript 배송 추적 라이브러리는 Fleet Engine Deliveries API의 위치 정보 제공자를 미리 정의합니다. 프로젝트 ID와 토큰 팩토리 참조를 사용하여 인스턴스화합니다.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

지도뷰 초기화

JavaScript Journey 공유 라이브러리를 로드한 후 지도뷰를 초기화하고 HTML 페이지에 추가합니다. 페이지에는 지도뷰를 포함하는 <div> 요소가 포함되어야 합니다. 다음 예에서 <div> 요소의 이름은 map_canvas입니다.

경합 상태를 피하려면 지도가 초기화된 후 호출된 콜백에서 위치 정보 제공자의 추적 ID를 설정합니다.

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-id';

// Give the map an initial viewport to allow it to 
// initialize; otherwise the 'ready' event above may 
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

TypeScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // Any undefined styling options will use defaults.
});

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may 
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

추적 ID

위치 정보 제공자에 제공되는 추적 ID는 같은 택배의 수령 및 배송 작업, 배송 실패 횟수 등 여러 작업에 해당할 수 있습니다. 배송 추적 지도에 표시할 태스크 1개가 선택됩니다. 표시할 작업은 다음과 같이 결정됩니다.

진행 중인 수령 작업이 정확히 1개만 있는 경우 표시됩니다. 진행 중인 수령 작업이 여러 개 있으면 오류가 발생합니다.
진행 중인 게재 작업이 정확히 1개만 있는 경우 표시됩니다. 진행 중인 전송 작업이 여러 개 있으면 오류가 발생합니다.
종료된 배송 작업이 있는 경우:
- 종료된 전송 작업이 정확히 1개 있는 경우 표시됩니다.
- 종료된 전송 태스크가 여러 개 있는 경우 가장 최근의 결과 시간이 있는 태스크가 표시됩니다.
- 종료된 전송 태스크가 여러 개 있고 그 태스크에 결과 시간이 없으면 오류가 발생합니다.
종료된 수령 작업이 있는 경우:
- 종료된 수령 작업이 정확히 1개 있는 경우 표시됩니다.
- 종료된 수령 작업이 여러 개 있는 경우 결과 시간이 가장 최근인 작업이 표시됩니다.
- 종료된 수령 작업이 여러 개 있고 그중 결과 시간이 지정되지 않은 경우 오류가 발생합니다.
그렇지 않으면 작업이 표시되지 않습니다.

변경 이벤트 수신 대기

위치 정보 제공자를 사용하여 작업 추적 정보 객체에서 작업에 관한 메타 정보를 검색할 수 있습니다. 메타 정보에는 도착예정시간, 남은 정류장 수, 승차 또는 배달 전 남은 거리가 포함됩니다. 메타 정보가 변경되면 update 이벤트가 트리거됩니다. 다음 예는 이러한 변경 이벤트를 수신 대기하는 방법을 보여줍니다.

JavaScript

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

오류 처리

배송 정보 요청 시 비동기식으로 발생하는 오류는 error 이벤트를 트리거합니다. 다음 예는 오류를 처리하기 위해 이러한 이벤트를 리슨하는 방법을 보여줍니다.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

참고: 라이브러리 호출을 try...catch 블록으로 래핑하여 예상치 못한 오류를 처리해야 합니다.

추적 중지

위치 정보 제공자가 배송을 추적하지 못하도록 하려면 위치 정보 제공자에서 추적 ID를 삭제합니다.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

지도뷰에서 위치 정보 제공자 삭제

다음 예는 지도뷰에서 위치 정보 제공자를 삭제하는 방법을 보여줍니다.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

기본 지도의 디자인 맞춤설정

지도 구성요소의 디자인과 분위기를 맞춤설정하려면 클라우드 기반 도구를 사용하거나 코드에서 직접 옵션을 설정하여 지도 스타일을 지정하세요.

클라우드 기반 지도 스타일 지정 사용

클라우드 기반 지도 스타일 지정을 사용하면 코드를 변경하지 않고도 Google Cloud 콘솔에서 Google 지도를 사용하는 모든 앱의 지도 스타일을 만들고 수정할 수 있습니다. 지도 스타일은 Cloud 프로젝트에 지도 ID로 저장됩니다. JavaScript 배송 추적 지도에 스타일을 적용하려면 JourneySharingMapView를 만들 때 mapId를 지정합니다. JourneySharingMapView가 인스턴스화된 후에는 mapId 필드를 변경하거나 추가할 수 없습니다. 다음 예에서는 지도 ID를 사용하여 이전에 만든 지도 스타일을 사용 설정하는 방법을 보여줍니다.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

코드 기반 지도 스타일 지정 사용

지도 스타일 지정을 맞춤설정하는 또 다른 방법은 JourneySharingMapView를 만들 때 mapOptions를 설정하는 것입니다.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

마커 맞춤설정 사용

JavaScript 배송 추적 라이브러리를 사용하면 지도에 추가된 마커의 디자인과 분위기를 맞춤설정할 수 있습니다. 이렇게 하려면 마커 맞춤설정을 지정하면 지도에 마커를 추가하기 전과 마커를 업데이트할 때마다 배송 추적 라이브러리에서 이를 적용합니다.

가장 간단한 맞춤설정은 동일한 유형의 모든 마커에 적용될 MarkerOptions 객체를 지정하는 것입니다. 객체에 지정된 변경사항은 각 마커가 생성된 후에 적용되고 모든 기본 옵션을 덮어씁니다.

고급 옵션은 맞춤설정 기능을 지정하는 것입니다. 맞춤설정 함수를 사용하면 데이터를 기반으로 마커의 스타일을 지정하고 클릭 처리와 같은 상호작용을 마커에 추가할 수 있습니다. 특히 배송 추적은 마커가 나타내는 객체 유형(차량 또는 목적지)에 관한 데이터를 맞춤설정 함수에 전달합니다. 이렇게 하면 마커 요소 자체의 현재 상태에 따라 마커 스타일을 변경할 수 있습니다. 예를 들어 목적지까지 남은 계획된 정류장 수와 같은 경우입니다. Fleet Engine 외부 소스의 데이터와 조인하고 이 정보를 기반으로 마커의 스타일을 지정할 수도 있습니다.

배송 추적 라이브러리는 FleetEngineShipmentLocationProviderOptions에서 다음 맞춤설정 매개변수를 제공합니다.

`MarkerOptions`를 사용하여 마커의 스타일 변경

다음 예는 MarkerOptions 객체를 사용하여 차량 마커의 스타일을 구성하는 방법을 보여줍니다. 다음 패턴에 따라 위에 나열된 마커 맞춤설정을 사용하여 마커의 스타일을 맞춤설정합니다.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

맞춤설정 함수를 사용하여 마커의 스타일 지정 변경

다음 예는 차량 마커의 스타일을 구성하는 방법을 보여줍니다. 위에 나열된 마커 맞춤설정 매개변수를 사용하여 마커의 스타일을 맞춤설정하려면 이 패턴을 따르세요.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

마커에 클릭 처리 추가

다음 예는 차량 마커에 클릭 처리를 추가하는 방법을 보여줍니다. 위에 나열된 마커 맞춤설정 매개변수를 사용하여 마커에 클릭 처리를 추가하려면 이 패턴을 따르세요.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

다중선 맞춤설정 사용

배송 추적 라이브러리를 사용하면 지도에서 배송 경로의 디자인과 분위기를 맞춤설정할 수도 있습니다. 라이브러리는 배송의 활성 또는 남은 경로의 각 좌표 쌍에 google.maps.Polyline 객체를 만듭니다. 다중선 맞춤설정을 지정하여 Polyline 객체의 스타일을 지정할 수 있습니다. 그런 다음 라이브러리는 두 가지 상황, 즉 객체를 지도에 추가하기 전과 객체에 사용되는 데이터가 변경된 상황에 이러한 맞춤설정을 적용합니다.

마커 맞춤설정과 마찬가지로 일치하는 모든 Polyline 객체를 만들거나 업데이트할 때 적용할 PolylineOptions 집합을 지정할 수 있습니다.

마찬가지로 맞춤설정 기능을 지정할 수 있습니다. 맞춤설정 함수를 사용하면 Fleet Engine에서 전송한 데이터를 기반으로 객체의 개별 스타일을 지정할 수 있습니다. 이 함수는 배송의 현재 상태에 따라 각 객체의 스타일을 변경할 수 있습니다. 예를 들어 Polyline 객체에 더 깊은 색을 칠하거나 차량이 느리게 움직일 때 더 두껍게 만듭니다. Fleet Engine 외부의 소스에 대해 조인하고 이 정보를 기반으로 Polyline 객체의 스타일을 지정할 수도 있습니다.

FleetEngineShipmentLocationProviderOptions에 제공된 매개변수를 사용하여 맞춤설정을 지정할 수 있습니다. 차량 여정의 다양한 경로 상태(이미 이동함, 현재 이동 중이거나 아직 이동하지 않음)에 대한 맞춤설정을 설정할 수 있습니다. 매개변수는 다음과 같습니다.

takenPolylineCustomization: 이미 이동된 경로의 경우
activePolylineCustomization: 활발하게 이동하는 경로
remainingPolylineCustomization: 아직 이동하지 않은 경로

`PolylineOptions`를 사용하여 `Polyline` 객체의 스타일 변경

다음 예는 PolylineOptions를 사용하여 Polyline 객체의 스타일을 구성하는 방법을 보여줍니다. 앞에서 설명한 다중선 맞춤설정을 사용하여 Polyline 객체의 스타일을 맞춤설정하려면 이 패턴을 따릅니다.

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

맞춤설정 함수를 사용하여 `Polyline` 객체의 스타일 변경

다음 예는 활성 Polyline 객체의 스타일을 구성하는 방법을 보여줍니다. 앞에 나열된 다중선 맞춤설정 매개변수를 사용하여 Polyline 객체의 스타일을 맞춤설정하려면 이 패턴을 따릅니다.

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

`Polyline` 객체의 공개 상태 제어

기본적으로 모든 Polyline 객체가 표시됩니다. Polyline 객체를 보이지 않게 설정하려면 다음과 같이 visible 속성을 설정하세요.

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

차량 또는 위치 마커의 `InfoWindow` 표시

InfoWindow를 사용하여 차량 또는 위치 마커에 대한 추가 정보를 표시할 수 있습니다.

다음 예에서는 InfoWindow를 만들어 차량 마커에 연결하는 방법을 보여줍니다.

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

자동 맞추기 사용 중지

자동 맞추기를 사용 중지하여 지도가 표시 영역을 차량 및 예상 경로에 자동으로 맞추지 않도록 할 수 있습니다. 다음 예는 여정 공유 지도 뷰를 구성할 때 자동 적합을 사용 중지하는 방법을 보여줍니다.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.   
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

기존 지도 바꾸기

JavaScript 배송 추적 라이브러리를 사용하면 맞춤설정이 손실되지 않고 마커 또는 기타 맞춤설정이 포함된 기존 지도를 대체할 수 있습니다.

예를 들어 마커가 표시되는 표준 google.maps.Map 항목이 포함된 웹페이지가 있다고 가정해 보겠습니다.

<!DOCTYPE html>
<html>
  <head>
    <style>
       /* Set the size of the div element that contains the map */
      #map {
        height: 400px;  /* The height is 400 pixels */
        width: 100%;  /* The width is the width of the web page */
       }
    </style>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>
    <script>
// Initialize and add the map
function initMap() {
  // The location of Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // The map, initially centered at Mountain View, CA.
  var map = new google.maps.Map(document.getElementById('map'));
  map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});

  // The marker, now positioned at Uluru
  var marker = new google.maps.Marker({position: uluru, map: map});
}
    </script>
    <!-- Load the API from the specified URL.
       * The async attribute allows the browser to render the page while the API loads.
       * The key parameter will contain your own API key (which is not needed for this tutorial).
       * The callback parameter executes the initMap() function.
    -->
    <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

JavaScript Journey 공유 라이브러리를 추가하려면 다음 안내를 따르세요.

인증 토큰 팩토리의 코드를 추가합니다.
initMap() 함수에서 위치 제공자를 초기화합니다.
initMap() 함수에서 지도뷰를 초기화합니다. 뷰에 지도가 포함됩니다.
맞춤설정을 지도뷰 초기화를 위한 콜백 함수로 이동합니다.
API 로더에 위치 라이브러리를 추가합니다.

다음 예는 어떤 변경사항을 적용해야 하는지 보여줍니다.

<!DOCTYPE html>
<html>
  <head>
    <style>
       /* Set the size of the div element that contains the map */
      #map {
        height: 400px;  /* The height is 400 pixels */
        width: 100%;  /* The width is the width of the web page */
       }
    </style>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>
    <script>
let locationProvider;

// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
  // options is a record containing two keys called 
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
      if (!response.ok) {
        throw new Error(response.statusText);
      }
      const data = await response.json();
      return {
        token: data.Token,
        expiresInSeconds: data.ExpiresInSeconds
      };
}

// Initialize and add the map
function initMap() {
  // (2) Initialize location provider.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    YOUR_PROVIDER_ID,
    authTokenFetcher,
  });

  // (3) Initialize map view (which contains the map).
  const mapView = new google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map'),
    locationProviders: [locationProvider],
    // any styling options
  });

  locationProvider.trackingId = TRACKING_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, map: map});
  };

    </script>
    <!-- Load the API from the specified URL
      * The async attribute allows the browser to render the page while the API loads
      * The key parameter will contain your own API key (which is not needed for this tutorial)
      * The callback parameter executes the initMap() function
      *
      * (5) Add the journey sharing library to the API loader.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

지정된 ID로 울루루 근처에 추적된 패키지가 있으면 이제 지도에 렌더링됩니다.

자바스크립트 배송 추적 라이브러리로 배송 추적

구성요소

배송 추적 지도 보기

배송 위치 제공업체

추적된 위치 객체

대상 위치

차량 위치

인증 토큰 가져오기 도구

스타일 지정 옵션

추적된 위치의 공개 상태 관리

위치 마커 공개 상태

작업 데이터 공개 상태

사용할 수 없는 작업

활성 차량 작업

경로 다중선 및 차량 위치 공개 상태 규칙:

JavaScript Journey 공유 라이브러리 시작하기

추적 ID 소유권 주장 만들기

인증 토큰 가져오기 도구 만들기

JavaScript

TypeScript

HTML에서 지도 로드

배송 팔로우

배송 위치 제공업체 인스턴스화

JavaScript

TypeScript

지도뷰 초기화

JavaScript

TypeScript

추적 ID

변경 이벤트 수신 대기

JavaScript

TypeScript

오류 처리

JavaScript

TypeScript

추적 중지

JavaScript

TypeScript

지도뷰에서 위치 정보 제공자 삭제

JavaScript

TypeScript

기본 지도의 디자인 맞춤설정

클라우드 기반 지도 스타일 지정 사용

JavaScript

TypeScript

코드 기반 지도 스타일 지정 사용

JavaScript

TypeScript

마커 맞춤설정 사용

MarkerOptions를 사용하여 마커의 스타일 변경

JavaScript

TypeScript

맞춤설정 함수를 사용하여 마커의 스타일 지정 변경

JavaScript

TypeScript

마커에 클릭 처리 추가

JavaScript

TypeScript

다중선 맞춤설정 사용

PolylineOptions를 사용하여 Polyline 객체의 스타일 변경

JavaScript

TypeScript

맞춤설정 함수를 사용하여 Polyline 객체의 스타일 변경

JavaScript

TypeScript

Polyline 객체의 공개 상태 제어

JavaScript

TypeScript

차량 또는 위치 마커의 InfoWindow 표시

JavaScript

TypeScript

자동 맞추기 사용 중지

JavaScript

TypeScript

기존 지도 바꾸기

`MarkerOptions`를 사용하여 마커의 스타일 변경

`PolylineOptions`를 사용하여 `Polyline` 객체의 스타일 변경

맞춤설정 함수를 사용하여 `Polyline` 객체의 스타일 변경

`Polyline` 객체의 공개 상태 제어

차량 또는 위치 마커의 `InfoWindow` 표시