Habilitar feed de datos paso a paso

Un feed de datos de instrucciones paso a paso proporciona información de navegación solo a dispositivos que no están diseñados para la guía de navegación basada en mapas. Proporciona las próximas maniobras con los elementos que proporcionas:

  • íconos (izquierda, derecha, giro en U)
  • números de giro en las rotondas
  • nombres de las rutas
  • las distancias y el tiempo estimados hasta el próximo paso de navegación o el destino final

Puedes usar el feed paso a paso para crear experiencias en las que la IU completa del SDK de Navigation no sea adecuada, como para Android Auto o pantallas pequeñas en las que no está disponible una pila de Android completa. Por ejemplo, puedes usar esta función para conductores de vehículos de dos ruedas, en la que puedes proyectar instrucciones de navegación solo para ayudarlos a llegar a sus destinos más rápido y con más confianza con mínimas distracciones.

Para usar el SDK, crearás un servicio y lo registrarás con 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 reciba información de navegación del SDK y proporcione el estado de navegación al dispositivo receptor.

Descripción general

En esta sección, se describe cómo agregar la biblioteca de TurnByTurn a tus proyectos y se resume el flujo de alto nivel para compilar la funcionalidad de navegación paso a paso.

Para consumir una versión independiente de la biblioteca de TurnByTurn, sigue estos pasos:

  1. Configura tu entorno para acceder al repositorio de Maven del host:

    Maven

    Agrega lo siguiente a tu archivo pom.xml:

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

    Gradle

    Agrega lo siguiente a tu archivo build.gradle:

    repositories {
    ...
    google()
}
  2. 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.

  1. Descarga y descomprime google_turnbyturn_*.jar.
  2. Copia el archivo JAR descargado en el directorio app/libs de tu proyecto.

  3. Agrega lo siguiente a tu build.gradle para incluir el archivo JAR en tu compilación.

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

Cómo usar la biblioteca de instrucciones paso a paso

Estos son los pasos generales para habilitar la función de instrucciones paso a paso. En las secciones que siguen, se proporcionan detalles sobre cada paso.

  1. Crea un servicio para recibir actualizaciones de navegación.

  2. Registra el servicio.

  3. Comprende los estados de navegación.

Crea un servicio para recibir actualizaciones de navegación

El SDK de Navigation se vincula a tu servicio de instrucciones paso a paso y le 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 el servicio puede residir en un proceso en segundo plano independiente.

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 la 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 a través del campo Message.what de la clase Message, que se establece en el valor de TurnByTurnManager.MSG_NAV_INFO.

Cómo registrar el servicio para actualizaciones de navegación

En los siguientes fragmentos de código, se registra 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 está activo mientras el SDK de Navigation se vincule a él. 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 lo desregistras. Según cómo configures tu app, es posible que desees iniciar un servicio en primer plano, que se describe en la descripción general de los servicios de la documentación de Android.

Cómo cancelar el registro del servicio

Para dejar de recibir actualizaciones de navegación, cancela el registro del servicio desde el SDK de Navigation.

navigator.unregisterServiceForNavUpdates();

Comprende los estados de navegación

Usa NavInfo.getNavState() para obtener el estado actual de la navegación, que es uno de los siguientes:

  • En ruta: El estado ENROUTE significa que la navegación guiada está activa y que el usuario está en la ruta proporcionada. Hay información disponible sobre el próximo paso de la 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 maniobra no está disponible porque aún no hay una ruta nueva. En la app de ejemplo, aparece el mensaje "Recalculando ruta…" en la pantalla de información de navegación. Una vez que se encuentra una ruta, se envía un mensaje NavInfo con el estado ENROUTE.

  • Detenido: STOPPED significa que la navegación finalizó. Por ejemplo, la navegación se detiene cuando el usuario sale de la navegación en la app. En la app de ejemplo, un estado STOPPED borra la pantalla de información de navegación para evitar que se muestren instrucciones de pasos residuales.

Cómo propagar la visualización del feed

Ahora que configuraste tu servicio de instrucciones paso a paso, en esta sección se describen los elementos visuales y de texto que puedes usar para propagar las tarjetas de instrucciones del feed de instrucciones paso a paso.

Una pantalla de un dispositivo móvil que muestra que se debe girar a la izquierda en 100 pies en W Ahwanee Ave. En la parte inferior de la pantalla, el tiempo restante hasta el destino es de 46 minutos y la distancia restante es de 39 millas.

Cuando el usuario ingresa a la navegación guiada, aparece una tarjeta de navegación en la parte superior que contiene datos de navegación propagados desde el SDK de Navigation. La imagen relacionada muestra un ejemplo de estos elementos de navegación esenciales.

En esta tabla, se muestran los campos de información de navegación y dónde encontrarlos.

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
El ícono de maniobra Distancia al destino
Distancia hasta el siguiente paso
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 este carril.

Configuración de guía de carril de muestra.

El campo isRecommended marca la dirección recomendada que debe tomar un usuario en un carril.

Ejemplo de indicación de carril

En el siguiente fragmento, se ilustra la representación de datos de los carriles que se muestran anteriormente.

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

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

Crea íconos para las maniobras

La enumeración Maneuver define cada maniobra posible que podría ocurrir durante la navegación, y puedes obtener la maniobra de un paso determinado desde el método StepInfo.getManeuver().

Debes crear íconos de maniobra y vincularlos con sus maniobras asociadas. Para algunas maniobras, puedes configurar una asignación uno a uno a un ícono, como DESTINATION_LEFT y DESTINATION_RIGHT. Sin embargo, como algunas maniobras son similares, es posible que desees asignar más de una maniobra a un solo ícono. Por ejemplo, TURN_LEFT y 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 del lado de conducción de un país. Por ejemplo, en los países en los que se conduce por el lado izquierdo de la ruta, los conductores toman una rotonda o un giro en U en el sentido de las manecillas del reloj, mientras que en los países en los que se conduce por el lado derecho de la ruta, se hace en el sentido de las manecillas del reloj. El SDK de Navigation detecta si se produce una maniobra en el tráfico de la izquierda o la derecha y muestra la maniobra adecuada. Por lo tanto, el ícono de maniobra puede ser diferente para una maniobra en el sentido de las manecillas del reloj en comparación con una maniobra en sentido contrario.

Expande para ver ejemplos de íconos de diferentes maniobras

Ícono de muestra 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

Es una pequeña lista de íconos generados que proporciona el SDK de Navigation.

Para facilitar los casos de uso de Android Auto, el SDK de Navigation admite la generación de íconos de guía de maniobras y carriles. Estos íconos se ajustan a las instrucciones de tamaño de imagen de la biblioteca de apps para vehículos de Android Auto, que recomienda segmentar un cuadro de límite de 500 x 74 dp. Consulta setsLaneImage y CarIcon en la documentación de referencia de Android para obtener más información.

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 instrucciones paso a paso propaga los campos maneuverBitmap y lanesBitmap con los íconos.

¿Qué sigue?