Ahora que configuraste el SDK para consumidores de JavaScript para tareas programadas, estás listo para 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 recorrido
- 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óninitMap
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>
Cómo cargar un mapa existente
También puedes cargar un mapa existente creado por la API de Google Maps JavaScript, como uno que ya tengas en uso.
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 del consumidor proporciona el progreso después de que obtiene la información de Fleet Engine.
Sugerencias:
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
.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 del retiro 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);
});
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 | Muestra 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 | Muestra 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 el consumidor 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 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);
Soluciona 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 errores inesperados.