Cómo comenzar a usar el SDK del controlador para Android

Puedes usar el SDK de Driver para mejorar la navegación y el seguimiento. a la aplicación Progreso del viaje y el pedido. El SDK de Driver proporciona la ubicación del vehículo y las actualizaciones de tareas en el motor de soluciones On-demand Rides and Deliveries de Fleet Engine.

El SDK de Driver mantiene al tanto los servicios de Fleet Engine y tus servicios personalizados de la ubicación y el estado del vehículo. Por ejemplo, el vehículo puede ser ONLINE. o OFFLINE, y la ubicación del vehículo cambia a medida que avanza un viaje.

También puedes consultar las apps de ejemplo de Android o muestras combinadas como ejemplo concreto.

Requisitos mínimos del sistema

El dispositivo móvil debe ejecutar Android 6.0 (nivel de API 23) o una versión posterior.

Configuración de compilaciones y dependencias

Las versiones 4.99 y posteriores del SDK de Driver están disponibles en el repositorio de Maven de Google.

Gradle

Agrega lo siguiente a tu archivo build.gradle:

repositories {
    ...
    google()
}

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>

Configuración del proyecto

Para usar el SDK del controlador, tu app debe orientarse minSdkVersion 23 o una versión posterior

Para ejecutar una aplicación compilada con el SDK de Driver, la biblioteca de el dispositivo debe tener Servicios de Google Play esté instalado.

Configura tu proyecto de desarrollo

Cómo configurar tu proyecto de desarrollo y obtener una clave de API para el proyecto en la consola de Google Cloud:

1. Crea un proyecto nuevo de la consola de Google Cloud o selecciona uno existente para usarlo. con el SDK de Driver. Espera unos minutos hasta que el proyecto nuevo se puede ver en la consola de Google Cloud.

2. Para ejecutar la app de demostración, tu proyecto debe tener acceso al SDK de Maps para Android. En la consola de Google Cloud, selecciona APIs y Servicios > Biblioteca y, luego, busca y habilita el SDK de Maps para Android

3. Para obtener una clave de API para el proyecto, selecciona APIs y Servicios > Credenciales > Crear credenciales > Clave de API Para más información sobre cómo obtener una clave de API, consulta Obtén una clave de API.

Agrega el SDK de Driver a tu app

El SDK de Driver está disponible en el repositorio de Maven de Google. El incluye los archivos del modelo de objetos del proyecto (.pom) del SDK y Javadocs. Para agregar el SDK del controlador a tu app, haz lo siguiente:

1. Agrega la siguiente dependencia a tu configuración de Gradle o Maven y reemplaza el Es el marcador de posición VERSION_NUMBER para la versión deseada del SDK de Driver.

   Gradle

   Agrega lo siguiente a tu build.gradle:

   dependencies {
     ...
     implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER'
   }
   

   Maven

   Agrega lo siguiente a tu pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
       <artifactId>transportation-driver</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

2. El SDK de Driver depende del SDK de Navigation. Esta dependencia se configura de tal manera de modo que, si se necesita una versión específica del SDK de Navigation, Se define de forma explícita en el archivo de configuración de compilación de la siguiente manera: omitir el bloque de código mencionado permitirá que el proyecto siempre descargue la versión más reciente del SDK de Navigation dentro de la versión de actualización principal. Ten en cuenta que los comportamientos combinados de las versiones más recientes del SDK de Driver y El SDK de Navigation se sometió a pruebas rigurosas antes de sus lanzamientos.

   Organiza la configuración de dependencias del desarrollo y la versión los entornos de producción según corresponda.

   Gradle

   Agrega lo siguiente a tu build.gradle:

   dependencies {
     ...
     implementation 'com.google.android.libraries.navigation:navigation:5.0.0'
   }
   

   Maven

   Agrega lo siguiente a tu pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>5.0.0</version>
     </dependency>
   </dependencies>
   

Agrega la clave de API a tu app

