Planejar um trajeto

Às vezes, você pode querer planejar o trajeto que seu app oferece aos usuários. Usar um token de trajeto da API Routes ou da API Route Optimization pode ajudar você a especificar duas coisas para o trajeto planejado:

• Uma polilinha para o trajeto

• Seus objetivos de rota

Por exemplo, confira alguns exemplos de objetivos de roteamento que você pode ter:

• Minimizar o tempo de entrega: uma empresa que entrega alimentos pode querer minimizar o tempo de entrega.

• Minimizar o tempo de viagem ou o consumo de combustível: uma empresa de logística pode querer melhorar a eficiência dos motoristas e reduzir os custos de combustível.

• Minimizar o tempo até o destino: uma operação de despacho de serviço pode querer minimizar o tempo que os operadores levam para chegar a uma solicitação de trabalho.

• Reduzir custos e melhorar a segurança: uma empresa de transporte por aplicativo pode querer encontrar um trajeto mais barato para os passageiros e evitar certas áreas por motivos de segurança.

Para mais informações sobre como planejar um trajeto usando um token de rota, consulte Receber um token de rota na API Routes e Polilinhas de transição e tokens de rota na API Route Optimization.

Por que usar um token de trajeto para objetivos de trajeto

Com um token de trajeto da API Routes ou da API Route Optimization, você tem mais controle sobre o trajeto fornecido:

• Planeje um trajeto com antecedência para o SDK do Navigation usar.

• Escolha o melhor trajeto para o SDK do Navigation usar. Se você solicitar tokens de rota ao gerar rotas na API Routes, vai receber um token para cada rota gerada. Em seguida, escolha o token do trajeto que você quer usar ao transmiti-lo ao SDK de navegação.

• Estimar o preço com antecedência, incluindo estimativas de HEC e distância. Embora o custo e o tempo reais possam variar, essa estimativa reduz a diferença entre o custo esperado e o real do trajeto.

• Especificar objetivos de rota mais avançados, como trajeto ecológico ou o trajeto mais curto.

Como funcionam os tokens de trajeto

Use a API Routes ou a API Route Optimization para planejar um trajeto usando objetivos de trajeto. É possível transmitir um token de trajeto retornado de uma dessas APIs para o SDK do Navigation para orientar como ele traça o trajeto do veículo.

Veja o que acontece quando você solicita e usa um token de trajeto:

1. A API Routes ou a API Route Optimization retorna um token de trajeto criptografado que inclui a polilinha e os objetivos do trajeto.

2. Você transmite o token de trajeto para o SDK do Navigation.

3. O SDK do Navigation inicia a navegação no trajeto planejado, mesmo que haja um mais rápido disponível.

4. Durante a viagem, se as condições do trânsito ou da via mudarem ou se o veículo sair do trajeto planejado, o SDK do Navigation vai calcular um novo trajeto que segue os objetivos e as opções de trajeto definidos no token de trajeto.

Esse processo maximiza a proximidade entre o trajeto real e o planejado.

Por que um trajeto planejado pode não ser seguido exatamente

A navegação começa no trajeto planejado, mas o trajeto real pode ser diferente em situações como as seguintes:

• O veículo começa longe do ponto de partida planejado.
• As condições do trânsito ou da via mudam durante a viagem.
• O veículo sai do trajeto planejado.

Essas diferenças podem afetar a distância, o HEC e outras qualidades importantes da viagem que você planejou.

Planejar um trajeto usando um token de trajeto

Para planejar um trajeto, crie um token de trajeto e transmita-o ao SDK do Navigation, conforme descrito nas etapas a seguir:

Etapa 1: criar um token de trajeto usando a API Routes ou a API Route Optimization

1. Solicite um token de trajeto com um dos seguintes métodos:

   • API Routes: computeRoutes. Para mais informações sobre como solicitar um token de trajeto na API Routes, consulte Calcular um trajeto e Receber um token de trajeto.

   • API Route Optimization: optimizeTours ou batchOptimizeTours. Para mais informações sobre como solicitar um token de rota na API Route Optimization, consulte Polilinhas de transição e tokens de rota.

2. Configure sua solicitação de API Routes para atender aos requisitos de uso de um token de rota:

   • Defina travelMode para DRIVE ou TWO_WHEELER.
   • Defina routingPreference para TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
   • Não use waypoints Via.

Etapa 2: transmitir o token de trajeto para o SDK do Navigation

1. Armazenar o token de trajeto: no SDK do Navigation, configure uma string para armazenar o token de trajeto. Exemplo:

   let routeToken = "route token returned by Routes API"
   

   Exemplo de um token de trajeto retornado:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Transmita o token de trajeto ao SDK do Navigation usando o método setDestinationsWithToken:completionHandler: de mapView.navigator. O SDK do Navigation recebe os destinos e as opções de trajeto do token de trajeto, então não é necessário transmitir pontos de referência.

   O modo de viagem definido no app, como mapView.travelMode, precisa ser um dos seguintes valores:

   • .driving (GMSNavigationTravelModeDriving): de carro. Esse é o valor padrão, então a maioria dos apps não precisa mudá-lo.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): motocicleta.

   Qualquer outro modo de transporte faz com que a solicitação falhe com .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Com qualquer um dos valores compatíveis, o trajeto usa o modo de transporte no token de trajeto. Por exemplo, se o app usa o modo de carro, mas o token de trajeto é para uma moto, o SDK do Navigation vai fornecer um trajeto para moto. Para confirmar qual modo de transporte o trajeto usa, verifique resolvedParameters.travelMode. Para mais informações, consulte Opções de roteamento resolvidas.

