Rastrear remessas com a biblioteca de rastreamento de envio JavaScript

A biblioteca Shipment Tracking do JavaScript permite visualizar a localização de veículos e os locais de interesse rastreados no Fleet Engine. A biblioteca contém um componente de mapa JavaScript que é uma substituição simples para uma entidade google.maps.Map padrão e componentes de dados para conexão com o Fleet Engine. Com a biblioteca JavaScript Shipment Tracking, você pode oferecer uma experiência de rastreamento de envio animada e personalizável no seu aplicativo da Web.

Componentes

A biblioteca JavaScript Shipment Tracking Library fornece componentes para visualização do veículo e do trajeto até um destino, além de feeds de dados brutos para o HEC de um motorista ou a distância restante a ser percorrida.

Visualização em mapa do rastreamento de envios

O componente de visualização de mapa mostra a localização de veículos e destinos. Se o trajeto para um veículo for conhecido, o componente de visualização de mapa vai animar o veículo à medida que ele se move ao longo do caminho previsto.

Provedor do local de envio

Um provedor de localização de remessa insere informações de localização de objetos rastreados no mapa de rastreamento de remessa para o rastreamento da primeira e da última milha.

Você pode usar o provedor de localização de remessa para rastrear:

  • O local de retirada ou entrega de uma remessa.
  • O local e a rota do veículo de entrega.

Objetos de localização rastreados

O provedor de localização rastreia a localização de objetos, como veículos e destinos.

Local de destino

O local de destino é onde uma jornada termina. Para o rastreamento de remessa, é o local planejado da tarefa.

Local do veículo

O local do veículo é o local monitorado. Ele pode, opcionalmente, incluir um trajeto para o veículo.

Coletor de tokens de autenticação

Para controlar o acesso aos dados de local armazenados no Fleet Engine, você precisa implementar um serviço de criação de JSON Web Token (JWT) para o Fleet Engine no seu servidor. Em seguida, implemente um coletor de tokens de autenticação como parte do seu aplicativo da Web usando a JavaScript Journey Share Library para autenticar o acesso aos dados de local.

Opções de estilo

Os estilos de marcadores e polilinhas determinam a aparência dos objetos de localização rastreados no mapa. Você pode usar opções de estilo personalizadas para alterar o estilo padrão de acordo com o estilo do seu aplicativo da Web.

Controlar a visibilidade dos locais rastreados

Esta seção descreve os controles de visibilidade para objetos rastreados no mapa. Essas regras se aplicam a duas categorias de objetos:

  • Marcador de local
  • Dados da tarefa

Visibilidade do marcador de local

Todos os marcadores de local para a origem e o destino são sempre mostrados no mapa. Por exemplo, o local de uma remessa é sempre mostrado no mapa, independentemente do estado da entrega.

Visibilidade dos dados da tarefa

Nesta seção, descrevemos as regras de visibilidade padrão que se aplicam aos dados da tarefa, como a localização do veículo e o trajeto restante. É possível personalizar muitas tarefas, mas não todas:

  • Tarefas de indisponibilidade : não é possível personalizar a visibilidade para essas tarefas.
  • Tarefas ativas do veículo - Você pode personalizar este tipo de tarefas.
  • Tarefas do veículo inativo: não é possível personalizar a visibilidade para essas tarefas.

Tarefas de indisponibilidade

O veículo não ficará visível se houver pelo menos uma tarefa de indisponibilidade (por exemplo, se o motorista estiver fazendo uma pausa ou o veículo estiver sendo reabastecido) no trajeto até a tarefa rastreada. O horário estimado de chegada e o tempo estimado de conclusão da tarefa ainda estão disponíveis.

Tarefas ativas do veículo

O objeto TaskTrackingInfo fornece vários elementos de dados que podem ser visíveis na biblioteca Shipment Tracking. Por padrão, esses campos ficam visíveis quando a tarefa é atribuída ao veículo e quando ele está a até cinco paradas da tarefa. A visibilidade termina quando a tarefa é concluída ou cancelada. Os campos são os seguintes:

  • Polilinhas do trajeto
  • Tempo estimado para a chegada
  • Tempo estimado de conclusão da tarefa
  • Distância de carro restante até a tarefa
  • Contagem de paradas restantes
  • Local do veículo