Una vez que hayas agregado el SDK del controlador a tu app, agrega la clave de API a tu app. Tú debe usar la clave de API del proyecto que obtuvo cuando configura tu proyecto de desarrollo.

En esta sección, se describe cómo almacenar tu clave de API para que pueda ser más segura. a los que hace referencia tu app. No debes incluir tu clave de API en tu versión un sistema de control de calidad. Debe almacenarse en el archivo local.properties, que se ubicado en el directorio raíz de tu proyecto. Para obtener más información sobre el local.properties, consulta Archivos de propiedades de Gradle.

Para optimizar esta tarea, puedes usar el complemento Secrets Gradle para Android.

Para instalar el complemento y almacenar tu clave de API, haz lo siguiente:

1. Abre el archivo build.gradle en el nivel raíz y agrega el siguiente código al Elemento dependencies en buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
       }
   }
   

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
       }
   }
   

2. Abre el archivo build.gradle a nivel de la app y agrega el siguiente código al elemento plugins.

   Groovy

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   

   Kotlin

   id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   

3. Si usas Android Studio, sincronizar tu proyecto con Gradle.

4. Abre el archivo local.properties en el directorio de nivel de proyecto y, luego, agrega el archivo siguiente código. Reemplaza YOUR_API_KEY por tu clave de API.

   MAPS_API_KEY=YOUR_API_KEY
   

5. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY. Luego, actualiza el atributo android:value de la siguiente manera:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
   

En el siguiente ejemplo, se muestra un manifiesto completo para una app de ejemplo:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.driverapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/_AppTheme">

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${MAPS_API_KEY}" />

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Nota: Para obtener la mejor experiencia de navegación, tanto el android.permission.ACCESS_COARSE_LOCATION y El equipo de atención al cliente debe otorgar los permisos android.permission.ACCESS_FINE_LOCATION usuario. Asegúrate de solicitar ambos durante el tiempo de ejecución dentro de la app.

Incluye las atribuciones requeridas en tu aplicación

Si usas el SDK del controlador en tu app, debes incluir texto de atribución y licencias de código abierto como parte de los avisos legales de tu app sección. Es mejor incluir las atribuciones como un elemento de menú independiente o como parte de un elemento de menú Acerca de.

La información sobre las licencias se encuentra en el archivo “third_party_licenses.txt”. archivo en el archivo AAR desarchivado.

Consulta https://developers.google.com/android/guides/opensource. sobre cómo incluir avisos de código abierto.

Dependencias

Si usas ProGuard para lo siguiente: optimizar tus compilaciones, quizás debas agregar las siguientes líneas a tu ProGuard de Terraform:

-dontwarn com.google.**
-dontwarn okio.**

El nivel de API mínimo admitido es 23.

Inicializa el SDK

Se requiere un ID de proveedor (por lo general, el ID del proyecto de Google Cloud) para hacer lo siguiente: inicializamos el objeto DriverContext. Para obtener más detalles sobre cómo configurar proyecto de Google Cloud, consulta Autenticación y autorización.

Antes de usar el SDK del controlador, primero debes inicializar el SDK de Navigation. Cómo inicializar el SDK:

1. Obtén un objeto Navigator de NavigationApi.

   Java

   NavigationApi.getNavigator(
       this, // Activity
       new NavigationApi.NavigatorListener() {
         @Override
         public void onNavigatorReady(Navigator navigator) {
           // Keep a reference to the Navigator (used to configure and start nav)
           this.navigator = navigator;
         }
       }
   );
   

   Kotlin

   NavigationApi.getNavigator(
     this, // Activity
     object : NavigatorListener() {
       override fun onNavigatorReady(navigator: Navigator) {
         // Keep a reference to the Navigator (used to configure and start nav)
         [e-mail] = navigator
       }
     },
   )
   