3. Verifique o status do trajeto no gerenciador de conclusão. Quando o SDK de navegação termina de calcular o trajeto, ele transmite um GMSNavigationRouteDescription para o gerenciador de conclusão. Se ele encontrar um trajeto do local do veículo até os destinos no token de trajeto, o routeStatus da descrição do trajeto será .OK (GMSRouteStatusOK), e você poderá iniciar a navegação. Caso contrário, o gerenciador de conclusão também vai receber um NSError que descreve a falha. Exemplo:

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

Verificar se o SDK do Navigation aplicou seu token de trajeto

Um status de trajeto .OK significa que o SDK de navegação encontrou um trajeto, mas não necessariamente o que você planejou. Para verificar se o trajeto corresponde ao planejado, siga estas etapas no gerenciador de conclusão:

1. Confirme se o routeStatus da descrição da rota é .OK. O SDK do Navigation só fornece detalhes do token de trajeto quando encontra um trajeto. Para mais informações, consulte a Etapa 2.

2. Receba o routeTokenExecutionDetails da descrição do trajeto, um objeto que está em conformidade com o protocolo GMSNavigationRouteTokenExecutionDetails. Se o servidor não fornecer detalhes do token de trajeto, essa propriedade será nil.

3. Verifique a propriedade tokenExecutionStatus dos detalhes da execução. Se for .tokenSuccessfullyApplied, o trajeto corresponde ao planejado. Qualquer outro status significa que o trajeto pode ser diferente do planejado. Para mais informações sobre cada status, consulte Valores de status de execução do token.

4. Opcional: se o status for .tokenSuccessfullyApplied, verifique a propriedade resolvedParameters dos mesmos detalhes de execução para saber quais opções de trajeto o trajeto usa, por exemplo, se ele evita pedágios. Para mais informações, consulte Opções de roteamento resolvidas.

Valores de status de execução do token

Se routeStatus for .OK, será possível iniciar a orientação com qualquer status de execução de token. O status informa se o trajeto segue o planejado.

Se o trajeto não seguir necessariamente o planejado e o trajeto exato for importante, por exemplo, porque você o usou para calcular um preço, registre o status ou solicite um novo token de trajeto do local atual do veículo.

Opções de roteamento resolvidas

resolvedParameters é um objeto que segue o protocolo GMSNavigationRouteTokenResolvedParameters ou nil se as opções de trajeto não estiverem disponíveis. Ele tem as seguintes propriedades:

• travelMode: o meio de transporte usado pelo trajeto, como .driving (GMSNavigationTravelModeDriving). O SDK do Navigation também informa .driving quando o trajeto usa um meio de transporte que não tem um valor correspondente ou quando o meio de transporte não está disponível.
• avoidTolls: se o trajeto evita pedágios.
• avoidHighways: se o trajeto evita rodovias.
• avoidFerries: se o trajeto evita balsas.
• avoidTunnels: se o trajeto foi calculado para evitar túneis, quando possível.
• avoidVignettes: os países em que o trajeto foi calculado para evitar pedágios, quando possível, como códigos de região de duas letras do CLDR Unicode, como CH para a Suíça.
• rerouteStrategy: a estratégia que o back-end de roteamento usa para calcular novas rotas durante a viagem. As estratégias incluem .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), que usa os parâmetros de roteamento no token de trajeto para calcular novos trajetos.

Se o status de execução do token não for .tokenSuccessfullyApplied, o SDK de navegação vai informar apenas travelMode, avoidTolls, avoidHighways e avoidFerries. As outras propriedades têm os valores padrão, mesmo que você tenha pedido para evitar túneis ou pedágios ao solicitar o token de trajeto: avoidTunnels é false (NO), avoidVignettes está vazio e rerouteStrategy é .unknown (GMSNavigationRerouteStrategyUnknown).

Exemplo

O exemplo de código a seguir demonstra como planejar um trajeto usando um token de trajeto, verificar se o SDK do Navigation aplicou o token e iniciar a orientação.

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Cenários com várias paradas

É possível configurar no máximo 25 waypoints.

O SDK de navegação não avança automaticamente para o próximo destino. Quando o veículo chegar a um ponto de referência, chame continueToNextDestinationWithCompletion: para iniciar o próximo trecho da viagem. Isso também se aplica a tokens de trajeto que têm pontos intermediários. Quando você avança para o próximo destino, o SDK do Navigation continua seguindo o trajeto do token de trajeto em vez de planejar um novo.

Como os tokens de trajeto e o SDK do Navigation interagem

Veja como o SDK do Navigation lida com o trajeto planejado:

• Substitui todos os destinos definidos anteriormente.

• Usa o local de partida do veículo.

• Ajusta o trajeto de acordo com as condições da via e do trânsito. Consulte Por que um trajeto planejado pode não ser seguido exatamente.

• Usa as opções de trajeto definidas no token de trajeto em vez das seguintes configurações no app, inclusive ao calcular um novo trajeto durante a viagem:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • O modo de viagem definido no app

• Segue estas configurações ao calcular ou ajustar o trajeto:

  • Objetivos do trajeto do seu token de trajeto, como trajeto ecológico ou o trajeto mais curto. Se o SDK do Navigation precisar ajustar o trajeto, ele vai usar os objetivos especificados quando você solicitou o token de trajeto.
  • Opções relacionadas a waypoints do token de rota, como a preferência de lado da via.