Cuando sigues un viaje, tu app para consumidores muestra al consumidor la ubicación del vehículo correspondiente. Para ello, tu app debe comenzar a seguir el viaje, actualizar el progreso del viaje durante el viaje y dejar de seguir el viaje cuando se complete.
En este documento, se abarcan los siguientes pasos clave en este proceso:
- Cómo configurar un mapa
- Inicializa un mapa y muestra el recorrido compartido
- Actualiza y sigue el progreso del viaje
- Cómo dejar de seguir un viaje
- Cómo controlar los errores de viaje
Cómo configurar un mapa
Para seguir el retiro o la entrega de un envío en tu app web, debes cargar un mapa y crear una instancia del SDK del consumidor para comenzar a hacer un seguimiento de tu recorrido. Puedes cargar un mapa nuevo o usar uno existente. Luego, utiliza la función de inicialización para crear una instancia del SDK del consumidor, de modo que la vista de mapa corresponda a la ubicación del elemento del que se realiza el 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 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>
Cómo reemplazar un mapa existente
Puedes reemplazar un mapa existente que incluya marcadores o cualquier otra personalización sin perderlos.
Por ejemplo, si tienes una página web con una entidad google.maps.Map
estándar en la que se muestra un marcador, puedes reemplazar el mapa y conservarlo. En esta sección, se describen los pasos para hacerlo.
Para reemplazar el mapa y mantener las personalizaciones, agrega viajes compartidos a tu página HTML con estos pasos, que también están numerados en el siguiente ejemplo:
Agrega código para la fábrica del token de autenticación.
Inicializa un proveedor de ubicación en la función
initMap()
.Inicializa la vista de mapa en la función
initMap()
. La vista contiene el mapa.Mueve tu personalización a la función de devolución de llamada para inicializar la vista de mapa.
Agrega la biblioteca de ubicaciones al cargador de API.
En el siguiente ejemplo, se muestran los cambios que se deben realizar. Si realizas un viaje con el ID especificado cerca de Uluru, ahora se renderizará en el mapa:
<!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>
let locationProvider;
// (1) Authentication Token Fetcher
async function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
// Initialize and add the map
function initMap() {
// (2) Initialize location provider.
locationProvider = new google.maps.journeySharing.FleetEngineTripLocationProvider({
projectId: "YOUR_PROVIDER_ID",
authTokenFetcher,
});
// (3) Initialize map view (which contains the map).
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map'),
locationProviders: [locationProvider],
// any styling options
});
locationProvider.tripId = TRIP_ID;
// (4) Add customizations like before.
// 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 async attribute allows the browser to render the page while the API loads
* The key parameter will contain your own API key (which is not needed for this tutorial)
* The callback parameter executes the initMap() function
*
* (5) Add the SDK to the API loader.
-->
<script defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
</script>
</body>
</html>
Inicializa un mapa y muestra el progreso del viaje
Cuando comienza un viaje, tu app debe crear una instancia de un proveedor de ubicación de viaje y, luego, inicializar un mapa para comenzar a compartir el progreso del viaje. Consulta las siguientes secciones para ver ejemplos.
Crea una instancia de un proveedor de ubicación de viajes
El SDK de JavaScript tiene un proveedor de ubicación predefinido para la API de transporte compartido de Fleet Engine. Usa el ID de tu proyecto y una referencia a tu fábrica de tokens para crear una instancia.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
Cómo inicializar la vista de mapa
Después de cargar el SDK de JavaScript, inicializa la vista del mapa y agrégala a la página HTML. Tu página debe contener un elemento <div>
que contenga la vista del mapa. En el siguiente ejemplo, el elemento <div>
se llama map_canvas
.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
Actualiza y sigue el progreso del viaje
Tu app debe escuchar eventos y actualizar el progreso del viaje a medida que avanza. Puedes recuperar información meta sobre un viaje desde el objeto de tarea utilizando el proveedor de ubicación. La metainformación incluye la hora de llegada estimada y la distancia restante antes de la partida o el destino. Los cambios en la metainformación activan un evento update. En el siguiente ejemplo, se muestra cómo escuchar estos eventos de cambio.
JavaScript
locationProvider.addListener('update', e => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
TypeScript
locationProvider.addListener('update', (e:
google.maps.journeySharing.FleetEngineTripLocationProviderUpdateEvent) => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
Cómo dejar de seguir un viaje
Una vez finalizado el viaje, debes impedir que el proveedor de ubicación realice el seguimiento. Para ello, debes quitar el ID de viaje y el proveedor de ubicación. Consulta las siguientes secciones para ver ejemplos.
Quita el ID de viaje del proveedor de ubicación
En el siguiente ejemplo, se muestra cómo quitar un ID de viaje del proveedor de ubicación.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
Quitar 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);
Maneja errores de viajes
Los errores que surgen de forma asíncrona cuando se solicita información del viaje activan eventos de error. En el siguiente ejemplo, se muestra cómo escuchar estos eventos para controlar errores.
JavaScript
locationProvider.addListener('error', e => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});
TypeScript
locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});