2. Crea un objeto DriverContext y propaga los campos obligatorios.

   Java

   DriverContext driverContext = DriverContext.builder(application)
       .setProviderId(providerId)
       .setVehicleId(vehicleId)
       .setAuthTokenFactory(authTokenFactory)
       .setNavigator(navigator)
       .setRoadSnappedLocationProvider(
           NavigationApi.getRoadSnappedLocationProvider(application))
       .build();
   

   Kotlin

   val driverContext =
     DriverContext.builder(application)
       .setProviderId(providerId)
       .setVehicleId(vehicleId)
       .setAuthTokenFactory(authTokenFactory)
       .setNavigator(navigator)
       .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application))
       .build()
   

3. Usa el objeto DriverContext para inicializar *DriverApi.

   Java

   RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
   

   Kotlin

   val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
   

4. Obtén el RidesharingVehicleReporter del objeto de la API. (*VehicleReporter extiende NavigationVehicleReporter).

   Java

   RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
   

   Kotlin

   val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
   

Autentica con AuthTokenFactory

Cuando el SDK de Driver genera actualizaciones de ubicación, debe enviar estas actualizaciones el servidor de Fleet Engine. Para autenticar estas solicitudes, el El SDK de Driver llamará a un llamador instancia de AuthTokenFactory. La fábrica es responsable de generar tokens de autenticación en la ubicación hora de actualización.

La forma exacta en que se generan los tokens será específica para la situación de cada desarrollador. Sin embargo, es probable que la implementación necesite realizar las siguientes acciones:

• recuperar un token de autenticación, posiblemente en formato JSON, desde un servidor HTTPS
• analizar y almacenar en caché el token
• actualiza el token cuando caduque

Para obtener más información sobre los tokens que espera el servidor de Fleet Engine, consulta Crear un token web JSON (JWT) para autorización.

A continuación, se muestra una implementación básica de un AuthTokenFactory:

Java

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String token;  // initially null
  private long expiryTimeMs = 0;

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  @Override
  public String getToken(AuthTokenContext authTokenContext) {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(authTokenContext.getVehicleId());
    }
    return token;
  }

  private void fetchNewToken(String vehicleId) {
    String url =
        new Uri.Builder()
            .scheme("https")
            .authority("yourauthserver.example")
            .appendPath("token")
            .appendQueryParameter("vehicleId", vehicleId)
            .build()
            .toString();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      token = obj.get("Token").getAsString();
      expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      // The expiry time could be an hour from now, but just to try and avoid
      // passing expired tokens, we subtract 10 minutes from that time.
      expiryTimeMs -= 10 * 60 * 1000;
    } catch (IOException e) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw new RuntimeException("Could not get auth token", e);
    }
  }
}

Kotlin

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: String = ""
  private var expiryTimeMs: Long = 0

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  override fun getToken(context: AuthTokenContext): String {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(authTokenContext.getVehicleId())
    }
     return token
  }

  fun fetchNewToken(vehicleId: String) {
    val url =
      Uri.Builder()
        .scheme("https")
        .authority("yourauthserver.example")
        .appendPath("token")
        .appendQueryParameter("vehicleId", vehicleId)
        .build()
        .toString()

    try {
      val reader = InputStreamReader(URL(url).openStream())

      reader.use {
        val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()

        token = obj.get("ServiceToken").getAsString()
        expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()

        // The expiry time could be an hour from now, but just to try and avoid
        // passing expired tokens, we subtract 10 minutes from that time.
        expiryTimeMs -= 10 * 60 * 1000
      }
    } catch (e: IOException) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw RuntimeException("Could not get auth token", e)
    }
  }
}

Esta implementación en particular usa el cliente HTTP de Java integrado para recuperar un en formato JSON desde el servidor de autenticación del desarrollador. El token es guardados para volver a usarlos. El token se vuelve a recuperar si el token anterior se encuentra en el transcurso de 10 minutos de su hora de vencimiento.

Es posible que tu implementación realice acciones de manera diferente; por ejemplo, usa un subproceso en segundo plano. para actualizar tokens.

Las excepciones en AuthTokenFactory se tratarán como transitorias, a menos que ocurran repetidamente. Después de varios intentos, el SDK del controlador supondrán que el es permanente y dejará de intentar enviar actualizaciones.

