Conferir uma frota

Esta seção mostra como usar a biblioteca de rastreamento de frotas do JavaScript para conferir uma frota. Esses procedimentos presumem que você tenha configurado a biblioteca de rastreamento de frota e carregado um mapa. Para mais detalhes, consulte Configurar a biblioteca de rastreamento de frotas do JavaScript.

Neste documento, abordamos as seguintes ações que você pode realizar ao visualizar uma frota:

1. Comece a rastrear a frota.
2. Detectar eventos e processar erros.
3. Interromper o monitoramento.
4. Acompanhar um único veículo enquanto visualiza uma frota.

Começar a rastrear a frota

Para rastrear uma frota, é necessário instanciar um provedor de localização de frota e definir restrições de localização para a janela de visualização do mapa, conforme descrito nas seções a seguir.

Instanciar um provedor de localização de frota

A biblioteca de rastreamento de frotas em JavaScript inclui um provedor de local que busca vários veículos da Fleet Engine.

Para instanciar, siga estas etapas:

1. Use o ID do projeto e uma referência ao seu coletor de tokens.

2. Usar uma consulta de filtro de veículo: ela controla quais veículos são mostrados no mapa. O filtro é transmitido ao Fleet Engine.

   • Para serviços sob demanda, use vehicleFilter e consulte ListVehiclesRequest.filter.
   • Para tarefas programadas, use deliveryVehicleFilter e analise ListDeliveryVehiclesRequest.filter.

3. Defina a área delimitadora para a tela do veículo. Use locationRestriction para limitar a área em que os veículos são mostrados no mapa. O provedor de local não fica ativo até que isso seja definido. É possível definir limites de local no construtor ou depois dele.

4. Inicializar a visualização do mapa.

Os exemplos a seguir mostram como instanciar um provedor de localização de frota para cenários de tarefas programadas e sob demanda. Esse exemplo também mostra como usar o locationRestriction no construtor para ativar o provedor de localização.

Viagens sob demanda

JavaScript

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

          // Optionally, specify location bounds to
          // limit which 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 vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

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

          // Optionally, specify location bounds to
          // limit which 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 vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

Tarefas agendadas

JavaScript

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

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately make the location provider active.
          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 make the location provider active.
          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"',
        });

Para definir locationRestriction após o construtor, adicione o locationProvider.locationRestriction mais tarde no código, conforme mostrado no exemplo de JavaScript abaixo.

Observação: o exemplo é para tarefas programadas, mas, para fazer isso em viagens sob demanda, basta usar google.maps.journeySharing.FleetEngineFleetLocationProvider.

   // You can choose to not set locationRestriction in the constructor.
   // In this case, the location provider *DOES NOT START* after this line, because
   // no locationRestriction is set.
   locationProvider = new google.maps.journeySharing.DeliveryFleetLocationProvider({
   ... // not setting locationRestriction here
   });

   // You can then set the locationRestriction *after* the constructor.
   // After this line, the location provider is active.
   locationProvider.locationRestriction = {
     north: 1,
     east: 2,
     south: 0,
     west: 1,
   };

Definir a restrição de local usando a janela de visualização do mapa

Também é possível definir os limites locationRestriction para corresponder à área atualmente visível na visualização do mapa.

Viagens sob demanda

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

Tarefas agendadas

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 provider 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 provider will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

Inicializar a visualização de mapa

Depois de criar o provedor de local, inicialize a visualização do mapa da mesma forma que você faz ao seguir um único veículo.

Depois de carregar a biblioteca JavaScript Journey Sharing, inicialize a visualização do mapa e a adicione à página HTML. Sua página precisa conter um elemento <div> que contenha a visualização do mapa. O elemento <div> é chamado de map_canvas nos exemplos a seguir.

Viagens sob demanda

JavaScript

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

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-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 want.
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],
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.VehicleId
                        = 'your-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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

Tarefas agendadas

JavaScript

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

// 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 want.
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],
});

// 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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

Detectar eventos e processar erros

Depois de começar a seguir a frota, é necessário detectar mudanças de evento e processar todos os erros que surgirem, conforme descrito nas seções a seguir.

Detectar eventos de mudança

É possível extrair metadados sobre a frota do objeto do veículo usando o provedor de local. As mudanças nas metainformações acionam um evento de atualização. As metainformações incluem propriedades do veículo, como estado de navegação, distância restante e atributos personalizados.

Para mais detalhes, consulte:

• Referência das opções de veículos para viagens sob demanda
• Referência das opções de veículo para tarefas programadas

Os exemplos a seguir mostram como detectar esses eventos de mudança.

Viagens sob demanda

JavaScript

locationProvider.addListener('update', e => {
  // e.vehicles contains data that may be
  // useful to the rest of the UI.
  for (vehicle of e.vehicles) {
    console.log(vehicle.navigationStatus);
  }
});

TypeScript

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

Tarefas agendadas

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

Detectar erros

Você também quer detectar e processar erros que ocorrem ao seguir um veículo. Erros que surgem de forma assíncrona ao solicitar informações do veículo acionam eventos de erro.

O exemplo abaixo mostra como detectar esses eventos para processar erros.

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

Parar de monitorar a frota

Para interromper o rastreamento da frota, defina os limites do provedor de local como nulos e remova-o da visualização do mapa, conforme descrito nas próximas seções.

Definir os limites do provedor de local como nulos

Para impedir que o provedor de local rastreie a frota, defina os limites do provedor de local como nulos.

Viagens sob demanda

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

Tarefas agendadas

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

Remover o provedor de local da visualização do mapa

O exemplo a seguir mostra como remover um provedor de local da visualização do mapa.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Rastrear um veículo de entrega enquanto visualiza uma frota de entrega

Se você estiver usando os serviços de mobilidade para tarefas programadas, poderá visualizar uma frota e mostrar a rota e as próximas tarefas de um veículo de entrega específico na mesma visualização do mapa. Para fazer isso, instancie um provedor de localização da frota de entrega e um provedor de localização do veículo de entrega e adicione ambos à visualização do mapa. Depois de instanciado, o provedor de localização da frota de entrega começa a mostrar veículos de entrega no mapa. Os exemplos a seguir mostram como instanciar os dois provedores de local:

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

Usar a personalização de marcadores para rastrear um veículo de entrega

Para permitir que o provedor de localização do veículo de entrega acompanhe um veículo de entrega quando você clicar no marcador da frota, siga estas etapas:

1. Personalize um marcador e adicione uma ação de clique.

2. Ocultar o marcador para evitar marcadores duplicados.

   Observação: o provedor de localização da frota de entrega renderiza um conjunto de marcadores, um para cada veículo rastreado. Se você quiser mostrar detalhes de um veículo quando o usuário clicar nele, instancie um provedor de local do veículo de entrega e defina o ID do veículo como o que o usuário clicou, conforme mostrado no exemplo a seguir. No entanto, ao fazer isso, o provedor de local do veículo de entrega também renderiza um marcador para esse veículo, como foi projetado. Assim, você oculta um deles para que não haja dois marcadores para o mesmo veículo.

Confira exemplos dessas etapas nas seções a seguir.

Personalizar um marcador e adicionar uma ação de clique

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

Ocultar o marcador para evitar marcadores duplicados

O marcador do provedor de local do veículo de entrega é ocultado para evitar a renderização de dois marcadores para o mesmo veí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);
    }
  };

A seguir

• Aplicar um estilo a um mapa