Realiza un seguimiento de tu flota con la biblioteca de seguimiento de la flota de JavaScript

La biblioteca de seguimiento de flota de JavaScript te permite visualizar las ubicaciones de los vehículos en sus flotas casi en tiempo real. La biblioteca usa la API de Deliveries para permitir la visualización de vehículos de entrega y las tareas. Al igual que la biblioteca de seguimiento de envío de JavaScript, contiene un componente de mapa de JavaScript que es un reemplazo directo de una entidad google.maps.Map estándar y componentes de datos para conectarse con Fleet Engine.

Componentes

La biblioteca de seguimiento de flota de JavaScript proporciona componentes para visualizar vehículos de entrega y paradas, además de feeds de datos sin procesar para la hora de llegada estimada o la distancia restante hasta una entrega.

Vista de mapa de seguimiento de flota

El componente de vista de mapa de seguimiento de flota visualiza la ubicación de los vehículos y las tareas. Si se conoce la ruta de un vehículo, el componente de vista de mapa animará ese vehículo a medida que se mueva por su ruta prevista.

Ejemplo de vista de mapa de seguimiento de flota

Proveedores de ubicación

Los proveedores de ubicación trabajan con información almacenada en Fleet Engine para enviar información de ubicación de los objetos rastreados al mapa de uso compartido de viajes.

Proveedor de ubicación del vehículo de entrega

El proveedor de ubicación del vehículo de entrega muestra la información de ubicación de un solo vehículo de entrega. Contiene información sobre la ubicación del vehículo, así como las tareas que completó el vehículo de entrega.

Proveedor de ubicación de flota de entregas

El proveedor de ubicación de la flota de entregas muestra información sobre la ubicación de varios vehículos. Puedes filtrar por ubicaciones o vehículos específicos, o mostrar toda la flota.

Cómo controlar la visibilidad de las ubicaciones que sigues

En esta sección, se describen las reglas de visibilidad de los objetos de ubicación con seguimiento en el mapa para el proveedor de ubicación predefinido de Fleet Engine. Los proveedores de ubicación personalizada o derivada pueden cambiar las reglas de visibilidad.

Vehículos de entrega

Un vehículo de entrega es visible en cuanto se crea en Fleet Engine y se puede ver en todo su recorrido, independientemente de sus tareas.

Marcadores de ubicación de tareas

Las paradas de vehículos planificados se muestran en el mapa como marcadores de paradas de vehículos. Los marcadores de las tareas completadas se muestran con un diseño diferente del de las paradas planificadas de un vehículo.

La ubicación de los resultados de la tarea se muestra con marcadores de resultado de la tarea. Las tareas con un resultado SUCCEEDED se muestran con marcadores de tareas exitosas, mientras que todas las demás tareas se muestran con marcadores de tareas fallidas.

Comienza a usar la biblioteca de seguimiento de flota de JavaScript

Antes de usar la biblioteca de seguimiento de flota de JavaScript, asegúrate de estar familiarizado con Fleet Engine y con obtener una clave de API. Luego, crea un ID de tarea y un reclamo de ID de vehículo de entrega.

Cómo crear un ID de tarea y un reclamo de ID de vehículo de entrega

Para realizar un seguimiento de los vehículos de entrega con el proveedor de ubicación de vehículos de entrega, crea un token web JSON (JWT) con un ID de tarea y una reclamación de ID de vehículo de entrega.

Para crear la carga útil de JWT, agrega una reclamación adicional en la sección de autorización con las claves taskid y deliveryvehicleid y establece el valor de cada clave en *. El token se debe crear con la función de Cloud IAM de superusuario de servicio de Fleet Engine. Ten en cuenta que esto otorga acceso amplio para crear, leer y modificar entidades de Fleet Engine, y solo debe compartirse con usuarios de confianza.

En el siguiente ejemplo, se muestra cómo crear un token para el seguimiento por vehículo y tarea:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
  "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "taskid": "*",
     "deliveryvehicleid": "*",
   }
}

