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 durante el viaje y dejar de seguirlo cuando se complete.
En este documento, se abordan los siguientes pasos clave de este proceso:
- Cómo configurar un mapa
- Inicializa un mapa y muestra el viaje 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 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 de tu viaje. 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
callbackejecuta la funcióninitMapdespués de que se carga la API. - El atributo
deferpermite que el navegador continúe 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. De esta manera, se mostrará el 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 conservar el marcador. En esta sección, se describen los pasos para hacerlo.
Para reemplazar el mapa y mantener las personalizaciones, agrega el uso compartido de viajes a tu página HTML siguiendo estos pasos, que también se numeran en el siguiente ejemplo:
Agrega código para la fábrica de tokens 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 la inicialización de 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 viajes 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 viaje
El SDK de JavaScript tiene un proveedor de ubicación predefinido para la API de Ridesharing 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',
});
Inicializa 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 de 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 del punto de partida o de destino. Los cambios en la metainformación activan un evento de actualización. 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, quita 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 = '';
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 viaje
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 los 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);
});