Cómo hacer un seguimiento de los envíos con la biblioteca de seguimiento de envíos de JavaScript

La biblioteca de seguimiento de envíos de JavaScript te permite visualizar la ubicación de los vehículos y las ubicaciones de interés que se rastrean en Fleet Engine. La biblioteca 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. Con la biblioteca de seguimiento de envíos de JavaScript, puedes proporcionar una experiencia de seguimiento de envío personalizada y animada desde tu aplicación web.

Componentes

La biblioteca de seguimiento de envíos de JavaScript proporciona componentes para visualizar el vehículo y la ruta a medida que avanza a un destino, así como feeds de datos sin procesar para la hora de llegada estimada de un conductor o la distancia restante de conducción.

Vista de mapa de seguimiento de envíos

El componente de vista de mapa visualiza la ubicación de vehículos y los destinos. Si se conoce la ruta de un vehículo, el componente de vista de mapa anima ese vehículo a medida que se desplaza por su ruta prevista.

Proveedor de ubicación de envío

Un proveedor de ubicación de envío proporciona información sobre la ubicación de los objetos rastreados en el mapa de seguimiento de envíos para el seguimiento del envío en la primera y la última milla.

Puedes usar el proveedor de ubicación de envío para realizar el seguimiento de lo siguiente:

  • Es la ubicación de retiro o entrega de un envío.
  • La ubicación y la ruta del vehículo de entrega.

Objetos de ubicación a los que se les hizo un seguimiento

El proveedor de ubicación hace un seguimiento de la ubicación de objetos como vehículos y destinos.

Ubicación de destino

La ubicación de destino es donde termina un viaje. Para el seguimiento del envío, es la ubicación planificada de la tarea.

Ubicación del vehículo

La ubicación del vehículo es la ubicación registrada de un vehículo. De manera opcional, puede incluir una ruta para el vehículo.

Recuperador de tokens de autenticación

Para controlar el acceso a los datos de ubicación almacenados en Fleet Engine, debes implementar un servicio de creación de token web JSON (JWT) para Fleet Engine en tu servidor. Luego, implementa una herramienta de recuperación de tokens de autenticación como parte de tu aplicación web. Para ello, usa la biblioteca de JavaScript Journey Share para autenticar el acceso a los datos de ubicación.

Opciones de diseño

Los diseños de marcadores y polilíneas determinan el aspecto de los objetos de ubicación a los que se hace seguimiento en el mapa. Puedes usar opciones de diseño personalizadas para cambiar el diseño predeterminado a fin de que coincida con el de tu aplicación web.

Cómo controlar la visibilidad de las ubicaciones que sigues

En esta sección, se describen los controles de visibilidad para los objetos registrados en el mapa. Estas reglas se aplican a dos categorías de objetos:

  • Marcador de ubicación
  • Datos de tareas

Visibilidad del marcador de ubicación

Todos los marcadores de ubicación del origen y el destino siempre se muestran en el mapa. Por ejemplo, una ubicación de entrega de envío siempre se muestra en el mapa, independientemente del estado de la entrega.

Visibilidad de datos de tareas

En esta sección, se describen las reglas de visibilidad predeterminadas que se aplican a los datos de tareas, como la ubicación del vehículo y la ruta restante. Puedes personalizar muchas tareas, pero no todas:

  • Tareas no disponibles: No se puede personalizar la visibilidad de estas tareas.
  • Tareas activas del vehículo: Puedes personalizar este tipo de tareas.
  • Tareas de vehículos inactivas: No puedes personalizar la visibilidad de estas tareas.

Tareas de no disponibilidad

Si hay al menos una tarea de no disponibilidad (por ejemplo, si el conductor se toma un descanso o el vehículo se está recargando) en la ruta hacia la tarea que se está rastreando, el vehículo no estará visible. La hora estimada de llegada y la hora estimada de finalización de la tarea todavía están disponibles.

Tareas activas del vehículo

El objeto TaskTrackingInfo proporciona varios elementos de datos que se pueden hacer visibles en la Biblioteca de seguimiento de envíos. De forma predeterminada, estos campos son visibles cuando se asigna la tarea al vehículo y cuando este se encuentra a 5 paradas de la tarea. La visibilidad finaliza cuando se completa o cancela la tarea. Los campos son los siguientes:

  • Polilíneas de ruta
  • Tiempo estimado hasta la llegada
  • Tiempo estimado de finalización de la tarea
  • Distancia restante en automóvil hasta la tarea
  • Recuento de paradas restantes
  • Ubicación del vehículo

Puedes personalizar la configuración de visibilidad por tarea si configuras TaskTrackingViewConfig en una tarea cuando creas o actualizas la tarea en Fleet Engine. Esto crea reglas sobre cuándo están disponibles los elementos de datos individuales, que pueden basarse en los siguientes criterios (denominados como opción de visibilidad a continuación):

  • Recuento de paradas restantes
  • Duración hasta la hora de llegada estimada
  • Distancia restante en automóvil
  • Siempre visible
  • Nunca visible