Crea un recuperador de tokens de autenticación

Puedes crear un recuperador de tokens de autenticación para recuperar un token emitido con las reclamaciones apropiadas en tus servidores mediante un certificado de cuenta de servicio para tu proyecto. Es importante que solo crees tokens en tus servidores y nunca los compartas con ningún cliente. De lo contrario, comprometerás la seguridad de tu sistema.

La herramienta de recuperación debe mostrar una estructura de datos con dos campos, dentro de una promesa:

  • Una cadena token.
  • Un número expiresInSeconds. Un token vence en este período después de la recuperación.

La biblioteca de seguimiento de flota de JavaScript solicita un token a través del recuperador de tokens de autenticación cuando se cumple alguna de las siguientes condiciones:

  • No tiene un token válido, como cuando no llamó a la herramienta de recuperación en una carga de página nueva o cuando la herramienta de recuperación no mostró un token.
  • El token que recuperó anteriormente venció.
  • El token que recuperó anteriormente se encuentra dentro del minuto de vencimiento.

De lo contrario, la biblioteca usa el token que se emitió anteriormente y que aún es válido, y no llama a la herramienta de recuperación.

En el siguiente ejemplo, se muestra cómo crear un recuperador de tokens de autenticación:

JavaScript

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

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  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.expiration_timestamp_ms - Date.now(),
  };
}

Cuando implementes el extremo del servidor para crear los tokens, ten en cuenta lo siguiente:

  • El extremo debe mostrar una hora de vencimiento del token. En el ejemplo anterior, se indica como data.ExpiresInSeconds.
  • La herramienta de recuperación de tokens de autenticación debe pasar la hora de vencimiento (en segundos, desde el momento de la recuperación) a la biblioteca, como se muestra en el ejemplo.
  • SERVER_TOKEN_URL depende de la implementación de tu backend. Estas son las URLs para el backend de la app de ejemplo:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

Cómo cargar un mapa desde HTML

En el siguiente ejemplo, se muestra cómo cargar la biblioteca de viajes compartidos de JavaScript desde una URL especificada. El parámetro devolución de llamada ejecuta la función initMap después de que se carga la API. El atributo defer permite que el navegador continúe procesando el resto de la página mientras se carga la API.

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

Sigue un vehículo de entrega

En esta sección, se muestra cómo usar la biblioteca de seguimiento de flota de JavaScript para seguir un vehículo de entrega. Asegúrate de cargar la biblioteca desde la función de devolución de llamada especificada en la etiqueta de la secuencia de comandos antes de ejecutar el código.

Crea una instancia de un proveedor de ubicación de vehículos de entrega

La biblioteca de seguimiento de flota de JavaScript predefine un proveedor de ubicación para la API de Fleet Engine Deliveries. Usa tu ID del proyecto y una referencia a la fábrica de tokens para crear una instancia.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, you may specify 
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, you may specify
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-id',
});

Cómo inicializar la vista de mapa

Después de cargar la biblioteca de JavaScript Journey Share, inicializa la vista de mapa y agrégala a la página HTML. Tu página debe contener un elemento <div> con 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 delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-vehicle-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('Times Square, New York, NY');
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 delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-vehicle-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('Times Square, New York, NY');
mapView.map.setZoom(14);

Cómo escuchar eventos de cambio

Puedes recuperar metainformación sobre una tarea del objeto deliveryVehicle mediante el proveedor de ubicación. La metainformación incluye la hora de llegada estimada y la distancia restante antes del próximo punto de partida o destino del vehículo. 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.deliveryVehicle contains data that may be        
  // useful to the rest of the UI.  
  if (e.deliveryVehicle) {
    console.log(e.deliveryVehicle.remainingDuration);
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  // e.deliveryVehicle contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicle) {
    console.log(e.deliveryVehicle.remainingDuration);
  }
});

Detecta errores

Los errores que surgen de forma asíncrona de la solicitud de información sobre el vehículo de entrega activan eventos de error. En el siguiente ejemplo, se muestra cómo escuchar estos eventos para manejar 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);
});

Detener el seguimiento

Para evitar que el proveedor de ubicación siga el vehículo de entrega, quita el ID del vehículo de entrega.

JavaScript

locationProvider.deliveryVehicleId = '';

TypeScript

locationProvider.deliveryVehicleId = '';

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

Visualiza una flota de entregas

En esta sección, se muestra cómo usar la biblioteca de JavaScript Journey Share para ver una flota de entregas. Asegúrate de cargar la biblioteca desde la función de devolución de llamada especificada en la etiqueta de la secuencia de comandos antes de ejecutar el código.

Crea una instancia de un proveedor de ubicación de la flota de entregas

La biblioteca de seguimiento de flota de JavaScript predefine un proveedor de ubicación que recupera varios vehículos desde la API de FleetEngine Deliveries. Usa el ID del proyecto y una referencia a la herramienta de recuperación de tokens para crear una instancia.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleFilter especifica una consulta que se usa para filtrar los vehículos que se muestran en el mapa. Este filtro se pasa directamente a Fleet Engine. Consulta ListDeliveryVehiclesRequest.filter para conocer los formatos compatibles.

locationRestriction limita el área en la que se muestran los vehículos en el mapa. También controla si el seguimiento de la ubicación está activo o no. El seguimiento de la ubicación no se iniciará hasta que se configure.

Una vez creado el proveedor de ubicación, inicializa la vista de mapa.

Cómo establecer una restricción de ubicación con el viewport del mapa

Los límites de locationRestriction se pueden configurar para que coincidan con el área visible actualmente en la vista de mapa.

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

Cómo escuchar eventos de cambio

Puedes recuperar información meta sobre la flota desde el objeto deliveryVehicles mediante el proveedor de ubicación. La metainformación incluye las propiedades del vehículo, como el estado de navegación, la distancia restante y los atributos personalizados. Consulta la documentación de referencia para obtener más detalles. 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.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryFleetLocationProviderUpdateEvent) => {
  // e.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

Detecta errores

Los errores que surgen de forma asíncrona de la solicitud de información de la flota de entregas activan eventos de error. Para ver ejemplos que muestren cómo detectar estos eventos, consulta Detecta errores.

Detener el seguimiento

Para evitar que el proveedor de ubicación rastree la flota de entregas, establece los límites del proveedor de ubicación en nulos.

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

Sigue un vehículo de reparto mientras visualizas una flota de entregas

Mientras visualizas una flota, puedes mostrar la ruta y las próximas tareas para un vehículo de entregas específico. Para ello, crea una instancia de un proveedor de ubicación de flota de entrega y un proveedor de ubicación de vehículo de entrega, y agrégalos a la vista de mapa:

JavaScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

TypeScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

El proveedor de ubicación de la flota de entregas comienza a mostrar los vehículos de entrega en el mapa. Usa la personalización de marcadores para permitir que el proveedor de ubicación del vehículo de entrega haga un seguimiento de un vehículo de entrega cuando se haga clic en el marcador de su flota:

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params: google.maps.journeySharing.DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

Oculta el marcador del proveedor de ubicación del vehículo de entrega a fin de evitar que se rendericen dos marcadores para el mismo vehículo:

JavaScript

// Specify the customization function either separately, or as a field in 
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params: deliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

Cómo personalizar el aspecto del mapa base

Para personalizar el aspecto del componente de mapas, realiza el diseño de tu mapa con herramientas basadas en la nube o configura opciones directamente en el código.

Cómo utilizar el diseño de mapas basado en Cloud

El diseño de mapas basado en Cloud te permite crear y editar diseños de mapa para cualquiera de tus apps que usen Google Maps desde la consola de Google Cloud sin necesidad de realizar cambios en tu código. Los diseños de mapa se guardan como IDs de mapa en tu proyecto de Cloud. Para aplicar un diseño al mapa de seguimiento de flota de JavaScript, especifica un mapId cuando crees el JourneySharingMapView. El campo mapId no se puede cambiar ni agregar después de que se crea una instancia de JourneySharingMapView. En el siguiente ejemplo, se muestra cómo habilitar un diseño de mapa creado anteriormente con un ID de mapa.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
});

