Premiers pas avec le SDK grand public pour Android

Vous pouvez utiliser le SDK grand public pour créer et exécuter une application grand public de base intégrée aux services de backend de la solution On-demand Rides and Deliveries. Vous pouvez créer une application de progression des trajets et des commandes capable d'afficher un trajet actif, de répondre aux mises à jour des trajets et de gérer les erreurs.

Comme le SDK Consumer possède une architecture modulaire, vous pouvez utiliser les parties de l'API que vous souhaitez utiliser pour votre application et les intégrer à vos propres API, services de backend fournis par Fleet Engine et API supplémentaires de Google Maps Platform.

Configuration système minimale requise

L'appareil mobile doit exécuter Android 6.0 (niveau d'API 23) ou une version ultérieure.

Configuration de la compilation et des dépendances

Les versions 1.99.0 et ultérieures du SDK grand public sont disponibles à l'aide du dépôt Maven de Google. La version du dépôt privé précédemment utilisé est obsolète.

Gradle

Ajoutez le code ci-dessous à votre fichier build.gradle :

repositories {
    ...
    google()
}

Maven

Ajoutez le code ci-dessous à votre fichier pom.xml :

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

Configuration du projet

Pour utiliser le SDK grand public pour Android, votre application doit cibler minSdkVersion 23 ou version ultérieure.

Pour exécuter une application créée avec le SDK grand public, les services Google Play doivent être installés sur l'appareil Android.

Configurer votre projet de développement

Pour configurer votre projet de développement et obtenir une clé API pour le projet dans la console Google Cloud:

  1. Créez un projet dans la console Google Cloud ou sélectionnez un projet existant à utiliser avec le SDK Consumer. Attendez quelques minutes que le nouveau projet soit visible dans la console Google Cloud.

  2. Pour que vous puissiez exécuter l'application de démonstration, votre projet doit avoir accès au SDK Maps pour Android. Dans la console Google Cloud, sélectionnez API et services > Bibliothèque, puis recherchez et activez le SDK Maps pour Android.

  3. Obtenez une clé API pour le projet en sélectionnant API et services > Identifiants > Créer des identifiants > Clé API. Pour savoir comment obtenir une clé API, consultez Obtenir une clé API.

Ajouter le SDK grand public à votre application

Le SDK Consumer SDK est disponible via un dépôt Maven privé. Le dépôt inclut les fichiers .pom (Project Object Model) du SDK, ainsi que des documents Javadocs. Pour ajouter le SDK grand public à votre application:

  1. Configurez votre environnement pour accéder au dépôt Maven de l'hôte, comme décrit dans la section précédente.

    Si vous avez déclaré une configuration de gestion centralisée des dépendances dans settings.gradle, désactivez-la comme suit.

    • Supprimez le bloc de code suivant dans settings.gradle:

      import org.gradle.api.initialization.resolve.RepositoriesMode
      dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
              google()
              mavenCentral()
          }
      }
      
  2. Ajoutez la dépendance suivante à votre configuration Gradle ou Maven, en remplaçant l'espace réservé VERSION_NUMBER par la version souhaitée du SDK grand public.

    Gradle

    Ajoutez les éléments suivants à votre build.gradle :

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

    Maven

    Ajoutez les éléments suivants à votre pom.xml :

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
        <artifactId>transportation-consumer</artifactId>
        <version>VERSION_NUMBER</version>
      </dependency>
    </dependencies>
    
  3. Le SDK grand public dépend du SDK Maps. Cette dépendance est configurée de sorte que si la version du SDK Maps n'est pas explicitement définie dans le fichier de configuration de compilation comme celui-ci, lorsqu'une nouvelle version du SDK Maps est publiée, le SDK grand public continue à utiliser la version minimale compatible requise.

    Gradle

    Ajoutez les éléments suivants à votre build.gradle :

    dependencies {
      ...
      implementation 'com.google.android.gms:play-services-maps:18.1.0'
    }
    

    Maven

    Ajoutez les éléments suivants à votre pom.xml :

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
        <version>18.1.0</version>
      </dependency>
    </dependencies>
    

