Navegar por rotas de veículos grandes

Público-alvo:este guia é destinado a desenvolvedores de dispositivos móveis responsáveis por criar a experiência de navegação guiada para motoristas de caminhões, ônibus ou outros veículos comerciais de grande porte.

O que este guia aborda:como usar um trajeto específico para caminhões gerado pela API Routes ou pela API Route Optimization para uma sessão de navegação guiada com o SDK Navigation para iOS.

O que você vai aprender

Você vai aprender a realizar as seguintes tarefas:

  • Use um routeToken para conectar o planejamento de rotas de back-end à experiência de navegação no app.
  • Configure o SDK de navegação para usar uma rota de caminhão pré-planejada.
  • Entenda como as restrições específicas para caminhões aparecem para o motorista na interface de navegação.

Pré-requisitos

Antes de começar, verifique se você atende aos seguintes requisitos:

1. Solicitar acesso para seu projeto

As rotas para veículos grandes estão disponíveis para um conjunto limitado de clientes. Para manifestar interesse e solicitar acesso ao seu projeto na nuvem do Google Cloud, preencha o formulário de contato. Um representante do Google vai entrar em contato para informar as próximas etapas.

Depois que o Google conceder acesso, verifique se o projeto na nuvem do Google está provisionado para o roteamento de veículos grandes.

Se a organização usa projetos separados do Google Cloud para as APIs de roteamento de back-end e o SDK de navegação para dispositivos móveis, entre em contato com o Google para provisionar cada projeto.

2. Configurar a geração de rotas de back-end e receber um token de rota

Antes de iniciar a navegação no dispositivo, o servidor de back-end precisa gerar uma rota de caminhão e receber um routeToken usando uma das seguintes APIs:

A solicitação de back-end precisa especificar travelMode: TRUCK com os atributos físicos do veículo (altura, largura, comprimento, peso, número de eixos e carga de materiais perigosos). A API Routes retorna um routeToken na resposta, que o servidor de back-end transmite ao app para dispositivos móveis.

3. Atender aos requisitos mínimos do SDK e do sistema

Seu app precisa usar a versão mínima necessária do SDK do Navigation, que é a 5.4.0 ou mais recente.

Além disso, seu projeto precisa atender aos requisitos de configuração padrão do SDK de navegação.

Limitações e diretrizes operacionais

Antes de começar, observe as seguintes limitações e diretrizes operacionais:

  • Disponibilidade geográfica: o trajeto de veículos grandes está disponível nos 48 estados contíguos dos Estados Unidos (disponibilidade geral) e no Japão (experimental). Ele não está disponível no Alasca, no Havaí nem nos territórios dos EUA.
  • Aviso e segurança do motorista: os motoristas não devem confiar apenas nas rotas retornadas pelo SDK do Navigation para garantir a segurança ou a legalidade. As rotas podem não ser adequadas para o veículo em todas as condições de estrada, e segui-las pode expor os motoristas a perigos, como baixa altura livre ou estradas com restrição de peso. Os motoristas precisam sempre ficar atentos e obedecer às placas de trânsito e às regulamentações locais.
  • Rotas de melhor esforço: quando a API Routes não consegue encontrar um trajeto que obedeça totalmente às restrições do veículo, ela retorna uma rota de "melhor esforço" que ainda pode passar por segmentos restritos. Por exemplo, a API Routes define a flag routeRestrictionsPartiallyIgnored na resposta. Ao navegar por essas rotas, o SDK do Navigation mostra balões de texto para destacar as restrições relevantes. Planeje os trajetos com cuidado nesses casos e não use um trajeto sinalizado como única fonte de verdade para planejamento ou navegação.
  • Recursos não compatíveis: o trajeto de veículos grandes não é compatível com os seguintes recursos:
    • Preços de pedágio para caminhões
    • Limites de velocidade específicos para caminhões ou veículos pesados
    • Rotas para materiais radioativos perigosos
  • Limites de uso: as solicitações feitas ao SDK do Navigation seguem os limites padrão de uso e cota. Para mais informações, consulte Uso e faturamento.

Mostrar interface específica para caminhões (balões de rota)

O SDK do Navigation mostra automaticamente avisos visuais, chamados de legendas de trajeto, no mapa para alertar os motoristas sobre as próximas restrições para caminhões. As frases de destaque aparecem para restrições que ocorrem ao longo do trajeto planejado, mas não são mostradas em outras vias próximas.

O SDK de navegação inclui avisos para as seguintes restrições:

Restrição Ícone e texto da frase de destaque Condições para exibição
Height Um ícone amarelo de restrição de altura
Amarelo = aviso, seu veículo está perto da altura máxima permitida
Um ícone vermelho de restrição de altura
Vermelho = seu veículo está acima da altura máxima permitida 		Um aviso amarelo aparece quando a altura do veículo está próxima da restrição.
Mapa mostrando um aviso de restrição de altura
Uma frase de destaque vermelha vai aparecer se o trajeto não estiver em conformidade e violar uma restrição de altura.
Mapa mostrando uma violação de restrição de altura
Peso Ícone de restrição de peso Uma frase de destaque vermelha aparece quando o peso do veículo excede o limite da via.
Um mapa mostrando um ícone de restrição de peso
Caminhões proibidos Ícone de caminhões proibidos Uma frase de destaque vermelha aparece ao viajar em um trecho de via com restrição para caminhões comerciais.
Um mapa mostrando um ícone de proibido caminhões
Mercadorias perigosas Ícone de produtos perigosos Uma frase de destaque vermelha aparece quando a carga de materiais perigosos do veículo é proibida em um trecho da via.
Um mapa mostrando um ícone de produtos perigosos

Como funcionam os tokens de trajeto

Um routeToken é um snapshot criptografado de um trajeto criado pelo back-end de roteamento do Google. Ela encapsula a geometria da rota planejada, bem como as dimensões físicas e o perfil restrito do veículo.

O fluxo de trabalho segue estas etapas:

  1. Solicitar rota: o servidor de back-end solicita uma rota de caminhão da API Routes (ou da API Route Optimization).
  2. Receber token: a API Routes calcula o trajeto compatível e retorna um routeToken ao servidor de back-end.
  3. Encaminhar token: o servidor de back-end transmite o routeToken e as coordenadas de destino para o app para dispositivos móveis.
  4. Transmitir para o SDK: o app para dispositivos móveis transmite o routeToken para o SDK do Navigation.
  5. Iniciar orientação: o SDK do Navigation processa todos os aspectos da experiência de navegação guiada, incluindo a renderização de textos explicativos de trajeto e o processamento de novos trajetos dinâmicos de acordo com as restrições do veículo.

Recálculos e novos trajetos dinâmicos

Durante a navegação ativa, as condições de trânsito, as vias interditadas ou as conversões perdidas podem fazer com que o veículo se desvie do trajeto planejado.

Quando o trajeto é alterado:

  • O SDK do Navigation recalcula automaticamente o trajeto até o destino.
  • O SDK mantém os atributos e as dimensões do veículo codificados no routeToken original.
  • O novo trajeto recalculado evita pontes com limite de altura e peso, além de vias proibidas para caminhões comerciais.

Implementação: iniciar uma viagem específica para caminhões

Siga estas etapas para inicializar e iniciar a navegação guiada com um token de rota de veículo grande.

Etapa 1: receber o token de trajeto do back-end

Seu app para dispositivos móveis recebe a string routeToken com as coordenadas de destino do servidor de back-end. Para saber como gerar esse token no seu servidor, consulte Gerar rotas e HECs para veículos grandes na documentação da API Routes.

O código a seguir é um exemplo de token de trajeto:

{
  "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}

Etapa 2: transmitir o token para o Navigator

Transmita os waypoints de routeToken e de destino para o método setDestinations de mapView.navigator.

Ao configurar waypoints e transmitir o token de trajeto, lembre-se do seguinte:

  • Requisito de correspondência de destino: as coordenadas de destino transmitidas para setDestinations precisam corresponder às coordenadas de destino usadas ao gerar o routeToken. Especificar um destino diferente causa um erro.
  • Rotas na lateral da via: veículos comerciais grandes não podem fazer retornos com facilidade em ruas estreitas. Para garantir que o caminhão se aproxime do destino pelo lado correto da via, defina preferSameSideOfRoad = true nos waypoints.
  • Paradas de veículos: para guiar o caminhão até um local adequado para parar ou descarregar, defina vehicleStopover = true nos waypoints.
  • Pontos de navegação: se o destino tiver uma entrada de carga ou uma doca de carregamento designada, especifique-a usando um token de ponto de navegação.

Etapa 3: processar o status do trajeto e iniciar a navegação

Avalie o GMSRouteStatus retornado no callback setDestinations. Quando o status for .OK (GMSRouteStatusOK), defina isGuidanceActive = true (guidanceActive = YES) para iniciar a navegação guiada ativa.

Exemplo de código

Transmita o token de trajeto ao SDK do Navigation usando o método mapView.navigator setDestinations, especificando os mesmos waypoints de destino que você usou ao criar o token de trajeto:

// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

Telas no veículo

Você pode mostrar a sessão de navegação para veículos grandes em telas no painel usando a Navegação para CarPlay.

Próximas etapas

  • Modificar a interface de navegação: personalize os controles de interface e os elementos visuais integrados, como a bússola, o botão de recentralização e a perspectiva da câmera.
  • Detectar eventos de navegação: processe atualizações de navegação e eventos de ciclo de vida, como progresso do trajeto, mudanças no HEC e novos trajetos.