Ten en cuenta que cada elemento de datos solo se puede asociar con una opción de visibilidad. No es posible combinar criterios usando O o Y.

El siguiente es un ejemplo de personalización. Las reglas de esa personalización son las siguientes:

  • Muestra las polilíneas de la ruta si el vehículo está a 3 paradas.
  • Muestra la hora de llegada estimada si la distancia de conducción restante es inferior a 5,000 metros.
  • No mostrar nunca la cantidad de paradas restantes.
  • Los demás campos conservan la visibilidad predeterminada que se muestra cuando el vehículo está a 5 paradas de la tarea.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

También puedes personalizar la configuración de visibilidad predeterminada de tu proyecto. Para ello, comunícate con el equipo de asistencia al cliente.

Polilíneas de ruta y reglas de visibilidad de la ubicación del vehículo:

Cuando las polilíneas de rutas son visibles, también se debe ver la ubicación del vehículo. De lo contrario, se puede indicar al final de las polilíneas. Esto significa que las polilíneas de rutas no pueden tener una opción de visibilidad menos restrictiva.

Debes seguir estas reglas para proporcionar una combinación válida de polilíneas de rutas y ubicación del vehículo:

  • Cuando las polilíneas de rutas y la ubicación del vehículo tienen el mismo tipo de opción de visibilidad, ocurre lo siguiente:

    • Si la opción de visibilidad es el recuento de paradas restantes, la duración hasta la hora de llegada estimada o la distancia en automóvil restante, las polilíneas de rutas deben proporcionar un valor menor o igual que el valor establecido para esta opción de visibilidad para la ubicación del vehículo. El siguiente es un ejemplo:
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • Si las polilíneas de rutas tienen una opción de visibilidad siempre visible, la ubicación del vehículo también debe proporcionar una opción de visibilidad siempre visible.
    • Si la ubicación del vehículo tiene una opción de visibilidad nunca visible, las polilíneas de rutas también deben proporcionar una opción de visibilidad nunca visible.
  • Cuando las polilíneas de rutas y la ubicación del vehículo tienen tipos de opciones de visibilidad diferentes, la ubicación del vehículo solo se muestra cuando se cumplen ambas opciones de visibilidad.

    El siguiente es un ejemplo:

    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingDrivingDistanceMetersThreshold": 3000
      },
    }
    

    En este ejemplo, la ubicación del vehículo solo es visible si el recuento de paradas restante es de al menos 3 Y la distancia restante en automóvil es de al menos 3,000 metros.

Comienza a usar la biblioteca de viajes compartidos de JavaScript

Antes de usar la biblioteca de recorrido compartido de JavaScript, asegúrate de estar familiarizado con Fleet Engine y con obtener una clave de API.

Para realizar el seguimiento de una publicación, primero crea un reclamo de ID de seguimiento.

Cómo crear un reclamo de ID de seguimiento

Para realizar el seguimiento de un envío mediante el proveedor de ubicación de envío, crea un token web JSON (JWT) con una reclamación de ID de seguimiento.

Para crear la carga útil de JWT, agrega una reclamación adicional en la sección de autorización con la clave trackingid. Establece su valor como el ID de seguimiento del envío.

En el siguiente ejemplo, se muestra cómo crear un token para realizar el seguimiento por ID de seguimiento:

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

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 envío de JavaScript solicita un token a través de la herramienta de recuperación 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 seguimiento de envíos 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 envío

En esta sección, se muestra cómo usar la biblioteca de JavaScript Shipment Tracking para realizar un seguimiento de un envío o una 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.

Cómo crear una instancia de proveedor de ubicación de envío

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

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-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.

Para evitar condiciones de carrera, establece el ID de seguimiento del proveedor de ubicación en la devolución de llamada que se invoca después de inicializar el mapa.

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // 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 will start 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

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // 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 will start 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);

ID de seguimiento

El ID de seguimiento proporcionado al proveedor de ubicación puede corresponder a varias tareas; por ejemplo, una tarea de retiro y entrega para el mismo paquete o varios intentos de entrega fallidos. Se selecciona una tarea para que se muestre en el mapa de seguimiento del envío. La tarea que se mostrará se determina de la siguiente manera:

  1. Si hay exactamente una tarea de retiro abierta, se muestra. Se genera un error si hay varias tareas de retiro abierto.
  2. Si hay exactamente una tarea de entrega abierta, se muestra. Se genera un error si hay varias tareas de entrega abierta.
  3. Si hay tareas de entrega cerrada, haz lo siguiente:
    • Si hay exactamente una tarea de entrega cerrada, se muestra.
    • Si hay varias tareas de entrega cerrada, se mostrará la que tenga el tiempo de resultado más reciente.
    • Si hay varias tareas de entrega cerrada, pero ninguna de ellas tiene un plazo de resultado, se genera un error.
  4. Si hay tareas de retiro cerradas, haz lo siguiente:
    • Si hay exactamente una tarea de retiro cerrada, se muestra.
    • Si hay varias tareas de retiro cerradas, se mostrará la que tenga el tiempo de resultado más reciente.
    • Si hay varias tareas de retiro cerradas, ninguna de las cuales tiene un tiempo de resultado, se genera un error.
  5. De lo contrario, no se muestra ninguna tarea.