Ajouter la clé API à votre application

Une fois que vous avez ajouté le SDK grand public à votre application, ajoutez la clé API à celle-ci. Vous devez utiliser la clé API du projet que vous avez obtenue lorsque vous avez configuré votre projet de développement.

Cette section explique comment stocker votre clé API afin qu'elle puisse être référencée de manière plus sécurisée par votre application. Vous ne devez pas l'enregistrer dans votre système de contrôle des versions. Il doit être stocké dans le fichier local.properties, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier local.properties, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, vous pouvez utiliser le plug-in Secrets Gradle pour Android.

Pour installer le plug-in et stocker votre clé API :

  1. Ouvrez le fichier build.gradle au niveau racine et ajoutez le code suivant à l'élément dependencies sous 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. Ouvrez le fichier build.gradle au niveau de l'application et ajoutez le code suivant à l'élément plugins.

    Groovy

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

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. Si vous utilisez Android Studio, synchronisez votre projet avec Gradle.

  4. Ouvrez local.properties dans votre répertoire au niveau du projet, puis ajoutez le code suivant. Remplacez YOUR_API_KEY par votre clé API.

    MAPS_API_KEY=YOUR_API_KEY
    
  5. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY et mettez à jour l'attribut android:value comme suit:

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

L'exemple suivant présente un fichier manifeste complet pour une application exemple:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.consumerapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_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>

Inclure les attributions requises dans votre application

Si vous utilisez le SDK grand public dans votre application, vous devez inclure le texte d'attribution et les licences Open Source dans la section des mentions légales de votre application. Il est préférable d'inclure les attributions dans un élément de menu indépendant ou dans un élément de menu About (À propos).

Les informations sur les licences se trouvent dans le fichier "third_party_licenses.txt" du fichier AAR désarchivé.

Pour savoir comment inclure des notifications Open Source, consultez la page https://developers.google.com/android/guides/opensource.

Authentification par SDK client

Le SDK grand public permet l'authentification à l'aide de jetons Web JSON. Un jeton Web JSON (JWT) est un jeton d'accès basé sur JSON qui fournit une ou plusieurs revendications sur un service. Par exemple, un serveur peut générer un jeton avec la revendication "connecté en tant qu'administrateur" et le transmettre à un client. Le client peut ensuite utiliser ce jeton pour prouver qu'il est connecté en tant qu'administrateur.

Le SDK Consumer utilise le jeton Web JSON fourni par l'application pour communiquer avec Fleet Engine. Pour plus d'informations, consultez la page Authentification et autorisation pour parc Engine.

Le jeton d'autorisation doit inclure une revendication tripid:TRIP_ID dans l'en-tête authorization du jeton, où TRIP_ID correspond à l'ID du trajet. Le SDK grand public peut ainsi accéder aux détails du trajet, y compris la position du véhicule, l'itinéraire et l'heure d'arrivée prévue.

Rappels de jeton Web JSON

Le SDK grand public enregistre un rappel de jeton d'autorisation avec l'application lors de l'initialisation. Le SDK appelle l'application afin d'obtenir un jeton pour toutes les requêtes réseau nécessitant une autorisation.

Nous vous recommandons vivement de mettre en cache les jetons d'autorisation et de ne les actualiser que lorsque le délai expiry est écoulé. Les jetons doivent être émis avec un délai d'expiration d'une heure.

Le rappel du jeton d'autorisation spécifie le jeton de service nécessaire au service TripService. Elle fournit également l'élément tripId requis pour le contexte.

L'exemple de code suivant montre comment implémenter un rappel de jeton d'autorisation.

Java

class JsonAuthTokenFactory implements AuthTokenFactory {

  private static final String TOKEN_URL =
      "https://yourauthserver.example/token";

  private static class CachedToken {
    String tokenValue;
    long expiryTimeMs;
    String tripId;
  }

