Ativar feed de dados passo a passo

Um feed de dados passo a passo fornece informações somente de navegação para dispositivos não projetados para orientações de navegação baseadas em mapa. Ele fornece os elementos a seguir para as próximas manobras:

• ícones (esquerda, direita, retorno)
• virar números em rotatórias
• nomes de vias
• distâncias e tempo estimados para a próxima etapa da navegação ou destino final

Você pode usar o feed de navegação guiada para criar experiências em que a interface completa do SDK de navegação não é adequada, como para o Android Auto ou para telas pequenas em que uma pilha completa do Android não está disponível. Por exemplo, você pode usar esse recurso para motoristas de veículos de duas rodas, em que é possível projetar orientações somente de navegação para ajudá-los a chegar ao destino mais rápido e com mais confiança com o mínimo de distrações.

Para usar o SDK, crie um serviço e registre-o com o SDK do Navigation para Android para que ele possa receber novas informações de navegação em tempo real (cerca de uma vez por segundo, durante a navegação).

Este documento mostra como criar e registrar um serviço de navegação que recebe informações de navegação do SDK e fornece o estado de navegação ao dispositivo receptor.

Visão geral

Esta seção descreve como adicionar a biblioteca TurnByTurn aos seus projetos e resume o fluxo de alto nível para criar a funcionalidade de navegação guiada.

Adicionar a biblioteca TurnByTurn ao seu projeto usando o Maven (recomendado)

Observação: você pode pular esta etapa se já tiver configurado o app com o SDK de navegação, que contém a biblioteca TurnByTurn.

Para consumir uma versão independente da biblioteca TurnByTurn, siga estas etapas:

1. Configure o ambiente para acessar o repositório Maven do host:

   Maven

   Adicione a instrução a seguir ao seu arquivo pom.xml:

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   Gradle

   Adicione a instrução a seguir ao seu arquivo build.gradle:

   repositories {
       ...
       google()
   }
       

Adicione a seguinte dependência à sua configuração do Maven ou Gradle:

2. Maven

   <dependencies>
   ...
   <dependency>
         <groupId>com.google.android.maps</groupId>
         <artifactId>google_turnbyturn</artifactId>
         <version>1.0.0</version>
   </dependency>
   </dependencies>
       
       

   Gradle

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
       

Adicione a biblioteca TurnByTurn ao seu projeto usando um arquivo JAR transferido por download (alternativa)

A biblioteca TurnByTurn está disponível como um arquivo JAR nesta pasta do SDK. Se não tiver acesso, entre em contato com seu representante.

1. Baixe o arquivo google_turnbyturn_*.jar e descompacte-o.
2. Copie o arquivo JAR salvo no diretório app/libs do projeto.

3. Adicione o código a seguir ao build.gradle para incluir o JAR no build.

   dependencies {
      ...
      api fileTree(include: ['*.jar'], dir: 'libs')
   }
   

Como usar a biblioteca TurnByTurn

Estas são as etapas principais para ativar a funcionalidade de navegação guiada. As seções a seguir dão detalhes sobre cada etapa.

1. Criar um serviço para receber atualizações de navegação.

2. Registre o serviço.

3. Entenda os estados de navegação.

4. Confira um exemplo de tela de navegação que mostra elementos essenciais.

Criar um serviço para receber atualizações de navegação

O SDK do Navigation é vinculado ao seu serviço TurnByTurn e envia atualizações de navegação pelo Android Messenger . É possível criar um novo serviço de navegação para essas atualizações ou usar um serviço existente.

A vantagem de usar um serviço para receber atualizações de navegação é que ele pode ficar em um processo em segundo plano separado.

O serviço no exemplo a seguir recebe informações de navegação e usa o TurnByTurnManager para converter os dados em um objeto NavInfo que contém os detalhes de navegação.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

Códigos de mensagem

As mensagens NavInfo podem ser identificadas por meio do campo Message.what da classe Message, definida como o valor de TurnByTurnManager.MSG_NAV_INFO.

Observação: deixe de lado o intervalo de valores 7200-7299 para códigos de mensagem, porque o SDK do Navigation pode usar códigos de mensagem nesse intervalo no futuro.

Como registrar o serviço para atualizações de navegação

Os snippets de código a seguir registram o serviço de navegação.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

Como iniciar e interromper o serviço

O serviço de navegação fica ativo desde que o SDK de navegação esteja vinculado a ele. É possível chamar startService() e stopService() manualmente para controlar o ciclo de vida do serviço de navegação. No entanto, quando você registra o serviço com o SDK do Navigation, ele é iniciado automaticamente e só é interrompido quando você cancela o registro. Dependendo de como você configurar o app, é recomendável iniciar um serviço em primeiro plano, conforme descrito na Visão geral dos serviços da documentação do Android.

Como cancelar o registro do serviço

Para não receber mais atualizações de navegação, cancele o registro do serviço no SDK do Navigation.

navigator.unregisterServiceForNavUpdates();

Entender os estados de navegação

Use NavInfo.getNavState() para ver o estado atual da navegação, que é um dos seguintes:

• Em rota: o estado ENROUTE significa que a navegação guiada está ativa no momento e que o usuário está na rota fornecida. Informações sobre a próxima etapa da manobra atual estão disponíveis.

