Navegar por rotas de veículos grandes

Para quem é este guia:leia este guia se você for um desenvolvedor para dispositivos móveis responsável por criar a experiência de navegação guiada para motoristas de caminhões, ônibus ou outros veículos comerciais grandes.

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

O que você vai aprender

Você vai aprender a fazer o seguinte:

• Use um routeToken para conectar o planejamento de rotas de back-end com a experiência de navegação no app.
• Configure o SDK Navigation para usar um trajeto de caminhão pré-planejado.
• 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 ao projeto

O roteamento de veículos grandes está disponível para um conjunto limitado de clientes. Para expressar interesse e solicitar acesso ao seu projeto do Google Cloud, preencha o formulário de contato. Um representante do Google vai entrar em contato com as próximas etapas.

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

Se a sua organização usa projetos separados do Google Cloud para as APIs de roteamento de back-end e o SDK Navigation 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 um trajeto de caminhão e receber um routeToken usando uma das seguintes APIs:

• API Routes: recomendada para calcular rotas únicas de caminhão entre origens e destinos. Para instruções de configuração, consulte Gerar rotas e ETAs de veículos grandes.
• API Route Optimization: recomendada para otimizar rotas com várias paradas em uma frota. Para mais informações, consulte o guia de roteamento de veículos grandes da API Route Optimization.

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

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

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

Limitações e diretrizes operacionais

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

• Disponibilidade geográfica: o roteamento 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, Havaí ou territórios dos EUA.
• Orientação e segurança para motoristas: os motoristas não podem confiar apenas nas rotas retornadas pelo SDK Navigation para garantir segurança ou conformidade com a lei. As rotas podem não ser adequadas para o veículo em todas as condições de via, e segui-las pode expor os motoristas a perigos, como vias com restrição de altura ou peso. Os motoristas precisam sempre ficar alertas e obedecer às placas de trânsito e às regulamentações locais.
• Trajetos de melhor esforço: quando a API de roteamento não consegue encontrar um trajeto que atenda totalmente às restrições do veículo, ela retorna um trajeto de "melhor esforço" que ainda pode passar por trechos restritos. Por exemplo, a API Routes define a flag routeRestrictionsPartiallyIgnored na resposta. Ao navegar por essas rotas, o SDK Navigation exibe indicadores de rota para destacar as restrições relevantes. Planeje rotas com cuidado nesses casos e não use uma rota sinalizada como única fonte de verdade para planejamento ou navegação.
• Recursos não compatíveis: o roteamento para veículos grandes não é compatível com os seguintes recursos:
  • Preços de pedágios para caminhões
  • Limites de velocidade específicos para caminhões ou veículos pesados
  • Roteamento para materiais perigosos radioativos
• Limites de uso: as solicitações feitas ao SDK Navigation seguem os limites de uso e de cota padrão. Para mais informações, consulte Uso e faturamento.

Mostrar a interface específica para caminhões (indicações de rota)

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

O SDK Navigation inclui alertas para as seguintes restrições:

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

Como os tokens de rota funcionam

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

O fluxo de trabalho segue estas etapas:

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

Recálculos e redirecionamentos dinâmicos

Durante a navegação ativa, as condições de trânsito, as interdições ou as conversões perdidas podem fazer com que o veículo se desvie da rota planejada.

Quando o redirecionamento ocorre:

• O SDK Navigation recalcula automaticamente o trajeto até o destino.
• O SDK retém os atributos e as dimensões do veículo codificados no routeToken original.
• O trajeto recalculado evita vias com altura livre baixa, pontes com restrição de peso e 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: extrair o token de rota do seu back-end

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

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

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

Etapa 2: transmitir o token ao navegador

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

Ao configurar pontos de parada e transmitir o token de rota, lembre-se das seguintes considerações:

• 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.
• Trajetos ao lado da via: veículos comerciais grandes não conseguem fazer retornos em U com facilidade em ruas estreitas. Para garantir que o caminhão se aproxime do destino pelo lado correto da via, defina preferSameSideOfRoad = true nos seus pontos de parada.
• Paradas do veículo: para guiar o caminhão até um local adequado para parada ou descarga, defina vehicleStopover = true nos waypoints.
• Pontos de navegação: se o destino tiver uma entrada de carga ou um cais de carga designado, especifique-o usando um token de ponto de navegação.

Etapa 3: processar o status da rota e iniciar a orientaçã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 rota para o SDK Navigation usando o método mapView.navigator setDestinations, especificando os mesmos pontos de parada de destino que você usou ao criar o token de rota:

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

Próximas etapas

• Modificar a interface de navegação: personalize controles e elementos visuais integrados da interface, 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 da rota, mudanças na ETA e novos trajetos.