Sigue un envío

Ahora que configuraste el SDK de JavaScript Consumer para tareas programadas, puedes seguir un envío con tu app para consumidores. En este documento, se abarcan los siguientes pasos clave de este proceso:

Inicializar un mapa y mostrar el viaje compartido
Actualizar y seguir el progreso del viaje
Dejar de seguir un envío
Controlar los errores de seguimiento de envíos

Configura un mapa

Para seguir la recolección o la entrega de un envío en tu app web, debes cargar un mapa y crear una instancia del SDK de Consumer para comenzar a hacer un seguimiento del envío. Puedes cargar un mapa nuevo o usar uno existente. Luego, usa la función de inicialización para crear una instancia del SDK de Consumer de modo que la vista de mapa corresponda a la ubicación del artículo que se está siguiendo.

Carga un mapa nuevo con la API de Google Maps JavaScript

Para crear un mapa nuevo, carga la API de Google Maps JavaScript en tu app web. En el siguiente ejemplo, se muestra cómo cargar la API de Google Maps JavaScript, habilitar el SDK y activar la verificación de inicialización.

El parámetro callback ejecuta la función initMap después de que se carga la API.
El atributo defer permite que el navegador siga renderizando el resto de la página mientras se carga la API.

Usa la función initMap para crear una instancia del SDK de Consumer. Por ejemplo:

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

Carga un mapa existente

También puedes cargar un mapa existente creado por la API de Google Maps JavaScript, como uno que ya estés usando.

Por ejemplo, supongamos que tienes una página web con una entidad google.maps.Map estándar en la que se muestra un marcador como se define en el siguiente código HTML. Esto muestra tu mapa con la misma función initMap en la devolución de llamada al 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>

Crea una instancia de un proveedor de ubicación de envío

Usa el proveedor de ubicación de envío, junto con el captador de tokens de autorización que definiste anteriormente, para comenzar a recibir datos de Fleet Engine.

En estos ejemplos, se muestra cómo crear una instancia del proveedor de ubicación.

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

Muestra el viaje compartido

Para mostrar el progreso de una tarea programada, inicializa su vista, que establece el marco para que el mapa corresponda a la ubicación del viaje seguido. Luego, el SDK de Consumer proporciona el progreso después de obtener la información de Fleet Engine.

Sugerencias:

Asegúrate de que tu página contenga un <div> elemento que contenga la vista de mapa. En el siguiente ejemplo, el <div> elemento se llama map_canvas.
Ten en cuenta las reglas de visibilidad predeterminadas que Fleet Engine aplica a los viajes seguidos. También puedes configurar reglas de visibilidad para el envío de vehículos activos y las tareas de paradas programadas. Consulta Personaliza la visibilidad de las tareas en la Configura tareas guía.

En estos ejemplos, se muestra cómo inicializar una vista 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);
}

Actualiza el progreso del envío

Puedes escuchar eventos y actualizar el progreso del envío a medida que avanza un viaje. Usa el proveedor de ubicación para recuperar metainformación del objeto taskTrackingInfo. Los cambios en la metainformación activan un evento de actualización. El objeto taskTrackingInfo proporciona lo siguiente:

ETA
Cantidad de paradas restantes
Distancia restante antes de la recolección o la entrega

En el siguiente ejemplo, se muestra cómo escuchar estos eventos de cambio.

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

Muestra criterios para varias tareas

El SDK de Consumer para tareas programadas muestra solo una tarea por ID de seguimiento en el mapa. Sin embargo, también sueles asignar un ID de seguimiento a un artículo de envío específico que permanece asociado con el artículo durante todo su viaje en tu sistema. Esto significa que un solo ID de seguimiento puede estar asociado con varias tareas, como una tarea de recolección seguida de una tarea de entrega para el mismo paquete o varias tareas de envío fallidas para un paquete.

Para controlar esta situación, Fleet Engine aplica criterios para mostrar tareas, que se muestran en la siguiente tabla.

Criterios de la tarea	Resultado
Tareas de recolección abiertas
Existe exactamente una	Mostrar la tarea
Existen varias	Generar error
Tareas de recolección cerradas
Existe exactamente una	Mostrar la tarea
Existen varias (algunas con horarios de resultado)	Mostrar la tarea con el horario de resultado más reciente
Existen varias (ninguna con horarios de resultado)	Generar error
Tareas de entrega abiertas
Existe exactamente una	Mostrar la tarea
Existen varias	Generar error
Tareas de entrega cerradas
Existe exactamente una	Mostrar la tarea
Existen varias (algunas con horarios de resultado)	Mostrar la tarea con el horario de resultado más reciente
Existen varias (ninguna con horarios de resultado)	Generar error

Dejar de seguir un envío

Cuando se completa o se cancela un viaje de envío, tu app para consumidores debe dejar de seguir un envío quitando el ID de seguimiento y el proveedor de ubicación de la vista de mapa. Para obtener detalles, consulta las siguientes secciones.

Quita el ID de seguimiento

Para evitar que el proveedor de ubicación haga un seguimiento del envío, quita el ID de seguimiento del proveedor de ubicación. En los siguientes ejemplos, se muestra cómo hacerlo.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Quita el proveedor de ubicación de la vista de mapa

En el siguiente ejemplo, se muestra cómo quitar un proveedor de ubicación de la vista de mapa.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Controla los errores de seguimiento de envíos

Los errores que surgen de forma asíncrona cuando se solicita información de envío activan eventos de error. En el siguiente ejemplo, se muestra cómo escuchar estos eventos para controlar los errores.

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

Nota: Asegúrate de incluir las llamadas a la biblioteca en bloques try...catch para controlar los errores imprevistos.

¿Qué sigue?

Diseña un mapa

Sigue un envío Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Configura un mapa

Carga un mapa nuevo con la API de Google Maps JavaScript

Carga un mapa existente

Crea una instancia de un proveedor de ubicación de envío

JavaScript

TypeScript

Muestra el viaje compartido

JavaScript

TypeScript

Actualiza el progreso del envío

JavaScript

TypeScript

Muestra criterios para varias tareas

Dejar de seguir un envío

Quita el ID de seguimiento

JavaScript

TypeScript

Quita el proveedor de ubicación de la vista de mapa

JavaScript

TypeScript

Controla los errores de seguimiento de envíos

JavaScript

TypeScript

¿Qué sigue?

Sigue un envío