Um feed de dados de navegação detalhada fornece informações apenas de navegação para dispositivos não projetados para orientação de navegação baseada 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
É possível usar o feed de instruções passo a passo para criar experiências em que a interface completa do SDK de navegação não é adequada, como no Android Auto ou em 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 Navigation para Android para que ele possa receber novas informações de navegação em tempo real (aproximadamente 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)
Para consumir uma versão independente da biblioteca TurnByTurn, siga estas etapas:
- Configure seu 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 à 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' }
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 você não tiver acesso, entre em contato com seu representante.
- Faça o download e descompacte
google_turnbyturn_*.jar
. - Copie o arquivo JAR salvo no diretório
app/libs
do projeto. 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.
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 . Você pode criar um novo serviço de navegação para essas atualizações ou usar um serviço existente.
O benefício de usar um serviço para receber atualizações de navegação é que o serviço pode ser executado 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 mensagens
As mensagens NavInfo
podem ser identificadas por meio do campo Message.what da classe Message
, definida como o valor de TurnByTurnManager.MSG_NAV_INFO
.
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 conferir 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.Recalculando a rota:
REROUTING
significa que a navegação está em andamento, mas o navegador está procurando uma nova rota. A próxima etapa de manobra não está disponível porque ainda não há uma nova rota. No app de exemplo, a mensagem "Recalculando rota…" aparece na tela de informações de navegação. Depois que uma rota é encontrada, uma mensagemNavInfo
é enviada com o estadoENROUTE
.Interrompida:
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 estadoSTOPPED
limpa a exibição de informações de navegação para evitar que as instruções de etapas sejam exibidas.
Preencher a tela do feed
Agora que você configurou o serviço de trajeto, esta seção aborda os elementos visuais e de texto que podem ser usados para preencher os cards de orientação do feed de trajeto.
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 |
Ícone de manobra | Distância até o destino |
Distância até a próxima etapa | |
Campos de indicação de faixa |
Orientação de faixa
O SDK de navegação representa as faixas no card de direção da 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 indicaçã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}]
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 de uma determinada etapa com o método StepInfo.getManeuver()
.
Você precisa criar ícones de manobra e parear com as manobras associadas.
Para algumas manobras, é possível configurar um mapeamento um para um para um ícone, como
DESTINATION_LEFT
e DESTINATION_RIGHT
. No entanto, como algumas manobras são
semelhantes, talvez você queira mapear mais de uma manobra para um único ícone. Por
exemplo, TURN_LEFT
e ON_RAMP_LEFT
podem ser mapeados para o ícone de sinal de pare.
Algumas manobras contêm um rótulo clockwise
ou counterclockwise
adicional,
que o SDK determina com base no lado de direção de um país. Por exemplo, em países onde 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 da manobra no sentido anti-horário.
Expanda para conferir exemplos de ícones para diferentes manobras
Ícone de amostra | 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 orientação de movimentação e 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 conferir mais detalhes.
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: