Monitore seus dispositivos com a biblioteca de rastreamento de frota de JavaScript

A biblioteca JavaScript Fleet Tracking permite visualizar a localização de veículos nas frotas quase em tempo real. A biblioteca usa a API Deliveries para permitir a visualização de tarefas e veículos de entrega. Assim como a biblioteca JavaScript Shipment Tracking, ela contém um componente de mapa JavaScript que é uma substituição simples para uma entidade google.maps.Map padrão e componentes de dados para se conectar ao Fleet Engine.

Componentes

A biblioteca JavaScript Fleet Tracking oferece componentes para a visualização de veículos de entrega e paradas, além de feeds de dados brutos para HEC ou distância restante até uma entrega.

Visualização em mapa do rastreamento de frota

O componente de visualização de mapa "Rastreamento de frota" mostra a localização de veículos e tarefas. Se o trajeto para um veículo for conhecido, o componente de visualização de mapa vai animar o veículo à medida que ele se move ao longo do caminho previsto.

Exemplo de visualização de mapa de rastreamento de frotas

Provedores de localização

Os provedores de localização trabalham com informações armazenadas no Fleet Engine para enviar informações de localização de objetos rastreados ao mapa de compartilhamento de jornada.

Provedor de localização de veículo de entrega

O provedor de localização do veículo de entrega mostra as informações de localização de um único veículo de entrega. Ele contém informações sobre a localização do veículo, bem como as tarefas que foram concluídas pelo veículo de entrega.

Provedor de localização de frota de entregas

O provedor de localização da frota de entregas mostra informações de localização de vários veículos. É possível filtrar por veículos ou locais específicos ou mostrar toda a frota.

Controlar a visibilidade dos locais rastreados

Nesta seção, descrevemos as regras de visibilidade para objetos de localização rastreados no mapa para o provedor de localização predefinido do Fleet Engine. Os provedores de local personalizados ou derivados podem alterar as regras de visibilidade.

Veículos de entrega

Um veículo de entrega fica visível assim que é criado no Fleet Engine e aparece durante todo o trajeto, independentemente das tarefas.

Marcadores de local da tarefa

As paradas planejadas do veículo são mostradas no mapa como marcadores de parada do veículo. Os marcadores de tarefas concluídas são mostrados com um estilo diferente das paradas planejadas de um veículo.

O local dos resultados da tarefa é exibido com marcadores de resultado da tarefa. As tarefas com um resultado SUCCEEDED são mostradas com marcadores de tarefas bem-sucedidas, enquanto todas as outras tarefas são mostradas com marcadores de tarefas com falha.

Introdução à biblioteca JavaScript Fleet Tracking

Antes de usar a biblioteca JavaScript Fleet Tracking, conheça o Fleet Engine e saiba como acessar uma chave de API. Em seguida, crie um ID de tarefa e uma reivindicação de ID do veículo de entrega.

Criar um ID de tarefa e uma reivindicação de ID do veículo de entrega

Para rastrear veículos de entrega usando o provedor de localização do veículo de entrega, crie um JSON Web Token (JWT) com um ID da tarefa e uma declaração de ID do veículo de entrega.

Para criar o payload do JWT, inclua uma declaração adicional na seção de autorização com as chaves taskid e deliveryvehicleid e defina o valor de cada chave como *. O token deve ser criado usando o papel do Cloud IAM Superusuário de serviço do Fleet Engine. Observe que isso concede amplo acesso para criar, ler e modificar entidades do Fleet Engine e só deve ser compartilhado com usuários confiáveis.

O exemplo a seguir mostra como criar um token para rastreamento por veículo e tarefa:

{
  "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": "*",
   }
}

Criar um coletor de tokens de autenticação

Crie um coletor de tokens de autenticação para recuperar um token gerado com as declarações apropriadas nos servidores usando um certificado de conta de serviço para o projeto. É importante produzir tokens apenas nos servidores e nunca compartilhar certificados com clientes. Caso contrário, a segurança do sistema será comprometida.

O coletor precisa retornar uma estrutura de dados com dois campos, encapsulados em uma promessa:

  • Uma string token.
  • Um número expiresInSeconds. Um token expira nesse período após a busca.

A biblioteca JavaScript Fleet Tracking envia um token usando o coletor de tokens de autenticação quando uma das seguintes condições é verdadeira:

  • Ela não tem um token válido, como quando não chamou o coletor em um novo carregamento de página ou quando não retornou com um token.
  • O token buscado anteriormente expirou.
  • O token buscado anteriormente está dentro de um minuto para expirar.

Caso contrário, a biblioteca usa o token emitido anteriormente, ainda válido, e não chama o coletor.

O exemplo a seguir mostra como criar um coletor de tokens de autenticação:

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

Ao implementar o endpoint do lado do servidor para criar os tokens, lembre-se do seguinte:

  • O endpoint precisa retornar um prazo de validade para o token. No exemplo acima, ele é fornecido como data.ExpiresInSeconds.
  • O coletor de tokens de autenticação precisa transmitir o tempo de validade (em segundos, a partir do momento da busca) à biblioteca, conforme mostrado no exemplo.
  • O SERVER_TOKEN_URL depende da implementação do back-end. Estes são os URLs para o back-end do app de exemplo:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

Carregar um mapa de HTML

O exemplo a seguir mostra como carregar a biblioteca JavaScript Journey Share de um URL especificado. O parâmetro callback executa a função initMap após o carregamento da API. O atributo defer permite que o navegador continue renderizando o restante da página enquanto a API é carregada.

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

Seguir um veículo de entrega

Nesta seção, mostramos como usar a biblioteca JavaScript Fleet Tracking Library para acompanhar um veículo de entrega. Carregue a biblioteca usando a função de callback especificada na tag do script antes de executar o código.

Instanciar um provedor de localização de veículos de entrega

A biblioteca JavaScript Fleet Tracking define um provedor de localização para a API Fleet Engine Deliveries. Para instanciá-lo, use o ID do projeto e uma referência à fábrica do token.

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

Inicializar a visualização de mapa

Depois de carregar essa biblioteca, inicialize a visualização de mapa e adicione à página HTML. Sua página deve conter um elemento <div> que contenha a visualização de mapa. No exemplo abaixo, o elemento <div> é chamado de 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);

Ouvir eventos de alteração

É possível recuperar metainformações sobre uma tarefa do objeto deliveryVehicle usando o provedor de localização. Essas informações incluem o HEC e a distância restante antes do próximo embarque ou desembarque do veículo. As mudanças nas metainformações acionam um evento update. O exemplo abaixo mostra como detectar esses eventos de mudança.

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

Detectar erros

Os erros que surgem de forma assíncrona ao solicitar informações do veículo de entrega acionam eventos. O exemplo a seguir 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 monitoramento

Para impedir que o provedor do local rastreie o veículo de entrega, remova o ID dele.

JavaScript

locationProvider.deliveryVehicleId = '';

TypeScript

locationProvider.deliveryVehicleId = '';

Remover o provedor de localização da visualização de mapa

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Conferir uma frota de entregas

Nesta seção, mostramos como usar a biblioteca JavaScript Journey Share para visualizar uma frota de entregas. Carregue a biblioteca usando a função de callback especificada na tag do script antes de executar o código.

Instanciar um provedor de localização de frota de entregas

A biblioteca JavaScript Fleet Tracking define um provedor de localização que busca vários veículos da API FleetEngine Deliveries. Para instanciá-lo, use o ID do projeto e uma referência ao coletor de tokens.

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 uma consulta usada para filtrar veículos mostrados no mapa. Esse filtro é transmitido diretamente para o Fleet Engine. Consulte ListDeliveryVehiclesRequest.filter para conferir os formatos compatíveis.

locationRestriction limita a área em que os veículos são mostrados no mapa. Ela também controla se o monitoramento de localização está ativo ou não. O monitoramento de localização não será iniciado até que essa opção seja definida.

Após construir o provedor de localização, inicialize a visualização de mapa.

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

Os limites locationRestriction podem ser configurados para corresponder à área atualmente visível na visualização 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;
    }
  });

Ouvir eventos de alteração

É possível extrair metainformações sobre a frota do objeto deliveryVehicles usando o provedor de localização. As metainformações incluem propriedades do veículo, como estado de navegação, distância restante e atributos personalizados. Consulte a documentação de referência para saber mais. A mudança nas metainformações aciona um evento update. O exemplo abaixo mostra como detectar esses eventos de mudança.

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

Os erros que surgem de forma assíncrona ao solicitar informações da frota de entrega acionam eventos de erro. Para ver exemplos de como detectar esses eventos, consulte Detectar erros.

Parar monitoramento

Para impedir que o provedor de localização rastreie a frota de entregas, defina os limites desse provedor como nulo.

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

Remover o provedor de localização da visualização de mapa

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Rastreie um veículo de entrega e confira uma frota de entregas

Ao visualizar uma frota, você pode mostrar o trajeto e as próximas tarefas de um veículo de entrega específico. Para fazer isso, instancie um provedor de localização de frota de entregas e um provedor de localização de veículo de entrega e adicione ambos à visualização 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
});

O provedor de localização da frota de entregas começa a mostrar veículos de entrega no mapa. Use a personalização de marcadores para permitir que o provedor de localização do veículo de entrega rastreie um veículo de entrega quando o marcador da frota receber um 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();
      });
    }
  };

Oculte o marcador do provedor de localização do veículo de entrega 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);
    }
  };

Personalizar a aparência do mapa básico

Para personalizar a aparência do componente Maps, estilize seu mapa usando ferramentas baseadas na nuvem ou definindo opções diretamente no código.

Usar a Estilização de mapas baseada na nuvem

Com a Estilização de mapas baseada na nuvem, você pode criar e editar estilos para qualquer um dos seus apps que usam o Google Maps no console do Google Cloud sem precisar alterar o código. Os estilos de mapa são salvos como IDs de mapa no seu projeto do Cloud. Para aplicar um estilo ao mapa de rastreamento de frota do JavaScript, especifique um mapId ao criar a JourneySharingMapView. Não é possível adicionar ou mudar o campo mapId depois que o JourneySharingMapView for instanciado. O exemplo a seguir mostra como ativar um estilo de mapa criado anteriormente com um ID.

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