  private CachedToken token;

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  @Override
  public String getToken(AuthTokenContext context) {
    // If there is no existing token or token has expired, go get a new one.
    String tripId = context.getTripId();
    if (tripId == null) {
      throw new RuntimeException("Trip ID is missing from AuthTokenContext");
    }
    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        !tripId.equals(token.tripId)) {
      token = fetchNewToken(tripId);
    }
    return token.tokenValue;
  }

  private static CachedToken fetchNewToken(String tripId) {
    String url = TOKEN_URL + "/" + tripId;
    CachedToken token = new CachedToken();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();

      token.tokenValue = obj.get("ServiceToken").getAsString();
      token.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 5 minutes from that time.
      */
      token.expiryTimeMs -= 5 * 60 * 1000;
    } catch (IOException e) {
      /*
      * It's OK to throw exceptions here. The error listeners will receive the
      * error thrown here.
      */
      throw new RuntimeException("Could not get auth token", e);
    }
    token.tripId = tripId;

    return token;
  }
}

Kotlin

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  override fun getToken(context: AuthTokenContext): String {
    // If there is no existing token or token has expired, go get a new one.
    val tripId = 
      context.getTripId() ?: 
        throw RuntimeException("Trip ID is missing from AuthTokenContext")

    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        tripId != token.tripId) {
      token = fetchNewToken(tripId)
    }

    return token.tokenValue
  }

  class CachedToken(
    var tokenValue: String? = "", 
    var expiryTimeMs: Long = 0,
    var tripId: String? = "",
  )

  private companion object {
    const val TOKEN_URL = "https://yourauthserver.example/token"

    fun fetchNewToken(tripId: String) {
      val url = "$TOKEN_URL/$tripId"
      val token = CachedToken()

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

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

          token.tokenValue = obj.get("ServiceToken").getAsString()
          token.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 5 minutes from that time.
          */
          token.expiryTimeMs -= 5 * 60 * 1000
        }
      } catch (e: IOException) {
        /*
        * It's OK to throw exceptions here. The error listeners will receive the
        * error thrown here.
        */
        throw RuntimeException("Could not get auth token", e)
      }

      token.tripId = tripId

      return token
    }
  }
}

Initialiser l'API

Avant de suivre ces procédures, nous partons du principe que vous avez activé les services appropriés et le SDK client.

Obtenir l'instance ConsumerApi

Pour utiliser le SDK grand public, votre application doit initialiser ConsumerApi de manière asynchrone. L'API est un singleton. La méthode d'initialisation utilise un AuthTokenFactory. La fabrique génère de nouveaux jetons JWT pour l'utilisateur si nécessaire.

providerId correspond à l'ID de projet de votre projet Google Cloud. Consultez le guide de l'utilisateur de Fleet Engine pour en savoir plus sur la création du projet.

Votre application doit implémenter AuthTokenFactory comme décrit dans Consumer SDK Authentication (Authentification par SDK grand public).

Java

Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
    this, "myProviderId", authTokenFactory);

consumerApiTask.addOnSuccessListener(
  consumerApi -> this.consumerApi = consumerApi);

Kotlin

val consumerApiTask =
  ConsumerApi.initialize(this, "myProviderId", authTokenFactory)

consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
  this@YourActivity.consumerApi = consumerApi
}

SDK Maps et moteurs de rendu de cartes

La version 2.x.x du SDK grand public est compatible avec le SDK Maps pour Android 18.1.0 et versions ultérieures. Le tableau ci-dessous récapitule le moteur de rendu par défaut en fonction de la version du SDK Maps et de la compatibilité des deux. Nous vous recommandons d'utiliser le dernier moteur de rendu. Toutefois, si vous devez utiliser l'ancien moteur de rendu, vous pouvez le spécifier explicitement à l'aide de MapsInitializer.initialize().

Version du SDK Maps Compatibilité avec le dernier moteur de rendu Compatible avec l'ancien moteur de rendu Moteur de rendu par défaut
V18.1.0 et versions antérieures Oui Oui Ancien*
V18.2.0 Oui Oui La plus récente

* Lors du déploiement du nouveau moteur de rendu Maps, le dernier moteur de rendu sera utilisé par défaut.

Ajouter le SDK Maps en tant que dépendance

Gradle

Ajoutez les éléments suivants à votre build.gradle :

dependencies {
  //...
  implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}

Maven

Ajoutez les éléments suivants à votre pom.xml :

 <dependencies>
   ...
   <dependency>
     <groupId>com.google.android.gms</groupId>
     <artifactId>play-services-maps</artifactId>
     <version>18.1.0</version>
   </dependency>
 </dependencies>

Initialiser le SDK Maps avant d'initialiser le SDK grand public

Dans votre classe Application ou Activity de démarrage, appelez MapsInitializer.initialize() et attendez le résultat de la requête du moteur de rendu avant d'initialiser le SDK grand public.

java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);
  initViews();

  MapsInitializer.initialize(getApplicationContext(), Renderer.LATEST,
      new OnMapsSdkInitializedCallback() {
        @Override
        public void onMapsSdkInitialized(Renderer renderer) {
          switch (renderer) {
            case LATEST:
              Log.i("maps_renderer", "LATEST renderer");
              break;
            case LEGACY:
              Log.i("maps_renderer", "LEGACY renderer");
              break;
          }

          initializeConsumerSdk();
        }
      });
}

Kotlin

fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)
  initViews()

  MapsInitializer.initialize(
    getApplicationContext(), Renderer.LATEST,
    object : OnMapsSdkInitializedCallback() {
      fun onMapsSdkInitialized(renderer: Renderer?) {
        when (renderer) {
          LATEST -> Log.i("maps_renderer", "LATEST renderer")
          LEGACY -> Log.i("maps_renderer", "LEGACY renderer")
        }
        initializeConsumerSdk()
      }
    })
  }

Créer l'interface utilisateur

Vous pouvez utiliser ConsumerMapFragment ou ConsumerMapView pour créer l'interface utilisateur de votre application. ConsumerMapFragment vous permet de définir votre carte à l'aide d'un Fragment, tandis que ConsumerMapView vous permet d'utiliser un View. La fonctionnalité de partage de course est la même dans ConsumerMapView et ConsumerMapFragment. Vous pouvez donc en choisir une selon que View ou Fragment conviennent mieux à votre application.

Ajouter la prise en charge de l'API 19 (KitKat) et des drawables vectoriels

Si la conception de votre application nécessite la compatibilité avec les appareils utilisant l'API 19 (KitKat) et les drawables vectoriels, ajoutez le code suivant à votre activité. Ce code étend AppCompatActivity afin d'utiliser les drawables vectoriels dans le SDK grand public.

Java

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

Ajouter la vue ou le fragment de carte

Vous créez la carte pour afficher le partage de parcours dans un fragment Android ou une vue, que vous définissez dans le fichier XML de mise en page de votre application (situé dans /res/layout). Le fragment (ou la vue) permet ensuite d'accéder à la carte de partage de parcours, que votre application peut consulter et modifier. La carte fournit également un handle vers le ConsumerController, ce qui permet à votre application de contrôler et de personnaliser l'expérience de partage du parcours.

Carte et contrôleur de partage de parcours

Vous définissez la carte de partage du parcours soit en tant que fragment (à l'aide de ConsumerMapFragment), soit en tant que vue (avec ConsumerMapView), comme illustré dans l'exemple de code suivant. Votre méthode onCreate() doit ensuite appeler getConsumerGoogleMapAsync(callback), qui renvoie ConsumerGoogleMap de manière asynchrone dans le rappel. Vous utilisez ensuite ConsumerGoogleMap pour afficher le partage du parcours. Il peut être mis à jour si nécessaire par votre application.

ConsumerMapFragment

Vous définissez le fragment dans le fichier XML de mise en page de votre application, comme illustré dans l'exemple de code suivant.

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

L'appel à getConsumerGoogleMapAsync() doit provenir de la méthode onCreate().

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

    // Find the ConsumerMapFragment.
    ConsumerMapFragment consumerMapFragment =
        (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

    // Initiate the callback that returns the map.
    if (consumerMapFragment != null) {
      consumerMapFragment.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          });
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    // Find the ConsumerMapFragment.
    val consumerMapFragment =
      fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

    consumerMapFragment.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      }
    )
  }
}
ConsumerMapView