Cómo escuchar eventos de cambio

Puedes recuperar la metainformación sobre una tarea desde el objeto de información de seguimiento de tareas mediante el proveedor de ubicación. La información meta incluye la hora de llegada estimada, la cantidad de paradas restantes y la distancia restante antes de la partida o la entrega. 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.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 solucionar errores

Los errores que surgen de forma asíncrona de la solicitud de información de envío activan eventos 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);
});

Nota: Asegúrate de unir las llamadas a bibliotecas en bloques try...catch para controlar los errores inesperados.

Detener el seguimiento

Para evitar que el proveedor de ubicación siga el envío, quita el ID de seguimiento del proveedor.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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 envíos 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'
  }
  // Any other styling options.
});

TypeScript

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

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 cambiar el diseño y la visibilidad de las rutas

Para configurar el diseño y la visibilidad de las rutas tomadas y previstas, utiliza opciones de diseño personalizadas. Para obtener más información, consulta Interfaz de PolylineOptions.

En el siguiente ejemplo, se muestra cómo configurar el diseño y la visibilidad de las rutas anticipadas. Para configurar el diseño y la visibilidad de las rutas tomadas, utiliza takenRoutePolylineSetup en lugar de anticipatedRoutePolylineSetup.

JavaScript

// This function is specified in the 
// JourneySharingMapView constructor's options 
// parameter.
function anticipatedRoutePolylineSetup({
    defaultPolylineOptions, defaultVisible}) {
  // If this function is not specified, the 
  // PolylineOptions object contained in 
  // defaultPolylineOptions is used to render the
  // anticipated route polyline. visible property sets the
  // polyline's visibility. Modify this object and 
  // pass it back to customize the style of the map.
  defaultPolylineOptions.strokeOpacity = 0.5;
  defaultPolylineOptions.strokeColor = 'red';
  return {
    polylineOptions: defaultPolylineOptions,
    visible: true
  };
}

// As an alternative, set a static PolylineOptions to 
// use for the anticipated route:
const anticipatedRoutePolylineOptionsSetup = {
  polylineOptions: {
    strokeOpacity: 0.5,
    strokeColor: 'red',
    …
  },
  visible: true,
};

TypeScript

// This function is specified in the 
// JourneySharingMapView constructor's options 
// parameter.
function anticipatedRoutePolylineSetup(options: {
  defaultPolylineOptions: google.maps.PolylineOptions,
  visible: boolean,
}): {
  polylineOptions: google.maps.PolylineOptions,
  visible: boolean,
} {
  // If this function is not specified, the 
  // PolylineOptions object contained in 
  // defaultPolylineOptions is used to render the
  // anticipated route polyline. visible property sets the
  // polyline's visibility. Modify this object and 
  // pass it back to customize the style of the map.
  options.defaultPolylineOptions.strokeOpacity = 0.5;
  options.defaultPolylineOptions.strokeColor = 'red';
  return {
    polylineOptions: options.defaultPolylineOptions,
    visible: true
  };
}

// As an alternative, set a static PolylineOptions to 
// use for the anticipated route:
const anticipatedRoutePolylineSetup = {
  polylineOptions: {
    strokeOpacity: 0.5,
    strokeColor: 'red',
    …
  },
  visible: true,
};

Cómo personalizar los marcadores

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

La personalización más simple 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 envíos pasa datos a la función de personalización sobre el tipo de objeto que representa el marcador: vehículo o destino. 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 previstas restantes hasta el destino). Incluso puedes unir datos de fuentes fuera de Fleet Engine y diseñar el marcador en función de esa información.

La biblioteca de seguimiento de envíos proporciona los siguientes parámetros de personalización en FleetEngineShipmentLocationProviderOptions:

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 las personalizaciones de marcadores mencionadas 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.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    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: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

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

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

Cómo reemplazar un mapa existente

Puedes usar la biblioteca de JavaScript Shipment Tracking para reemplazar un mapa existente que incluya marcadores o cualquier otra personalización sin perderlas.

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, 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.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    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.trackingId = TRACKING_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.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

Si tienes un paquete con seguimiento con el ID especificado cerca de Uluru, ahora se renderizará en el mapa.