Usar a Estilização de mapas baseada em código

Outra maneira de personalizar a estilização do mapa é definir mapOptions ao criar o 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" }
        ]
      }
    ]
  }
});

Mudar o estilo e a visibilidade dos trajetos

Para configurar o estilo e a visibilidade de rotas percorridas e previstas, use as opções de estilo personalizado. Para mais informações, consulte a interface PolylineOptions.

O exemplo a seguir mostra como configurar o estilo e a visibilidade de rotas previstas. Para configurar o estilo e a visibilidade das rotas percorridas, use takenRoutePolylineSetup em vez 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 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 static PolylineOptions to
// use for the anticipated route.
const anticipatedRoutePolylineSetup = {
  polylineOptions: {
    strokeOpacity: 0.5,
    strokeColor: 'red',
    …
  },
  visible: true,
};

Usar as personalizações dos marcadores

Com a biblioteca JavaScript Fleet Tracking, você pode personalizar a aparência dos marcadores adicionados ao mapa. Para fazer isso, especifique personalizações de marcador, que serão aplicadas pela biblioteca Fleet Tracking antes de adicionar marcadores ao mapa e sempre que eles forem atualizados.

A personalização mais simples é especificar um objeto MarkerOptions que será aplicado a todos os marcadores do mesmo tipo. As alterações especificadas no objeto são aplicadas depois da criação de cada marcador, substituindo todas as opções padrão.

Uma opção mais avançada é especificar uma função de personalização. As funções de personalização permitem estilizar os marcadores com base nos dados, além de adicionar interatividade a eles, como o processamento de cliques. Especificamente, o rastreamento de frota transmite dados para a função de personalização sobre o tipo de objeto que o marcador representa: veículo, parada ou tarefa. Isso permite que o estilo do marcador mude com base no estado atual do próprio elemento, por exemplo, no número de paradas restantes ou no tipo de tarefa. É possível até mesmo mesclar dados de fontes fora do Fleet Engine e estilizar o marcador com base nessas informações.

Além disso, é possível usar funções de personalização para filtrar a visibilidade do marcador. Para fazer isso, chame setVisible(false) no marcador.

No entanto, por motivos de desempenho, recomendamos usar a filtragem nativa no provedor de localização, como FleetEngineDeliveryFleetLocationProvider.deliveryVehicleFilter. Sendo assim, quando você precisar de mais funcionalidades de filtragem, aplique a filtragem usando a função de personalização.

A biblioteca Fleet Tracking oferece os seguintes parâmetros de personalização:

Mudar o estilo dos marcadores usando MarkerOptions

O exemplo a seguir mostra como configurar o estilo de um marcador de veículo com um objeto MarkerOptions. Siga esse padrão para personalizar o estilo de qualquer marcador usando qualquer um dos parâmetros de personalização listados acima.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Alterar o estilo dos marcadores usando funções de personalização

O exemplo a seguir mostra como configurar o estilo de um marcador de veículo. Siga esse padrão para personalizar o estilo de qualquer marcador usando qualquer um dos parâmetros listados acima.

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

Adicionar processamento de cliques aos marcadores

O exemplo a seguir mostra como adicionar o gerenciamento de cliques a um marcador de veículo. Siga esse padrão para adicionar processamento de cliques a qualquer marcador usando um dos parâmetros de personalização listados acima.

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 visíveis

O exemplo a seguir mostra como filtrar quais marcadores de veículo ficam visíveis. Siga esse padrão para filtrar os marcadores usando qualquer um dos parâmetros de personalização listados acima.

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

Mostrar um InfoWindow para um marcador de veículo ou local

Você pode usar um InfoWindow para exibir mais informações sobre um veículo ou marcador de local.

O exemplo a seguir mostra como criar um InfoWindow e anexá-lo a um marcador de veí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();

Desativar o ajuste automático

Desative o ajuste automático para impedir que o mapa se ajuste automaticamente à janela de visualização ao veículo e ao trajeto previsto. O exemplo a seguir mostra como desativar o ajuste automático ao configurar a visualização de mapa do compartilhamento de jornada.

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

Substituir um mapa

Você pode substituir um mapa que inclua marcadores ou outras personalizações sem perder o acesso a elas.

Por exemplo, suponha que você tenha uma página da Web com uma entidade google.maps.Map padrão em que um marcador é exibido:

<!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 adicionar a biblioteca JavaScript Journey Share, que inclui Fleet Tracking:

  1. Adicione o código da fábrica de tokens de autenticação.
  2. Inicialize um provedor de localização na função initMap().
  3. Inicialize a visualização de mapa na função initMap(). A visualização contém o mapa.
  4. Mova a personalização para a função de callback para a inicialização da visualização de mapa.
  5. Adicione a biblioteca de localização ao carregador da API.

O exemplo a seguir mostra as mudanças a serem feitas:

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

Se você opera um veículo de entrega com o ID especificado perto de Uluru, ele vai ser renderizado no mapa.