• Novo trajeto: REROUTING significa que a navegação está em andamento, mas o navegador está procurando uma nova rota. A próxima etapa da manobra não está disponível porque ainda não há um novo trajeto. No app de exemplo, uma mensagem "Redirecionando..." aparece na exibição de informações de navegação. Depois que uma rota é encontrada, uma mensagem NavInfo é enviada com o estado ENROUTE.

• Interrompido: STOPPED significa que a navegação terminou. Por exemplo, a navegação é interrompida quando o usuário sai da navegação no app. No app de exemplo, um estado STOPPED limpa a exibição de informações de navegação para evitar que instruções de etapas restantes sejam mostradas.

Preencher a exibição do feed

Agora que você configurou seu serviço de navegação guiada, esta seção aborda os elementos visuais e de texto que você pode usar para preencher os cards de orientação para o feed passo a passo.

Campos de informações do card de navegação

Quando o usuário entra na navegação guiada, um card de navegação aparece na parte de cima com os dados de navegação preenchidos pelo SDK de navegação. A imagem relacionada mostra um exemplo desses elementos de navegação essenciais.

Esta tabela mostra os campos de informações de navegação e onde eles podem ser encontrados.

Campos de cada etapa de navegação	Campos da viagem geral
Encontrado em StepInfo	Encontrado em NavInfo
Nome completo da via	Tempo restante
O ícone da manobra	Distância até o destino
Distância até a próxima etapa
Campos de orientação de faixa

Orientação de faixa

O SDK do Navigation representa as faixas no card de navegação de navegação como objetos de dados Lane e LaneDirection. Um objeto Lane representa uma faixa específica durante a navegação e tem uma lista de objetos LaneDirection que descrevem todas as curvas que podem ser feitas nessa faixa.

A direção recomendada que um usuário precisa seguir em uma faixa é marcada pelo campo isRecommended.

Exemplo de orientação de faixa

O snippet a seguir ilustra a representação de dados das faixas acima.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

Crie ícones para manobras

O enum Maneuver define cada manobra possível que pode ocorrer durante a navegação, e você pode conferir a manobra de uma determinada etapa com o método StepInfo.getManeuver().

Crie ícones de manobras e combine-os com as manobras associadas. Em algumas manobras, você pode configurar um mapeamento de um para um para um ícone, como DESTINATION_LEFT e DESTINATION_RIGHT. No entanto, como algumas manobras são semelhantes, convém mapear mais de uma manobra para um único ícone. Por exemplo, TURN_LEFT e ON_RAMP_LEFT podem ser mapeados para o ícone de virar à esquerda.

Manobras do Android Auto: as manobras no SDK Navigation têm um mapeamento individual para o Android Auto, mas é necessário converter os tipos para o formato correto do Android Auto. Consulte Garantir os tipos de manobra corretos em Ativar a navegação para o Android Auto.

Algumas manobras contêm um rótulo clockwise ou counterclockwise extra, que o SDK determina com base no lado do percurso de um país. Por exemplo, em países em que a direção é do lado esquerdo da via, os motoristas fazem uma rotatória ou retorno no sentido horário, enquanto os países que dirigem no lado direito da via seguem no sentido horário. O SDK do Navigation detecta se uma manobra ocorre no trânsito do lado esquerdo ou direito e gera a manobra apropriada. Portanto, seu ícone de manobra pode ser diferente no sentido horário ou no sentido anti-horário.

Clique para abrir e conferir exemplos de ícones de diferentes manobras

Ícone de exemplo	Manobras por turno
	DEPART UNKNOWN
	STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
	TURN_RIGHT ON_RAMP_RIGHT
	TURN_LEFT ON_RAMP_LEFT
	TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
	TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
	TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
	TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
	TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
	TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
	ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_RIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
	ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_STRAIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
	ROUNDABOUT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_LEFT_CLOCKWISE
	ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_LEFT_CLOCKWISE
	ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
	ROUNDABOUT_U_TURN_CLOCKWISE
	ROUNDABOUT_COUNTERCLOCKWISE
	ROUNDABOUT_CLOCKWISE
	ROUNDABOUT_EXIT_COUNTERCLOCKWISE
	ROUNDABOUT_EXIT_CLOCKWISE
	MERGE_RIGHT OFF_RAMP_RIGHT
	MERGE_LEFT OFF_RAMP_LEFT
	FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
	FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
	MERGE_UNSPECIFIED
	DESTINATION
	DESTINATION_RIGHT
	DESTINATION_LEFT
	FERRY_BOAT
	FERRY_TRAIN

Usar ícones gerados

Para facilitar os casos de uso do Android Auto, o SDK de navegação oferece suporte à geração de ícones de manobra e orientação de faixa. Esses ícones se encaixam na orientação de dimensionamento de imagem da biblioteca Android Auto Car App, que recomenda segmentar uma caixa delimitadora de 500 x 74 dp. Consulte setsLaneImage e CarIcon na documentação de referência do Android para mais detalhes.

Observação: a geração de ícones está desativada por padrão.

Exemplo de geração de ícone

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

Depois de ativar a geração de ícones, o objeto StepInfo TurnbyTurn preenche os campos maneuverBitmap e lanesBitmap com os ícones.

A seguir

• Para apps Android Auto:
  • Desenhar o mapa e ativar a navegação.