Cómo utilizar el diseño de mapas basado en código

Otra forma de personalizar el diseño del mapa es establecer mapOptions cuando crees el elemento JourneySharingMapView.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

Cómo personalizar los marcadores

Con la biblioteca de seguimiento de flota de JavaScript, puedes personalizar el aspecto de los marcadores que se agregan al mapa. Para ello, especifica las personalizaciones de los marcadores, que la biblioteca de seguimiento de flotas aplica antes de agregar marcadores al mapa y con cada actualización de marcadores.

La personalización más sencilla consiste en especificar un objeto MarkerOptions que se aplicará a todos los marcadores del mismo tipo. Los cambios especificados en el objeto se aplican después de la creación de cada marcador y reemplazan las opciones predeterminadas.

Una opción más avanzada es especificar una función de personalización. Las funciones de personalización permiten definir el estilo de los marcadores según los datos, además de agregarles interactividad, por ejemplo, controlar los clics. Específicamente, el seguimiento de flota pasa datos a la función de personalización sobre el tipo de objeto que representa el marcador: vehículo, parada o tarea. De esta manera, el diseño del marcador puede cambiar en función del estado actual del elemento del marcador (por ejemplo, la cantidad de paradas restantes o el tipo de tarea). Incluso puedes unir datos de fuentes fuera de Fleet Engine y diseñar el marcador en función de esa información.

Además, puedes usar funciones de personalización para filtrar la visibilidad de los marcadores. Para ello, llama a setVisible(false) en el marcador.

Sin embargo, por motivos de rendimiento, recomendamos filtrar con el filtro nativo en el proveedor de ubicación, como FleetEngineDeliveryFleetLocationProvider.deliveryVehicleFilter. Dicho esto, cuando necesites funcionalidad de filtrado adicional, puedes aplicar el filtrado con la función de personalización.

La biblioteca de seguimiento de flota proporciona los siguientes parámetros de personalización:

Cambia el estilo de los marcadores con MarkerOptions.

En el siguiente ejemplo, se muestra cómo configurar el diseño de un marcador de vehículo con un objeto MarkerOptions. Sigue este patrón para personalizar el estilo de cualquier marcador con cualquiera de los parámetros de personalización de marcadores mencionados anteriormente.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Cambia el estilo de los marcadores con las funciones de personalización

En el siguiente ejemplo, se muestra cómo configurar el estilo de un marcador de vehículo. Sigue este patrón para personalizar el estilo de cualquier marcador mediante cualquiera de los parámetros de personalización mencionados anteriormente.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

Cómo agregar la administración de clics a los marcadores

En el siguiente ejemplo, se muestra cómo agregar el manejo de clics a un marcador de vehículo. Sigue este patrón para agregar el control de clics a cualquier marcador mediante cualquiera de los parámetros de personalización del marcador mencionados anteriormente.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

Filtrar marcadores visibles

En el siguiente ejemplo, se muestra cómo filtrar los marcadores de vehículos que son visibles. Sigue este patrón para filtrar cualquier marcador con cualquiera de los parámetros de personalización de marcadores mencionados anteriormente.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

Personaliza las polilíneas al seguir un vehículo de entregas

Con la biblioteca de seguimiento de flota de JavaScript, también puedes personalizar el aspecto de la ruta del vehículo que sigues en el mapa. La biblioteca crea un objeto google.maps.Polyline para cada par de coordenadas en la ruta activa o restante del vehículo. Para aplicar diseño a los objetos Polyline, especifica las personalizaciones de polilíneas. Luego, la biblioteca aplica estas personalizaciones en dos situaciones: antes de agregar objetos al mapa y cuando cambian los datos utilizados para los objetos.