La vue peut être utilisée dans un fragment ou dans une activité, comme défini dans votre fichier XML.

<com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/consumer_map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

L'appel à getConsumerGoogleMapAsync() doit provenir de onCreate(). En plus du paramètre de rappel, il nécessite l'activité ou le fragment qui le contiennent, ainsi que GoogleMapOptions (qui peut être nul) contenant les attributs de configuration pour MapView. La classe de base de l'activité ou du fragment doit être respectivement une FragmentActivity ou une Fragment prise en charge, car elle donne accès à son cycle de vie.

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

L'élément MapView d'un fragment est le même que dans l'exemple ci-dessus pour MapView dans une activité, sauf que le fragment gonfle la mise en page qui inclut MapView dans la méthode onCreateView() du fragment.

Java

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

Kotlin

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

Réglage du zoom de l'appareil photo pour faire la mise au point sur un trajet

Le bouton "Ma position" par défaut intégré au SDK Maps centre l'appareil photo sur la position de l'appareil.

Si une session de partage de parcours est en cours, vous pouvez centrer la caméra pour qu'elle se concentre sur le trajet plutôt que sur la position de l'appareil.

Solution intégrée au SDK grand public pour Android: AutoCamera

Pour vous permettre de vous concentrer sur le parcours plutôt que sur la position de l'appareil, le SDK grand public fournit une fonctionnalité AutoCamera activée par défaut. La caméra zoome pour se concentrer sur l'itinéraire de partage du trajet et le point de cheminement du trajet suivant.

AutoCamera

Personnaliser le comportement de l'appareil photo

Si vous avez besoin de mieux contrôler le comportement de la caméra, vous pouvez désactiver ou activer la caméra automatique à l'aide de ConsumerController.setAutoCameraEnabled().

ConsumerController.getCameraUpdate() renvoie les limites recommandées pour l'appareil photo à ce moment précis. Vous pouvez ensuite fournir cet CameraUpdate en tant qu'argument à GoogleMap.moveCamera() ou GoogleMap.animateCamera().

Accédez au partage de course et aux cartes

Pour prendre en charge le partage de course et les interactions avec la carte dans votre application, vous devez accéder à ConsumerGoogleMap et ConsumerController. ConsumerMapFragment et ConsumerMapView renvoient tous deux de manière asynchrone ConsumerGoogleMap dans ConsumerMapReadyCallback. ConsumerGoogleMap renvoie ConsumerController à partir de getConsumerController(). Vous pouvez accéder à ConsumerGoogleMap et ConsumerController comme suit.

Java

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

Kotlin

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

ConsumerGoogleMap

ConsumerGoogleMap est une classe wrapper pour la classe GoogleMap. Elle permet à votre application d'interagir avec la carte à l'aide d'une API équivalente à GoogleMap. L'utilisation de la carte grand public permet à votre application et à votre service de covoiturage d'interagir facilement avec la même carte GoogleMap sous-jacente. Par exemple, GoogleMap n'autorise qu'un seul enregistrement de rappel, mais ConsumerGoogleMap accepte les rappels à double enregistrement. Ces rappels permettent à votre application et à votre service de covoiturage d'enregistrer des rappels appelés de manière séquentielle.

ConsumerController

ConsumerController permet d'accéder à des fonctionnalités de partage de course, par exemple pour surveiller les trajets, contrôler leur état et définir des lieux.

Configurer le partage du parcours

