Seguir um envio

Agora que você configurou o SDK do JavaScript Consumer para tarefas programadas, já pode acompanhar um envio com seu aplicativo para o consumidor. Este documento aborda as seguintes etapas principais desse processo:

Inicializar um mapa e mostrar a viagem compartilhada
Atualizar e acompanhar o progresso da jornada
Parar de acompanhar um envio
Resolver erros de rastreamento de envio

Configurar um mapa

Para acompanhar a coleta ou entrega de um envio no seu app da Web, carregue um mapa e instancie o SDK do Consumer para começar a rastrear o envio. Você pode carregar um novo mapa ou usar um já existente. Em seguida, use a função de inicialização para instanciar o SDK do Consumer para que a visualização do mapa corresponda ao local do item que está sendo rastreado.

Carregar um novo mapa usando a API Maps JavaScript

Para criar um novo mapa, carregue a API Maps JavaScript no seu app da Web. O exemplo a seguir mostra como carregar a API Maps JavaScript, ativar o SDK e acionar a verificação de inicialização.

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.

Use a função initMap para instanciar o SDK do Consumer. Exemplo:

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

Carregar um mapa existente

Também é possível carregar um mapa criado pela API Maps JavaScript, como um que você já esteja usando.

Por exemplo, suponha que você tenha uma página da Web com uma entidade google.maps.Map padrão em que um marcador é mostrado conforme definido no código HTML a seguir. Isso mostra seu mapa usando a mesma função initMap no callback no final:

    <!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 Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // 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 Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * 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>

Instanciar um provedor de local de envio

Use o provedor de local de envio, junto com o buscador de token de autorização definido anteriormente, para começar a receber dados do Fleet Engine.

Estes exemplos mostram como instanciar o provedor de local.

JavaScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

TypeScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Mostrar a jornada compartilhada

Para mostrar o progresso de uma tarefa programada, inicialize a visualização dela, que define o frame do mapa para corresponder ao local da viagem rastreada. O progresso é fornecido pelo SDK do Consumer depois que ele recebe as informações do Fleet Engine.

Dicas:

Verifique se a página contém um elemento <div> que contém a visualização do mapa. No exemplo a seguir, o <div> elemento é chamado de map_canvas.
Conheça as regras de visibilidade padrão que o Fleet Engine aplica às viagens rastreadas. Também é possível configurar regras de visibilidade para o envio de veículos ativos e tarefas de paradas programadas. Consulte Personalizar a visibilidade da tarefa no Configurar tarefas guia.

Estes exemplos mostram como inicializar uma visualização de mapa.

JavaScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts 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

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // 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 starts 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);
}

Atualizar o progresso do envio

Você pode detectar eventos e atualizar o progresso do envio à medida que uma viagem avança. Use o provedor de local para recuperar metainformações do objeto taskTrackingInfo. As mudanças nas metainformações acionam um evento update. O objeto taskTrackingInfo fornece o seguinte:

HEC
Número de paradas restantes
Distância restante antes da coleta ou entrega

O exemplo a seguir 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);
});

Mostrar critérios para várias tarefas

O SDK do Consumer para tarefas programadas mostra apenas uma tarefa por ID de acompanhamento no mapa. No entanto, você também costuma atribuir um ID de acompanhamento a um produto de envio específico que permanece associado ao produto durante toda a viagem no seu sistema. Isso significa que um único ID de acompanhamento pode estar associado a várias tarefas, como uma tarefa de retirada seguida de uma tarefa de entrega para o mesmo pacote ou várias tarefas de envio com falha para um pacote.

Para lidar com essa situação, o Fleet Engine aplica critérios para mostrar tarefas, mostrados na tabela a seguir.

Critérios de tarefa	Resultado
Tarefas de coleta abertas
Existe exatamente uma	Mostrar a tarefa
Várias existem	Gerar erro
Tarefas de retirada fechadas
Existe exatamente uma	Mostrar a tarefa
Várias existem (algumas com horários de resultado)	Mostrar a tarefa com o horário de resultado mais recente
Várias existem (nenhuma com horários de resultado)	Gerar erro
Tarefas de entrega abertas
Existe exatamente uma	Mostrar a tarefa
Várias existem	Gerar erro
Tarefas de entrega fechadas
Existe exatamente uma	Mostrar a tarefa
Várias existem (algumas com horários de resultado)	Mostrar a tarefa com o horário de resultado mais recente
Várias existem (nenhuma com horários de resultado)	Gerar erro

Parar de acompanhar um envio

Quando uma jornada de envio é concluída ou cancelada, seu aplicativo para o consumidor precisa parar de acompanhar um envio removendo o ID de acompanhamento e o provedor de local da visualização do mapa. Confira mais detalhes nas próximas seções.

Remover o ID de acompanhamento

Para impedir que o provedor de local rastreie o envio, remova o ID de acompanhamento do provedor de local. Os exemplos a seguir mostram como fazer isso.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Remover o provedor de local da visualização do mapa

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Resolver erros de rastreamento de envio

Os 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 resolver 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 inesperados.

A seguir

Personalizar o estilo de um mapa

Seguir um envio Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Configurar um mapa

Carregar um novo mapa usando a API Maps JavaScript

Carregar um mapa existente

Instanciar um provedor de local de envio

JavaScript

TypeScript

Mostrar a jornada compartilhada

JavaScript

TypeScript

Atualizar o progresso do envio

JavaScript

TypeScript

Mostrar critérios para várias tarefas

Parar de acompanhar um envio

Remover o ID de acompanhamento

JavaScript

TypeScript

Remover o provedor de local da visualização do mapa

JavaScript

TypeScript

Resolver erros de rastreamento de envio

JavaScript

TypeScript

A seguir

Seguir um envio