Al igual que con la personalización de marcadores, puedes especificar un conjunto de PolylineOptions para que se aplique a todos los objetos Polyline coincidentes cuando se crean o actualizan.

Del mismo modo, puedes especificar una función de personalización. Las funciones de personalización permiten definir el estilo individual de los objetos según los datos que envía Fleet Engine. La función puede cambiar el diseño de cada objeto según el estado actual del vehículo; por ejemplo, colorear el objeto Polyline con un tono más profundo o hacerlo más grueso cuando el vehículo se mueve más lento. Incluso puedes unirte a fuentes externas a Fleet Engine y diseñar el objeto Polyline según esa información.

Puedes especificar las personalizaciones mediante los parámetros proporcionados en FleetEngineDeliveryVehicleLocationProviderOptions. Puedes configurar personalizaciones para los diferentes estados de la ruta en el recorrido del vehículo, ya sea recorrida, de forma activa o aún no recorrida. Los parámetros son los siguientes:

Cambia el estilo de los objetos Polyline con PolylineOptions.

En el siguiente ejemplo, se muestra cómo configurar el diseño de un objeto Polyline con PolylineOptions. Sigue este patrón para personalizar el diseño de cualquier objeto Polyline con cualquiera de las personalizaciones de polilíneas que se mencionaron anteriormente.

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

Cambia el estilo de los objetos Polyline con funciones de personalización

En el siguiente ejemplo, se muestra cómo configurar el diseño de un objeto Polyline activo con una función de personalización. Sigue este patrón para personalizar el estilo de cualquier objeto Polyline con cualquiera de los parámetros de personalización de polilíneas que se mencionaron anteriormente.

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: DeliveryVehiclePolylineCustomizationFunctionParams) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

Controla la visibilidad de los objetos Polyline

De forma predeterminada, todos los objetos Polyline son visibles. Para hacer que un objeto Polyline sea invisible, establece su propiedad visible:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Muestra un InfoWindow para un vehículo o un marcador de ubicación

Puedes utilizar un objeto InfoWindow para mostrar información adicional sobre un vehículo o un marcador de ubicación.

En el siguiente ejemplo, se muestra cómo crear un InfoWindow y adjuntarlo a un marcador de vehículo.

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 2. Attach the info window to a vehicle marker.   
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 2. Attach the info window to a vehicle marker.   
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

Inhabilitar el ajuste automático

Para evitar que el mapa se adapte automáticamente al viewport en el vehículo y la ruta anticipada, inhabilita el ajuste automático. En el siguiente ejemplo, se muestra cómo inhabilitar el ajuste automático cuando configuras la vista de mapa para compartir recorridos.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

Cómo reemplazar un mapa existente

Puedes reemplazar un mapa existente que incluya marcadores u otras personalizaciones sin perder esas personalizaciones.

Por ejemplo, supongamos que tienes una página web con una entidad google.maps.Map estándar en la que se muestra un marcador:

<!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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, 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.
    -->
    <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

Para agregar la biblioteca de JavaScript Journey Share, que incluye el seguimiento de flotas, haz lo siguiente:

  1. Agrega el código para la fábrica de tokens de autenticación.
  2. Inicializa un proveedor de ubicación en la función initMap().
  3. Inicializa la vista de mapa en la función initMap(). La vista contiene el mapa.
  4. Traslada tu personalización a la función de devolución de llamada para inicializar la vista de mapa.
  5. Agrega la biblioteca de ubicación al cargador de la API.

En el siguiente ejemplo, se muestran los cambios que se deben realizar:

<!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
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. Use FleetEngineDeliveryVehicleLocationProvider
  // as appropriate.
  locationProvider = new google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProvider({
    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
  });

mapView.addListener('ready', () => {
  locationProvider.deliveryVehicleId = DELIVERY_VEHICLE_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, 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 journey sharing library to the API loader, which includes Fleet Tracking functionality.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

Si conduces un vehículo de entregas con el ID especificado cerca de Uluru, ahora se renderizará en el mapa.