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.

Importante: o trajeto que os motoristas fazem pode ser diferente do que você planejou. Mudanças no trânsito ou nas condições da via, o veículo saindo do trajeto planejado ou uma mudança para um trajeto mais rápido podem alterar o trajeto durante a viagem. Sempre que o SDK de navegação calcula um novo trajeto, ele usa as opções de trajeto definidas no token, como evitar pedágios.

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.

Dica: um token de trajeto é para uma origem e um destino específicos e em um determinado momento. É necessário fazer uma nova solicitação de API Routes ou API Route Optimization para receber um novo token de rota.

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.

Dica: como prática recomendada, sempre solicite um novo token de trajeto ao definir o destino no SDK do Navigation e planeje alguma variação para evitar impactos nos seus negócios.

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.

Observação: é possível especificar valores precisos de origem e destino, como entradas, docas de carga ou áreas de retirada designadas, no token de rota usando um token de ponto de navegação.

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:

   String 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 Navigator.setDestinationsWithToken. O SDK de navegação recebe os destinos e as opções de trajeto do token de trajeto, então não é necessário transmitir pontos de referência ou um modo de viagem.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

   Observação: se o app usa uma versão do SDK do Navigation anterior à 8.1, use os métodos descontinuados setDestinations que usam CustomRoutesOptions e transmita os mesmos waypoints de destino usados para criar o token de trajeto.

3. Verifique o status do trajeto no seu callback. Quando o SDK de navegação termina de calcular o trajeto, ele transmite um RouteDescription para o callback. Se ele encontrar um trajeto do local do veículo até os destinos no token de trajeto, o RouteDescription.getRouteStatus vai retornar Navigator.RouteStatus.OK, e você poderá iniciar a navegação. Exemplo:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

Observação: se você precisar percorrer o mesmo trajeto novamente, solicite um novo token de trajeto.

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 callback:

1. Confirme se RouteDescription.getRouteStatus retorna Navigator.RouteStatus.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. Chame RouteDescription.getRouteTokenExecutionDetails para receber um objeto RouteTokenExecutionDetails. Se o servidor não fornecer detalhes do token de trajeto, esse método vai retornar null.

3. Chame getTokenExecutionStatus no objeto RouteTokenExecutionDetails. Se retornar TOKEN_SUCCESSFULLY_APPLIED, 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 TOKEN_SUCCESSFULLY_APPLIED, chame getResolvedParameters no mesmo objeto RouteTokenExecutionDetails para verificar quais opções de trajeto são usadas, como evitar pedágios. Para mais informações, consulte Opções de roteamento resolvidas.

Valores de status de execução do token

Se o status do trajeto for OK, você poderá iniciar a orientação com qualquer status de execução de token. O status informa se o trajeto segue o planejado.

Status	Segue o trajeto planejado	Descrição
TOKEN_SUCCESSFULLY_APPLIED	Sim	O SDK de navegação aplicou seu token de trajeto.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Não necessariamente.	O SDK de navegação não conseguiu recriar o trajeto planejado porque um local na solicitação de trajeto estava a mais de 25 metros do local correspondente no token de trajeto. Com setDestinationsWithToken, isso significa que o dispositivo estava a mais de 25 metros da origem no token de trajeto. O trajeto ainda vai para os destinos, mas o SDK de navegação não pode confirmar se ele usa as opções de trajeto do token, como evitar pedágios.
TOKEN_IGNORED_OTHER	Não necessariamente.	O SDK do Navigation não conseguiu recriar o trajeto planejado por outro motivo, por exemplo, porque uma via no trajeto planejado está fechada. O trajeto ainda vai para os destinos, mas o SDK de navegação não pode confirmar se ele usa as opções de trajeto do token, como evitar pedágios.
NO_TOKEN_PROVIDED	Não relevante	A solicitação de trajeto não incluiu um token de trajeto.
UNKNOWN	Desconhecido	O status é desconhecido.

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

getResolvedParameters retorna um objeto RouteTokenResolvedParameters ou null se as opções de trajeto não estiverem disponíveis. RouteTokenResolvedParameters tem os seguintes métodos:

• getTravelMode: o meio de transporte usado no trajeto, como RoutingOptions.TravelMode.DRIVING. O SDK do Navigation também informa RoutingOptions.TravelMode.DRIVING quando o trajeto usa um modo de transporte que não tem um valor correspondente ou quando o modo de transporte não está disponível.
• getAvoidTolls: se o trajeto evita pedágios.
• getAvoidHighways: se o trajeto evita rodovias.
• getAvoidFerries: se o trajeto evita balsas.

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.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

Observação: é possível configurar no máximo 25 paradas.

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:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • 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.

Observação: com setDestinationsWithToken, você não transmite waypoints. Assim, o SDK do Navigation usa os destinos e as opções de waypoint do seu token de trajeto. Para definir opções de waypoint, como a preferência de lado da via ou paradas de veículos, use os campos sideOfRoad e vehicleStopover nos waypoints na solicitação de API Routes. A origem é sempre o local do dispositivo. Portanto, as opções que você define na origem na solicitação da API Routes não se aplicam.