Informes de estado y errores con StatusListener

Dado que el SDK del controlador realiza acciones en el en segundo plano, usa StatusListener para activar notificaciones cuando se cumplan ciertas como errores, advertencias o mensajes de depuración. Los errores pueden ser transitorios por naturaleza (como BACKEND_CONNECTIVITY_ERROR) o pueden provocar que las actualizaciones de ubicación se detengan de forma permanente (como VEHICLE_NOT_FOUND, que indica un error de configuración).

Proporcionas una implementación de StatusListener opcional como la siguiente:

Java

class MyStatusListener implements StatusListener {
  /** Called when background status is updated, during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

Kotlin

class MyStatusListener : StatusListener() {
  /** Called when background status is updated, during actions such as location reporting. */
  override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

Notas sobre SSL/TLS

A nivel interno, la implementación del SDK de Driver usa SSL/TLS para comunicarse de forma segura con el servidor de Fleet Engine. Versiones anteriores de Android (API 19 o inferior) pueden requerir un parche SecurityProvider para poder comunicarse con el servidor. Deberías ver esto artículo para obtener más información sobre cómo trabajar con SSL en Android. El artículo también contiene muestras de código para aplicar parches al proveedor de seguridad.

Cómo habilitar las actualizaciones de ubicación

Una vez que tengas una instancia de *VehicleReporter, se habilitarán las actualizaciones de ubicación sencillo:

Java

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Kotlin

val reporter = ...

reporter.enableLocationTracking()

Las actualizaciones de ubicación se envían a intervalos regulares cuando el estado del vehículo es ONLINE Ten en cuenta que llamar a reporter.enableLocationTracking() no Establece automáticamente el estado del vehículo en ONLINE. Debes Establece el estado del vehículo de manera explícita.

De forma predeterminada, el intervalo del informe es de 10 segundos. El intervalo del informe puede se cambiará con reporter.setLocationReportingInterval(long, TimeUnit). El el intervalo de actualización mínimo admitido es de 5 segundos. Es posible que las actualizaciones más frecuentes generan solicitudes y errores más lentos.

Cómo inhabilitar las actualizaciones de ubicación

Cuando termine el turno del conductor, se podrán detener las actualizaciones de ubicación y vehículo marcado como sin conexión llamando DeliveryVehicleReporter.disableLocationTracking o RidesharingVehicleReporter.disableLocationTracking

Esta llamada provocará que se programe una actualización final para su entrega inmediata, que indica que el vehículo está sin conexión. Esta actualización no contendrá los datos del usuario ubicación.

Configuración del estado del vehículo

Cuando las actualizaciones de ubicación estén habilitadas, establecer el estado del vehículo en ONLINE hará lo siguiente: hacer que el vehículo esté disponible para consultas de SearchVehicles de manera similar, marcando vehículo como OFFLINE lo marcará como no disponible.

Tienes la opción de configurar el estado del vehículo en el servidor (consulta Actualización un vehículo) o directamente en el SDK del controlador:

Java

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);

Kotlin

val reporter = ...

reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)

Cuando las actualizaciones de ubicación están habilitadas, una llamada a setVehicleState se propagará en la próxima actualización de ubicación.

Si marcas un vehículo como ONLINE cuando el seguimiento de ubicación no esté habilitado, en un objeto IllegalStateException. Un vehículo se puede marcar como OFFLINE cuando el seguimiento de ubicación aún no está habilitado o se inhabilitó explícitamente. Esto generará en una actualización inmediata. Llamada a RidesharingVehicleReporter.disableLocationTracking() hará lo siguiente establece el estado del vehículo en OFFLINE.

Ten en cuenta que setVehicleState se devuelve de inmediato y las actualizaciones se realizan en la conversación de actualización de ubicación. De forma similar al manejo de errores de actualizaciones de ubicaciones, las actualizaciones del estado del vehículo se propagan con los recursos StatusListener se establece en DriverContext.