É possível personalizar a configuração de visibilidade por tarefa definindo TaskTrackingViewConfig em uma tarefa ao criá-la ou atualizá-la no Fleet Engine. Isso cria regras de quando elementos de dados individuais estão disponíveis. Elas podem ser baseadas nos seguintes critérios (chamados de opção de visibilidade abaixo):

  • Contagem de paradas restantes
  • Duração até o horário estimado de chegada
  • Distância de carro restante
  • Sempre visível
  • Nunca visível

Cada elemento de dados só pode ser associado a uma opção de visibilidade. Não é possível combinar critérios usando OR ou AND.

Confira abaixo um exemplo de personalização. As regras dessa personalização são:

  • Mostre as polilinhas do trajeto se o veículo estiver a até três paradas.
  • Mostre o HEC se a distância de carro restante for menor que 5.000 metros.
  • Nunca mostrar o número de paradas restantes.
  • Os outros campos mantêm a visibilidade padrão de que será mostrada quando o veículo estiver a até cinco paradas da tarefa.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Também é possível personalizar a configuração de visibilidade padrão do projeto entrando em contato com a equipe de suporte.

Regras de visibilidade de polilinhas de trajeto e localização de veículos:

Quando as polilinhas do trajeto estão visíveis, o local do veículo também precisa estar visível. Caso contrário, a localização do veículo pode ser indicada no fim das polilinhas. Isso significa que as polilinhas do trajeto não podem ter uma opção de visibilidade menos restritiva.

Estas regras precisam ser seguidas para fornecer uma combinação válida de polilinhas do trajeto e visibilidade da localização do veículo:

  • Quando as polilinhas do trajeto e o local do veículo têm o mesmo tipo de opção de visibilidade:

    • Se a opção de visibilidade for "Contagem de paradas restantes", "Duração até a HEC" ou "Distância de carro restante", as polilinhas do trajeto precisarão fornecer um valor menor ou igual ao definido nessa opção de visibilidade para a localização do veículo. Confira um exemplo:
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • Se as polilinhas do trajeto tiverem uma opção de visibilidade sempre visível, a localização do veículo também vai precisar oferecer uma opção de visibilidade sempre visível.
    • Se a localização do veículo tiver uma opção de visibilidade nunca visível, as polilinhas do trajeto também vão precisar oferecer uma opção de visibilidade nunca visível.
  • Quando as polilinhas do trajeto e o local do veículo têm tipos de opção de visibilidade diferentes, a localização do veículo só fica visível quando ambas as opções são atendidas.

    Confira um exemplo:

    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingDrivingDistanceMetersThreshold": 3000
      },
    }
    

    Nesse exemplo, a localização do veículo só vai estar visível se a contagem de paradas restantes for de pelo menos 3 E a distância de carro restante for de pelo menos 3.000 metros.

Introdução à biblioteca JavaScript Journey Share

Antes de usar a JavaScript Journey Share Library, conheça o Fleet Engine e saiba como acessar uma chave de API.

Para acompanhar uma entrega, crie uma reivindicação de ID de acompanhamento.

Criar uma reivindicação do ID de acompanhamento

Para rastrear uma remessa usando o provedor de localização de envio, crie um JSON Web Token (JWT) com uma declaração de ID de rastreamento.

Para criar o payload do JWT, inclua uma declaração adicional na seção de autorização com a chave trackingid. Defina o valor como o ID de rastreamento do frete.

O exemplo a seguir mostra como criar um token para acompanhar por ID de acompanhamento:

{
  "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",
   }
}

Criar um coletor de tokens de autenticação

