Para quem é este guia:leia este guia se você for um desenvolvedor de 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: este guia explica como usar uma rota específica para caminhões gerada pela API Routes ou pela API Route Optimization para ativar uma sessão de navegação guiada com o SDK do Navigation para iOS.
O que você vai aprender
Você vai aprender a fazer as seguintes tarefas:
- Usar um
routeTokenpara conectar o planejamento de rotas de back-end com a experiência de navegação no app. - Configurar o SDK do Navigation para usar um trajeto de caminhão pré-planejado.
- Entender como as restrições específicas para caminhões aparecem para o motorista na interface de navegação.
Pré-requisitos
Antes de começar, confira se você atende aos seguintes requisitos:
1. Solicitar acesso ao seu projeto
O roteamento de veículos grandes está disponível para um grupo 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 com as próximas etapas.
Depois que o Google conceder acesso, confira se o projeto na nuvem do Google Cloud está provisionado para 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 do 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 trajetos de caminhão únicos entre origens e destinos. Para instruções de configuração, consulte Gerar trajetos e ETAs de veículos grandes.
- API Route Optimization: recomendada para otimizar trajetos 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 de materiais perigosos). A API de roteamento 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
O 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, o projeto precisa atender aos requisitos de configuração padrão do SDK do 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 Japão (experimental). Ele não está disponível no Alasca, no Havaí ou nos territórios dos EUA.
- Avisos e segurança do motorista: os motoristas não podem confiar apenas nos trajetos retornados pelo SDK do Navigation para serem seguros ou legais. Os trajetos podem não ser adequados para o veículo em todas as condições de estrada, e segui-los pode expor os motoristas a perigos, como vias com altura ou peso restritos. 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 esteja totalmente
em conformidade com as restrições do veículo, ela retorna um trajeto de "melhor esforço" que
ainda pode passar por segmentos restritos. Por exemplo, a API Routes define o flag
routeRestrictionsPartiallyIgnoredna resposta. Ao navegar por esses trajetos, o SDK do Navigation mostra frases de destaque para destacar as restrições relevantes. Planeje os trajetos com cuidado nesses casos e não use um trajeto sinalizado como uma única fonte de verdade para planejamento ou navegação. - Recursos não compatíveis: o roteamento de veículos grandes não oferece suporte aos
seguintes recursos:
- Preços de pedágio para caminhões
- Limites de velocidade específicos para caminhões ou veículos pesados
- Roteamento de materiais perigosos radioativos
- Limites de uso: as solicitações feitas ao SDK do 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 (frases de destaque do trajeto)
O SDK do Navigation mostra automaticamente avisos visuais, chamados de frases de destaque do trajeto, no mapa para alertar os motoristas sobre as restrições de 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 do Navigation inclui frases de destaque para as seguintes restrições:
| Restrição | Ícone e texto da frase de destaque | Condições de exibição |
|---|---|---|
| Altura |
Amarelo = aviso, seu veículo está próximo da altura máxima permitida 
Vermelho = seu veículo está acima da altura máxima permitida |
Uma frase de destaque amarela aparece quando a altura do veículo está próxima da restrição.
Uma frase de destaque vermelha aparece se o trajeto não estiver em conformidade e violar uma restrição de altura. 
|
| Peso |
|
Uma frase de destaque vermelha 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 segmento de via
com uma restrição de caminhão comercial.
|
| Mercadorias perigosas |
|
Uma frase de destaque vermelha aparece quando a carga de materiais perigosos do veículo é proibida em um segmento de 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 do trajeto planejado, bem como as dimensões físicas e o perfil de restrição do veículo.
O fluxo de trabalho segue estas etapas:
- Solicitar trajeto: o servidor de back-end solicita um trajeto de caminhão da API Routes (ou da API Route Optimization).
- Receber token: a API de roteamento calcula o trajeto em conformidade e
retorna um
routeTokenpara o servidor de back-end. - Encaminhar token: o servidor de back-end transmite o
routeTokene as coordenadas de destino para o app para dispositivos móveis. - Transmitir ao SDK: o app para dispositivos móveis transmite o
routeTokenao SDK do Navigation. - Iniciar orientação: o SDK do Navigation processa todos os aspectos da navegação guiada, incluindo a renderização de frases de destaque do trajeto e o processamento de redirecionamento dinâmico 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, os fechamentos de vias ou as curvas perdidas podem fazer com que o veículo se desvie do trajeto planejado.
Quando o redirecionamento ocorre:
- O SDK do Navigation recalcula automaticamente o trajeto até o destino.
- O SDK retém os atributos e dimensões do veículo codificados no
routeTokenoriginal. - O trajeto recém-recalculado evita vias com altura ou peso restritos 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: receber o token de rota do back-end
O 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 servidor, consulte Gerar trajetos e ETAs 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 o routeToken e os waypoints de destino para o método mapView.navigator
setDestinations.
Ao configurar waypoints e transmitir o token de rota, considere o seguinte:
- Requisito de correspondência de destino: as coordenadas de destino transmitidas para
setDestinationsprecisam corresponder às coordenadas de destino usadas ao gerar orouteToken. Especificar um destino diferente causa um erro. - Roteamento lateral da via: veículos comerciais grandes não podem fazer
retornos em ruas estreitas. Para garantir que o caminhão se aproxime do destino no lado correto da via, defina
preferSameSideOfRoad = truenos waypoints. - Paradas de veículos: para orientar o caminhão até um local adequado para
parar ou descarregar, defina
vehicleStopover = truenos waypoints. - Pontos de navegação: se o destino tiver uma entrada de frete ou um cais de carga designado, especifique-o usando um token de ponto de navegação.
Etapa 3: processar o status do trajeto 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 do Navigation usando o método mapView.navigator
setDestinations, especificando os mesmos waypoints 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: {...})
Monitores veiculares
Você pode mostrar a sessão de navegação de 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 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 do trajeto, mudanças de ETA e redirecionamentos.