Seguir um envio

Agora que você configurou o SDK JavaScript Consumer para tarefas programadas, prontos para acompanhar o envio com seu app para o consumidor. Este documento abrange os estas etapas principais nesse processo:

  • Inicializar um mapa e mostrar a jornada compartilhada
  • Atualizar e acompanhar o progresso da viagem
  • Parar compartilhamento da viagem
  • Solucionar erros

Configurar um mapa

Para acompanhar a retirada ou entrega de uma remessa no seu app da Web, carregue um mapa e instancie o SDK do consumidor para começar a rastrear o envio. É possível carregar um mapa novo ou usar um existente. Depois, você usa o comando para instanciar o SDK Consumer para que a visualização de mapa corresponda ao localização do item sendo rastreado.

Carregar um novo mapa usando a API Google Maps JavaScript

Para criar um novo mapa, carregue a API Google Maps JavaScript no seu app da Web. O exemplo a seguir mostra como carregar a API JavaScript do Google Maps, ativar a do 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 do seu enquanto a API é carregada.

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

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

Carregar um mapa

Você também pode carregar um mapa criado pela API Google Maps JavaScript. como um que já esteja em uso.

Por exemplo, suponha que você tenha uma página da Web com google.maps.Map padrão entidade na qual 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>

Instancie um provedor de localização de remessas

Use o provedor de localização de remessas com o token de autorização que você definiu anteriormente para começar a receber dados do Fleet Engine.

Esses exemplos mostram como instanciar o provedor de localização.

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 que o mapa mostre a jornada compartilhada, você precisa inicializar o , que define o frame do próprio mapa para corresponder ao local da jornada acompanhada fornecida pelo SDK do consumidor depois de receber as informações de Fleet Engine.

Dicas:

  1. Verifique se a página contém um elemento &lt;div&gt; que contém a visualização de mapa. No exemplo a seguir, o elemento &lt;div&gt; é denominado map_canvas.

  2. Conheça as regras de visibilidade padrão que o Fleet Engine aplica aos eventos e suas jornadas. Você também pode configurar regras de visibilidade para veículos ativos em tarefas de remessa e paradas programadas. Consulte Personalizar a visibilidade da tarefa na Guia de configuração de tarefas.

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 progresso do envio

É possível detectar eventos e atualizar o andamento do frete como uma jornada avança. Use o provedor de localização para recuperar metainformações do taskTrackingInfo. Alterações na meta informações acionam um evento update. O objeto taskTrackingInfo fornece o seguinte:

  • HEC
  • Número de paradas restantes
  • Distância restante antes da retirada 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);
});

Critérios de exibição para várias tarefas

O SDK do consumidor para tarefas programadas mostra apenas uma tarefa por ID de acompanhamento em no mapa. No entanto, normalmente você atribui um ID de acompanhamento a um um produto de envio que permanece associado a ele ao longo de toda a jornada; no sistema. Isso significa que um único ID de acompanhamento pode ser associado a várias tarefas, como uma tarefa de retirada seguida por uma tarefa de entrega para o mesmo pacote ou várias tarefas de remessa com falha para um pacote.

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

Critérios da tarefa Resultado
Tarefas de retirada abertas
Existe exatamente um Mostrar a tarefa
Vários Gerar erro
Tarefas de retirada fechadas
Exatamente um existe Mostrar a tarefa
Existem vários (alguns com tempos de resultado) Mostrar tarefa com o horário de resultado mais recente
Várias existem (nenhuma com horários de resultado) Gerar erro
Abrir as tarefas de entrega
Existe exatamente um Mostrar a tarefa
Vários Gerar erro
Tarefas de entrega fechada
Existe exatamente um Mostrar a tarefa
Existem vários (alguns com tempos de resultado) Mostrar tarefa com o horário de resultado mais recente
Várias existem (nenhuma com horários de resultado) Gerar erro

Parar de seguir uma remessa

Quando uma jornada de envio for concluída ou cancelada, seu app para o consumidor deverá encerrar o compartilhamento da jornada removendo o ID de acompanhamento e o provedor de localização a visualização de mapa.

Remover o ID de acompanhamento

Para impedir que o provedor de localização rastreie o envio, remova o ID de rastreamento do provedor de localização. Os exemplos abaixo mostram como fazer isso.

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

Lidar com erros de rastreamento de envio

Erros que surgem de forma assíncrona ao solicitar informações de envio do acionador 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: é necessário agrupar as chamadas de biblioteca em blocos try...catch para processar erros inesperados.

A seguir