Crie um coletor de tokens de autenticação para recuperar um token gerado com as declarações apropriadas nos servidores usando um certificado de conta de serviço para o projeto. É importante produzir tokens apenas nos servidores e nunca compartilhar certificados com clientes. Caso contrário, a segurança do sistema será comprometida.

O coletor precisa retornar uma estrutura de dados com dois campos, encapsulados em uma promessa:

  • Uma string token.
  • Um número expiresInSeconds. Um token expira nesse período após a busca.

A biblioteca Shipment Tracking do JavaScript solicita um token usando o coletor de tokens de autenticação quando uma das seguintes condições é verdadeira:

  • Ela não tem um token válido, como quando não chamou o coletor em um novo carregamento de página ou quando não retornou com um token.
  • O token buscado anteriormente expirou.
  • O token buscado anteriormente está dentro de um minuto para expirar.

Caso contrário, a biblioteca usa o token emitido anteriormente, ainda válido, e não chama o coletor.

O exemplo a seguir mostra como criar um coletor de tokens de autenticação:

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(),
  };
}

Ao implementar o endpoint do lado do servidor para criar os tokens, lembre-se do seguinte:

  • O endpoint precisa retornar um prazo de validade para o token. No exemplo acima, ele é fornecido como data.ExpiresInSeconds.
  • O coletor de tokens de autenticação precisa transmitir o tempo de validade (em segundos, a partir do momento da busca) à biblioteca, conforme mostrado no exemplo.
  • O SERVER_TOKEN_URL depende da implementação do back-end. Estes são os URLs para o back-end do app de exemplo:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

Carregar um mapa de HTML

O exemplo a seguir mostra como carregar a biblioteca JavaScript Shipment Tracking de um URL especificado. O parâmetro callback executa a função initMap após o carregamento da API. O atributo defer permite que o navegador continue renderizando o restante da página enquanto a API é carregada.

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

Seguir uma remessa

Nesta seção, mostramos como usar a biblioteca JavaScript Shipment Tracking para acompanhar uma coleta ou entrega de uma remessa. Carregue a biblioteca usando a função de callback especificada na tag do script antes de executar o código.

Instanciar um provedor de localização de remessa

A biblioteca Shipment Tracking do JavaScript predefine um provedor de localização para a API Fleet Engine Deliveries. Use seu ID do projeto e uma referência à fábrica de tokens para instanciá-lo.

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',
});

Inicializar a visualização de mapa

Depois de carregar essa biblioteca, inicialize a visualização de mapa e adicione à página HTML. Sua página deve conter um elemento <div> que contenha a visualização de mapa. No exemplo a seguir, o elemento <div> é chamado de map_canvas.

Para evitar disputas, defina o ID de acompanhamento do provedor de localização no callback invocado após a inicialização do mapa.

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 de acompanhamento

O ID de rastreamento informado ao provedor de localização pode corresponder a várias tarefas. Por exemplo, uma tarefa de retirada e entrega do mesmo pacote ou várias tentativas de entrega com falha. Uma tarefa é selecionada para ser mostrada no mapa de rastreamento de envio. A tarefa a ser mostrada é determinada da seguinte maneira:

  1. Se houver exatamente uma tarefa para retirada aberta, ela será exibida. Um erro será gerado se houver várias tarefas de retirada aberta.
  2. Se houver exatamente uma tarefa de entrega aberta, ela será exibida. Um erro será gerado se houver várias tarefas de entrega abertas.
  3. Se houver tarefas de entrega encerradas:
    • Se houver exatamente uma tarefa de entrega encerrada, ela será exibida.
    • Se houver várias tarefas de entrega encerradas, aquela com o horário de resultado mais recente será exibida.
    • Se houver várias tarefas de entrega encerradas, e nenhuma delas tiver um tempo de resultado, será gerado um erro.
  4. Se houver tarefas de retirada fechadas:
    • Se houver exatamente uma tarefa de retirada fechada, ela será exibida.
    • Se houver várias tarefas de retirada fechadas, aquela com o horário de resultado mais recente será mostrada.
    • Se houver várias tarefas de retirada fechadas e nenhuma delas tiver um tempo de resultado, será gerado um erro.
  5. Caso contrário, nenhuma tarefa será exibida.

