Un feed de datos paso a paso proporciona información de solo navegación a los dispositivos que no están diseñados para guías de navegación basadas en mapas. Proporciona las próximas maniobras con los elementos que debes ingresar:
- íconos (izquierda, derecha, cambio de sentido)
- girar los números en las rotondas
- nombres de rutas
- las distancias estimadas y el tiempo hasta el siguiente paso de la navegación o el destino final
Puedes usar el feed paso a paso para crear experiencias en las que no sea adecuada la IU completa del SDK de Navigation, como para Android Auto o para pantallas pequeñas en las que no hay una pila completa de Android disponible. Por ejemplo, podrías usar esta opción para pasajeros de vehículos de dos ruedas, donde puedes proyectar orientación solo de navegación para ayudarlos a llegar a su destino más rápido y con mayor confianza con una cantidad mínima de distracciones.
Para usar el SDK, deberás crear un servicio y registrarlo en el SDK de Navigation para Android de modo que pueda recibir información de navegación nueva en tiempo real (alrededor de una vez por segundo durante la navegación).
En este documento, se muestra cómo crear y registrar un servicio de navegación que recibe información de navegación del SDK y proporciona el estado de navegación al dispositivo receptor.
Descripción general
En esta sección, se describe cómo agregar la biblioteca TurnByTurn a tus proyectos y se resume el flujo de alto nivel para compilar la funcionalidad paso a paso.
Agrega la biblioteca de TurnByTurn a tu proyecto con Maven (recomendado).
Para consumir una versión independiente de la biblioteca de TurnByTurn, sigue estos pasos:
Configura tu entorno para acceder al repositorio Maven del host como se describe en Cómo comenzar a usar el SDK de Driver en la Documentación de viajes y pedidos.
Agrega la siguiente dependencia a tu configuración de Maven o 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' }
Agrega la biblioteca de TurnByTurn a tu proyecto con un archivo JAR descargado (alternativa)
La biblioteca de TurnByTurn está disponible como un archivo JAR en esta carpeta del SDK. Si no tienes acceso, comunícate con tu representante.
- Descarga y descomprime
google_turnbyturn_*.jar
. - Copia el archivo JAR descargado en el directorio
app/libs
de tu proyecto. Agrega lo siguiente a tu
build.gradle
para incluir el JAR en tu compilación.dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
Cómo usar la biblioteca TurnByTurn
Estos son los pasos de alto nivel para habilitar la funcionalidad paso a paso. En las siguientes secciones, se proporcionan detalles sobre cada paso.
Crea un servicio para recibir actualizaciones de navegación.
Consulta un ejemplo de una pantalla de navegación en la que se muestran elementos esenciales.
Crea un servicio para recibir actualizaciones de navegación {#service}
El SDK de Navigation se vincula a tu servicio TurnByTurn y envía actualizaciones de navegación a través de Android Messenger. Puedes crear un servicio de navegación nuevo para estas actualizaciones o usar uno existente.
El beneficio de usar un servicio para recibir actualizaciones de navegación es que este puede permanecer en un proceso independiente en segundo plano.
El servicio del siguiente ejemplo recibe información de navegación y usa TurnByTurnManager
para convertir los datos en un objeto NavInfo
que contiene los detalles de navegación.
/** * 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 mensajes
Los mensajes NavInfo
se pueden identificar mediante el campo Message.what de la clase Message
, que se establece en el valor de TurnByTurnManager.MSG_NAV_INFO
.
Cómo registrar el servicio para las actualizaciones de navegación {#register}
Los siguientes fragmentos de código registran el servicio de navegación.
boolean isNavInfoReceivingServiceRegistered = navigator.registerServiceForNavUpdates( getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);
Cómo iniciar y detener el servicio
El servicio de navegación estará activo siempre que se vincule el SDK de Navigation. Puedes llamar a startService()
y stopService()
de forma manual para controlar el ciclo de vida del servicio de navegación, pero cuando registras tu servicio con el SDK de Navigation, este se inicia automáticamente y solo se detiene cuando cancelas el registro. Según cómo configures tu app, te recomendamos que consideres iniciar un servicio en primer plano, como se describe en la Descripción general de los servicios de la documentación de Android.
Cancela el registro del servicio
Para dejar de recibir actualizaciones de navegación, cancela el registro del servicio del SDK de Navigation.
navigator.unregisterServiceForNavUpdates();
Comprende los estados de navegación {#states}
Usa NavInfo.getNavState()
para obtener el estado actual de la navegación, que es uno de los siguientes:
Enruta: El estado
ENROUTE
significa que la navegación guiada está actualmente activa y que el usuario se encuentra en la ruta proporcionada. Hay información disponible sobre el próximo paso de maniobra actual.Redireccionamiento:
REROUTING
significa que la navegación está en curso, pero el navegador está buscando una ruta nueva. El próximo paso de la maniobra no está disponible porque aún no hay una ruta nueva. En la app de ejemplo, aparecerá el mensaje "Redireccionando..." en la pantalla de información de navegación. Una vez que se encuentra una ruta, se envía un mensajeNavInfo
con el estadoENROUTE
.Detenida:
STOPPED
significa que finalizó la navegación. Por ejemplo, la navegación se detiene cuando el usuario sale de la navegación en la app. En la app de ejemplo, un estadoSTOPPED
borra la pantalla de información de navegación para evitar que se muestren instrucciones de paso persistentes.
Propaga los datos que se muestran en el feed
Ahora que configuraste tu servicio paso a paso, en esta sección se abordan los elementos visuales y de texto que puedes usar para propagar las tarjetas de guía del feed paso a paso.
Campos de información de la tarjeta de navegación
Cuando el conductor inicia la navegación guiada, aparece una tarjeta de navegación en la parte superior, que contiene la fecha de navegación propagada desde el SDK de Navigation. La imagen relacionada muestra un ejemplo de estos elementos esenciales de navegación.
En esta tabla, se muestran los campos de la información de navegación y dónde los encuentras.
Campos para cada paso de navegación | Campos del viaje general |
---|---|
Se encontró en StepInfo |
Se encontró en NavInfo |
Nombre completo de la ruta | Tiempo restante |
Ícono de maniobras | Distancia hasta el lugar de destino |
Distancia al paso siguiente | |
Campos de indicación de carril |
Indicación de carril
El SDK de Navigation representa los carriles en la tarjeta de giro de navegación como objetos de datos Lane y LaneDirection. Un objeto Lane
representa un carril específico durante la navegación y tiene una lista de objetos LaneDirection
que describen todos los giros que se pueden realizar desde ese carril.
La dirección recomendada que debe tomar un conductor en un carril se marca mediante el campo isRecommended.
Ejemplo de indicación de carril
En el siguiente fragmento, se ilustra la representación de datos de los carriles que se muestran arriba.
// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
{/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]
// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]
Crea íconos para las maniobras
El enum Maneuver
define cada maniobra posible que se puede producir mientras navegas, y puedes obtener la maniobra para un paso determinado desde el método StepInfo.getManeuver()
.
Debes crear íconos de maniobras y vincularlos con sus maniobras asociadas.
En algunos casos, puedes configurar una asignación uno a uno para un ícono, como DESTINATION_LEFT
y DESTINATION_RIGHT
. Sin embargo, dado que algunas maniobras son similares, es posible que quieras asignar más de una maniobra a un solo ícono. Por ejemplo, tanto TURN_LEFT
como ON_RAMP_LEFT
podrían asignarse al ícono de giro a la izquierda.
Algunas maniobras contienen una etiqueta clockwise
o counterclockwise
adicional, que el SDK determina en función de la conducción en un país. Por ejemplo, en los países donde la conducción se realiza por el lado izquierdo de la ruta, los conductores dan una rotonda o gira en U en el sentido de las manecillas del reloj, mientras que los países que circulan por el lado derecho de la ruta lo hacen en el sentido de las manecillas del reloj. El SDK de Navigation detecta si una maniobra se produce en el tráfico hacia la izquierda o la derecha, y genera la maniobra correspondiente. Por lo tanto, el ícono de maniobra puede ser diferente para una maniobra en sentido horario o en sentido antihorario.
Expandir para ver ejemplos de íconos de diferentes maniobras
Ícono de ejemplo | Maniobras paso a paso |
---|---|
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
|
Cómo usar íconos generados
Para facilitar los casos de uso de Android Auto, el SDK de Navigation admite la generación de íconos de maniobra y de guía de carril. Estos íconos se ajustan a la guía de tamaño de imagen de la biblioteca de apps para vehículos de Android Auto, que recomienda establecer como objetivo un cuadro delimitador de 500 x 74 dp. Consulta setsLaneImage y CarIcon en la documentación de referencia de Android para obtener más detalles.
Ejemplo de generación de íconos
NavigationUpdatesOptions options =
NavigationUpdatesOptions.builder()
.setNumNextStepsToPreview(numNextStepsToPreview)
.setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
.setDisplayMetrics(getResources().getDisplayMetrics())
.build();
boolean isRegistered =
navigator.registerServiceForNavUpdates(
getPackageName(),
NavInfoReceivingService.class.getName(),
options);
Después de habilitar la generación de íconos, el objeto StepInfo
de TurnbyTurn propaga los campos maneuverBitmap y lanesBitmap con los íconos.
Próximos pasos
- Apps para Android Auto: