Sigue un envío

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

  • Inicializa un mapa y muestra el viaje compartido
  • Actualiza y sigue el progreso del viaje
  • Cómo dejar de seguir un envío
  • Cómo controlar los errores de seguimiento de envíos

Cómo configurar un mapa

Para seguir la recolección o 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 para consumidores, de modo que la vista del mapa corresponda a la ubicación del elemento al que se le está haciendo un seguimiento.

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 tu 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 Maps JavaScript de Google, 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 del envío junto con el recuperador 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
  });

Cómo mostrar el viaje compartido

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

Sugerencias:

  1. Asegúrate de que tu página contenga un elemento <div> que contenga la vista del mapa. En el siguiente ejemplo, el elemento <div> se llama map_canvas.

  2. Ten en cuenta las reglas de visibilidad predeterminadas que Fleet Engine aplica a los recorridos con seguimiento. También puedes configurar reglas de visibilidad para el envío de vehículos activos y las tareas de paradas programadas. Consulta Cómo personalizar la visibilidad de las tareas en la guía Cómo configurar tareas.

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 detectar eventos y actualizar el progreso del envío a medida que avanza un recorrido. Usa el proveedor de ubicación para recuperar metainformación del objeto taskTrackingInfo. Los cambios en la información de metadatos 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 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);
});

Cómo mostrar criterios para varias tareas

El SDK para consumidores de 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 bien de envío específico que permanece asociado con el bien durante su recorrido en tu sistema. Esto significa que un solo ID de seguimiento puede estar asociado con varias tareas, como una tarea de retiro 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, como se muestra en la siguiente tabla.

Criterios de tareas Resultado
Abrir tareas de retiro
Existe exactamente uno Cómo mostrar la tarea
Existen varios Genera un error
Tareas de retiro cerradas
Existe exactamente uno Cómo mostrar la tarea
Existen varios (algunos con tiempos de resultado) Mostrar la tarea con la hora del resultado más reciente
Existen varios (ninguno con tiempos de resultado) Genera un error
Abrir tareas de publicación
Existe exactamente uno Cómo mostrar la tarea
Existen varios Genera un error
Tareas de publicación cerradas
Existe exactamente uno Cómo mostrar la tarea
Existen varios (algunos con tiempos de resultado) Mostrar la tarea con la hora del resultado más reciente
Existen varios (ninguno con tiempos de resultado) Genera un error

Cómo dejar de seguir un envío

Cuando se completa o se cancela un recorrido 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 del mapa. Para obtener detalles, consulta las siguientes secciones.

Quita el ID de seguimiento

Para evitar que el proveedor de ubicación realice 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 = '';

Cómo quitar el proveedor de ubicación de la vista del 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);

Cómo controlar los errores de seguimiento de envíos

Los errores que surgen de forma asíncrona cuando se solicita información del 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 unir las llamadas a la biblioteca en bloques try...catch para controlar los errores imprevistos.

¿Qué sigue?