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

O trajeto para veículos grandes está disponível 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 do Google Cloud 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:

• API Routes: recomendada para calcular rotas de caminhão únicas entre origens e destinos. Para instruções de configuração, consulte Gerar rotas e ETAs para 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 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

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í ou em 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 vias 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 de roteamento não consegue encontrar uma rota que obedeça totalmente às restrições do veículo, ela retorna uma rota de "melhor esforço" que ainda pode atravessar segmentos restritos. Por exemplo, a API Routes define a flag routeRestrictionsPartiallyIgnored na resposta. Ao percorrer 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 de 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 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	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 aviso amarelo aparece quando a altura do veículo está próxima da restrição. Um aviso vermelho vai aparecer se o trajeto não estiver em conformidade e violar uma restrição de altura.
Peso		Um balão 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 frase de destaque vermelha aparece quando a carga de materiais perigosos do veículo é proibida em um trecho da via.

Como funcionam os tokens de trajeto

Um routeToken é um snapshot criptografado de um trajeto criado pelo back-end de rotas 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: seu 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 o 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 um novo trajeto é traçado:

• 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 evita pontes com limite de altura ou 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: 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 mais informações sobre como gerar esse token no seu servidor, consulte Gerar rotas e ETAs 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: definir destinos com o token de trajeto

Transmita o routeToken para o método mapView.navigator setDestinationsWithToken:completionHandler:. O SDK do Navigation recebe os destinos do token de trajeto, além do perfil de trajeto TRUCK que o direciona para aplicar restrições de veículos grandes. Não é necessário transmitir waypoints. O modo de viagem do app precisa ser .driving (GMSNavigationTravelModeDriving), que é o padrão, ou .twoWheeler (GMSNavigationTravelModeTwoWheeler).

Defina as opções de waypoint na solicitação de API da API Routes que cria o token de rota. O SDK do Navigation as recebe do token, junto com seus destinos. Para veículos grandes, considere as seguintes opções:

• Rotas na lateral da via: veículos comerciais grandes não conseguem fazer retornos com facilidade em ruas estreitas. Para garantir que o caminhão se aproxime do destino pelo lado correto da via, defina sideOfRoad como true no waypoint de destino.
• Paradas de veículos: para guiar o caminhão até um local apropriado para parar ou descarregar, defina vehicleStopover como true no waypoint de destino.
• 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

Quando o SDK de navegação termina de calcular o trajeto, ele transmite um GMSNavigationRouteDescription para o gerenciador de conclusão. Quando o routeStatus é .OK (GMSRouteStatusOK), defina isGuidanceActive = true (guidanceActive = YES) para iniciar a navegação guiada ativa.

Para confirmar se o SDK de navegação aplicou o token de trajeto, consulte Verificar se o SDK de navegação aplicou o token de trajeto.

Exemplo de código

Transmita o token de trajeto para setDestinationsWithToken:completionHandler: e, em seguida, inicie a navegação quando o status do trajeto for .OK.

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

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  if routeDescription?.routeStatus == .OK {
    self?.mapView.navigator?.isGuidanceActive = true
  }
}

Telas no veículo

Próximas etapas

• Modificar a interface de navegação: personalize os controles de interface integrados e os elementos visuais, como a bússola, o botão de centralizaçã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.