Ativar feed de dados passo a passo

Um feed de dados de navegação guiada fornece informações somente de navegação para dispositivos não projetados para orientações de navegação baseadas em mapas. Ela oferece manobras futuras com elementos que você fornece:

  • ícones (esquerda, direita, retorno)
  • Virar números em rotatórias
  • nomes de vias
  • estimativas de distância e tempo até a próxima etapa do trajeto 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 Android completa não está disponível. Por exemplo, você pode usar esse modo com passageiros de duas rodas, em que é possível projetar orientações de navegação para que cheguem ao destino com mais rapidez e confiança, com o mínimo de distrações.

Para usar o SDK, crie um serviço e registre-o no 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.

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

  1. Configure o ambiente para acessar o repositório Maven do host, conforme descrito em Introdução ao SDK do Driver na Documentação de viagem e pedido.

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

    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'
}

Adicionar 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. Faça o download e descompacte google_turnbyturn_*.jar.
  2. Copie o arquivo JAR transferido por download no diretório app/libs do projeto.

  3. Adicione o código abaixo 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 avançadas para ativar a funcionalidade de navegação guiada. As seções a seguir fornecem 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 exibição de navegação que mostra os elementos essenciais.

Criar um serviço para receber atualizações de navegação {#service}

O SDK do Navigation é vinculado ao serviço TurnByTurn e envia atualizações de navegação pelo Android Messenger . Você pode criar um novo serviço de navegação para essas atualizações ou usar um existente.

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

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 contenha 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 pelo campo Message.what da classe Message, que é definida como o valor de TurnByTurnManager.MSG_NAV_INFO.

Como registrar o serviço para atualizações de navegação {#register}

Os snippets de código abaixo 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 do Navigation esteja ativo. Você pode chamar startService() e stopService() manualmente para controlar o ciclo de vida do serviço de navegação, mas quando você registra seu serviço com o SDK do Navigation, ele é iniciado automaticamente e só é interrompido após o cancelamento do registro. Dependendo de como você configura seu app, considere 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 {#states}

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

  • Trajeto: o estado ENROUTE significa que a navegação guiada está ativa no momento e o usuário está no trajeto fornecido. Estão disponíveis informações sobre a próxima etapa da manobra atual.

  • Reencaminhamento: 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, a mensagem "Redirecionando..." aparece na exibição de informações de navegação. Quando uma rota é encontrada, uma mensagem NavInfo é enviada com o estado ENROUTE.

  • Interrompido: STOPPED significa que a navegação foi finalizada. 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 pertencentes sejam mostradas.

Preencher a exibição do feed

Agora que você configurou o serviço de navegação guiada, esta seção aborda os elementos visuais e de texto que podem ser usados para preencher os cards de orientação do feed de navegação guiada.

Uma tela de dispositivo móvel que mostra a próxima curva à esquerda a 30 metros na Avenida W Ahwanee. Na parte de baixo da tela, o tempo restante até o destino é de 46 minutos e a distância restante é de 59 milhas.

Quando o motorista entra na navegação guiada, um card de navegação aparece na parte de cima com a data preenchida pelo SDK do Navigation. A imagem relacionada mostra um exemplo desses elementos essenciais de navegação.

Esta tabela mostra os campos das informações de navegação e onde você as encontra.

Campos para cada etapa de navegação Campos da viagem
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 indicação de faixa

Orientação de pista

O SDK do Navigation representa as faixas no card 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.

Exemplo de configuração de orientação de faixa.

A rota recomendada para um motorista em uma faixa é marcada no campo isRecommended.

Exemplo de indicação de faixa

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

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

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

Criar ícones para manobras

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

É necessário criar ícones de manobra e combiná-los com as manobras associadas. Em algumas manobras, é possível configurar um mapeamento de um para um para um ícone, como DESTINATION_LEFT e DESTINATION_RIGHT. No entanto, como algumas manobras são semelhantes, você pode querer mapear mais de uma manobra para um único ícone. Por exemplo, TURN_LEFT e ON_RAMP_LEFT podem mapear para o ícone de virar à esquerda.

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

Clique para abrir ícones de exemplos de diferentes manobras

Ícone de exemplo Manobras TurnByTurn
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

Uma pequena lista de ícones gerados fornecidos pelo SDK do Navigation.

Para facilitar os casos de uso do Android Auto, o SDK do Navigation oferece suporte à geração de ícones de orientação de manobra e faixa. Esses ícones se encaixam nas orientações 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 saber mais.

Exemplo de geração de ícones

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

Depois que você ativa a geração de ícones, o objeto StepInfo do TurnbyTurn preenche os campos maneuverBitmap e lanesBitmap com os ícones.

A seguir