Une fois que le backend a mis en correspondance un consommateur et un véhicule, utilisez JourneySharingSession pour démarrer l'interface utilisateur de partage du parcours. Le partage du trajet affiche l'emplacement et l'itinéraire du véhicule correspondant. Après avoir implémenté le SDK dans votre application, vous pouvez ajouter une fonctionnalité permettant de surveiller les trajets, d'écouter les mises à jour et de gérer les erreurs. Les procédures suivantes supposent que les services de backend sont en place et que vos services de mise en correspondance des consommateurs avec les véhicules sont opérationnels.

  1. Enregistrez un écouteur sur un objet TripModel pour obtenir des détails sur le trajet, tels que l'heure d'arrivée estimée (ETA) et la distance que le véhicule doit parcourir avant l'arrivée.

    Java

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
    String tripName = ...;
    TripModelManager tripModelManager = consumerApi.getTripModelManager();
    TripModel tripModel = tripModelManager.getTripModel(tripName);
    
    // Create a JourneySharingSession instance based on the TripModel.
    JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
    
    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session);
    
    // Register for trip update events.
    tripModel.registerTripCallback(new TripModelCallback() {
      @Override
      public void onTripETAToNextWaypointUpdated(
          TripInfo tripInfo, @Nullable Long timestampMillis) {
        // ...
      }
    
      @Override
      public void onTripActiveRouteRemainingDistanceUpdated(
          TripInfo tripInfo, @Nullable Integer distanceMeters) {
        // ...
      }
    
      // ...
    });
    

    Kotlin

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
    val tripName = "tripName"
    val tripModelManager = consumerApi.getTripModelManager()
    val tripModel = tripModelManager.getTripModel(tripName)
    
    // Create a JourneySharingSession instance based on the TripModel.
    val session = JourneySharingSession.createInstance(tripModel)
    
    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session)
    
    // Register for trip update events.
    tripModel.registerTripCallback(
      object : TripModelCallback() {
        override fun onTripETAToNextWaypointUpdated(
          tripInfo: TripInfo,
          timestampMillis: Long?,
        ) {
          // ...
        }
    
        override fun onTripActiveRouteRemainingDistanceUpdated(
          tripInfo: TripInfo,
          distanceMeters: Int?,
        ) {
          // ...
        }
    
      // ...
    })
    
  2. Configurez votre trajet avec TripModelOptions.

    Java

    // Set refresh interval to 2 seconds.
    TripModelOptions tripOptions =
        TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
    tripModel.setTripModelOptions(tripOptions);
    

    Kotlin

    // Set refresh interval to 2 seconds.
    val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
    tripModel.setTripModelOptions(tripOptions)
    

Arrêter le partage du trajet

Veillez à arrêter le partage de parcours lorsqu'il n'est plus nécessaire, par exemple lorsque l'activité hôte est détruite. L'arrêt du partage du parcours entraîne également l'arrêt des requêtes réseau adressées à Fleet Engine et la prévention des fuites de mémoire.

L'exemple de code suivant montre comment arrêter le partage du parcours.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Gérer les erreurs de trajet

La méthode onTripRefreshError signale les erreurs qui se produisent lors de la surveillance de trajet. Le mappage des erreurs du SDK client suit les mêmes consignes HTTP/RPC que celles établies pour Google Cloud Platform. Voici quelques erreurs courantes lors de la surveillance des trajets:

HTTP RPC Description
400 INVALID_ARGUMENT Le client a spécifié un nom de trajet non valide. Le nom du trajet doit respecter le format providers/{provider_id}/trips/{trip_id}. provider_id doit être l'ID du projet Cloud appartenant au fournisseur de services.
401 UNAUTHENTICATED Requête non authentifiée en raison d'un jeton JWT non valide. Cette erreur se produit si le jeton JWT est signé sans ID de trajet ou si le jeton JWT a expiré.
403 PERMISSION_DENIED Le client ne dispose pas des autorisations nécessaires. Cette erreur se produit si le jeton JWT n'est pas valide, si le client ne dispose pas des autorisations nécessaires ou si l'API n'est pas activée pour le projet client. Le jeton JWT est peut-être manquant ou il est signé avec un ID de trajet qui ne correspond pas à l'ID de trajet demandé.
429 RESOURCE_EXHAUSTED Le quota de ressources est égal à zéro ou le débit du trafic dépasse la limite.
503 UNAVAILABLE Service indisponible. Généralement, le serveur est en panne.
504 DEADLINE_EXCEEDED Délai de requête dépassé. Cela ne se produit que si l'appelant définit un délai inférieur au délai par défaut de la méthode (c'est-à-dire que le délai demandé ne suffit pas pour que le serveur traite la requête) et que la requête ne s'est pas terminée dans le délai.

Pour en savoir plus, consultez la page Gestion des erreurs du SDK grand public.