Ouvir eventos de alteração

Você pode recuperar metainformações sobre uma tarefa do objeto de informações de rastreamento de tarefas usando o provedor de localização. Essas informações incluem o HEC, o número de paradas restantes e a distância restante antes da embarque ou da entrega. As mudanças nas metainformações acionam um evento update. O exemplo abaixo mostra como detectar esses eventos de mudança.

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);
});

Solucionar erros

Erros que surgem de forma assíncrona ao solicitar informações de envio acionam eventos error. O exemplo a seguir mostra como detectar esses eventos para processar erros.

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);
});

Observação:envolva as chamadas de biblioteca em blocos try...catch para lidar com erros imprevistos.

Parar monitoramento

Para impedir que o provedor de localização rastreie a remessa, remova o ID de rastreamento dele.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Remover o provedor de localização da visualização de mapa

O exemplo a seguir mostra como remover um provedor de localização da visualização de mapa.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Personalizar a aparência do mapa básico

Para personalizar a aparência do componente Maps, estilize seu mapa usando ferramentas baseadas na nuvem ou definindo opções diretamente no código.

Usar a Estilização de mapas baseada na nuvem

Com a Estilização de mapas baseada na nuvem, você pode criar e editar estilos para qualquer um dos seus apps que usam o Google Maps no console do Google Cloud sem precisar alterar o código. Os estilos de mapa são salvos como IDs de mapa no seu projeto do Cloud. Para aplicar um estilo ao mapa de rastreamento de envio do JavaScript, especifique um mapId ao criar o JourneySharingMapView. Não é possível adicionar ou mudar o campo mapId depois que o JourneySharingMapView for instanciado. O exemplo a seguir mostra como ativar um estilo de mapa criado anteriormente com um 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.
});

Usar a Estilização de mapas baseada em código

Outra maneira de personalizar a estilização do mapa é definir mapOptions ao criar o JourneySharingMapView.

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" }
        ]
      }
    ]
  }
});

Usar as personalizações dos marcadores

Com a biblioteca JavaScript Shipment Tracking, você pode personalizar a aparência dos marcadores adicionados ao mapa. Para fazer isso, especifique personalizações de marcador que serão aplicadas pela biblioteca Shipment Tracking antes de adicionar marcadores ao mapa e sempre que eles forem atualizados.

A personalização mais simples é especificar um objeto MarkerOptions que será aplicado a todos os marcadores do mesmo tipo. As alterações especificadas no objeto são aplicadas depois da criação de cada marcador, substituindo todas as opções padrão.

Uma opção mais avançada é especificar uma função de personalização. As funções de personalização permitem estilizar os marcadores com base nos dados, além de adicionar interatividade a eles, como o processamento de cliques. Especificamente, o Shipment Tracking transmite dados para a função de personalização sobre o tipo de objeto que o marcador representa: veículo ou destino. Isso permite que o estilo do marcador mude com base no estado atual do próprio elemento. Por exemplo, o número de paradas planejadas restantes até o destino. É possível até mesmo mesclar dados de fontes fora do Fleet Engine e estilizar o marcador com base nessas informações.

A biblioteca Shipment Tracking oferece os seguintes parâmetros de personalização no FleetEngineShipmentLocationProviderOptions:

Mudar o estilo dos marcadores usando MarkerOptions

O exemplo a seguir mostra como configurar o estilo de um marcador de veículo com um objeto MarkerOptions. Siga esse padrão para personalizar o estilo de qualquer marcador usando qualquer uma das opções listadas acima.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Alterar o estilo dos marcadores usando funções de personalização

O exemplo a seguir mostra como configurar o estilo de um marcador de veículo. Siga esse padrão para personalizar o estilo de qualquer marcador usando qualquer um dos parâmetros listados acima.

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}`);
  };

Adicionar processamento de cliques aos marcadores

O exemplo a seguir mostra como adicionar o gerenciamento de cliques a um marcador de veículo. Siga esse padrão para adicionar processamento de cliques a qualquer marcador usando um dos parâmetros de personalização listados acima.

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.
      });
    }
  };

Usar personalizações de polilinha

Com a biblioteca Shipment Tracking, você também pode personalizar a aparência da rota da remessa no mapa. A biblioteca cria um objeto google.maps.Polyline para cada par de coordenadas no caminho ativo ou restante da remessa. Você pode estilizar os objetos Polyline especificando personalizações de polilinha. A biblioteca aplica essas personalizações em duas situações: antes de adicionar os objetos ao mapa e quando os dados usados para os objetos mudam.

Assim como na personalização de marcadores, é possível especificar um conjunto de PolylineOptions para ser aplicado a todos os objetos Polyline correspondentes quando eles forem criados ou atualizados.

Da mesma forma, é possível especificar uma função de personalização. As funções de personalização permitem aplicar um estilo individual aos objetos com base nos dados enviados pelo Fleet Engine. A função pode mudar o estilo de cada objeto com base no estado atual do envio. Por exemplo, colorir o objeto Polyline com uma tonalidade mais profunda ou torná-lo mais espesso quando o veículo está se movendo mais devagar. É possível até mesmo mesclar de fontes fora do Fleet Engine e estilizar o objeto Polyline com base nessas informações.

Você pode especificar as personalizações usando parâmetros fornecidos em FleetEngineShipmentLocationProviderOptions. Você pode definir personalizações para diferentes estados do caminho na jornada do veículo: já percorrido, viajando ativamente ou ainda não viajando. Os parâmetros são os seguintes:

Mudar o estilo de objetos Polyline usando PolylineOptions

O exemplo a seguir mostra como configurar o estilo de um objeto Polyline com PolylineOptions. Siga esse padrão para personalizar o estilo de qualquer objeto Polyline usando qualquer uma das personalizações de polilinha listadas anteriormente.

JavaScript

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

TypeScript

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

Mudar o estilo de objetos Polyline usando funções de personalização

O exemplo a seguir mostra como configurar o estilo de um objeto Polyline ativo. Siga esse padrão para personalizar o estilo de qualquer objeto Polyline usando um dos parâmetros de personalização de polilinha listados anteriormente.

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'});
      }
    }
  };

Controlar a visibilidade de objetos Polyline

Por padrão, todos os objetos Polyline ficam visíveis. Para tornar um objeto Polyline invisível, defina a propriedade visible dele:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Mostrar um InfoWindow para um marcador de veículo ou local

Você pode usar um InfoWindow para exibir mais informações sobre um veículo ou marcador de local.

O exemplo a seguir mostra como criar um InfoWindow e anexá-lo a um marcador de veículo:

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();

Desativar o ajuste automático

Desative o ajuste automático para impedir que o mapa se ajuste automaticamente à janela de visualização ao veículo e ao trajeto previsto. O exemplo a seguir mostra como desativar o ajuste automático ao configurar a visualização de mapa do compartilhamento de jornada.

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();

Substituir um mapa

Você pode usar a biblioteca Shipment Tracking do JavaScript para substituir um mapa que inclui marcadores ou outras personalizações sem perder nada.

Por exemplo, suponha que você tenha uma página da Web com uma entidade google.maps.Map padrão em que um marcador é exibido:

<!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>

Para adicionar a biblioteca JavaScript Journey Share:

  1. Adicione o código da fábrica de tokens de autenticação.
  2. Inicialize um provedor de localização na função initMap().
  3. Inicialize a visualização de mapa na função initMap(). A visualização contém o mapa.
  4. Mova a personalização para a função de callback para a inicialização da visualização de mapa.
  5. Adicione a biblioteca de localização ao carregador da API.

O exemplo a seguir mostra as mudanças a serem feitas:

<!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>

Se você tiver um pacote rastreado com o ID especificado perto de Uluru, ele será renderizado no mapa.