Ce guide explique les différences entre la bibliothèque de compatibilité Places et la nouvelle version autonome du SDK Places pour Android. Si vous avez utilisé la bibliothèque de compatibilité Places au lieu de migrer vers la nouvelle version autonome du SDK Places pour Android, ce guide vous explique comment mettre à jour vos projets pour utiliser la nouvelle version du SDK Places pour Android.
Le seul moyen d'accéder aux fonctionnalités et aux corrections de bugs dans le SDK Places pour les versions d'Android supérieures à 2.6.0 sera d'utiliser le SDK Places pour Android. Google vous recommande de passer de la bibliothèque de compatibilité à la nouvelle version du SDK Places pour Android dès que possible.
Erreur : 9005 PLACES_API_RATE_LIMIT_EXCEEDED
Modifications apportées
Voici les principaux domaines concernés par les modifications :
- La nouvelle version du SDK Places pour Android est distribuée sous la forme d'une bibliothèque cliente statique. Avant janvier 2019, le SDK Places pour Android était disponible via les services Google Play. Depuis, une bibliothèque de compatibilité Places a été fournie pour faciliter la transition vers le nouveau SDK Places pour Android.
- Il existe de toutes nouvelles méthodes.
- Les masques de champ sont désormais acceptés pour les méthodes qui renvoient des informations sur les lieux. Vous pouvez utiliser des masques de champ pour spécifier les types de données de lieu à renvoyer.
- Les codes d'état utilisés pour signaler les erreurs ont été améliorés.
- La saisie semi-automatique est désormais compatible avec les jetons de session.
- Le sélecteur de lieu n'est plus disponible.
À propos de la bibliothèque de compatibilité Places
En janvier 2019, avec la sortie de la version 1.0 du SDK Places pour Android autonome, Google a fourni une bibliothèque de compatibilité pour faciliter la migration depuis la version décommissionnée du SDK Places pour Android des services Google Play (com.google.android.gms:play-services-places).
Cette bibliothèque de compatibilité a été fournie temporairement pour rediriger et traduire les appels d'API destinés à la version des services Google Play vers la nouvelle version autonome, jusqu'à ce que les développeurs puissent migrer leur code pour utiliser les nouveaux noms dans le SDK autonome. Pour chaque version du SDK Places pour Android publiée entre la version 1.0 et la version 2.6.0, une version correspondante de la bibliothèque de compatibilité Places a été publiée pour fournir des fonctionnalités équivalentes.
Gel et abandon de la bibliothèque de compatibilité Places
Toutes les versions de la bibliothèque de compatibilité pour le SDK Places pour Android sont obsolètes depuis le 31 mars 2022. La version 2.6.0 est la dernière version de la bibliothèque de compatibilité Places. Le seul moyen d'accéder aux fonctionnalités et aux corrections de bugs dans le SDK Places pour les versions d'Android supérieures à 2.6.0 sera d'utiliser le SDK Places pour Android.
Google vous recommande de migrer vers le SDK Places pour Android afin d'accéder aux nouvelles fonctionnalités et aux corrections de bugs critiques pour les versions supérieures à 2.6.0. Si vous utilisez actuellement la bibliothèque de compatibilité, suivez les étapes de la section Installer le SDK Places pour Android ci-dessous pour migrer vers le SDK Places pour Android.
Installer la bibliothèque cliente
La nouvelle version du SDK Places pour Android est distribuée sous la forme d'une bibliothèque cliente statique.
Utilisez Maven pour ajouter le SDK Places pour Android à votre projet Android Studio :
Si vous utilisez actuellement la bibliothèque de compatibilité Places :
Remplacez la ligne suivante dans la section
dependencies:implementation 'com.google.android.libraries.places:places-compat:X.Y.Z'
Avec cette ligne pour passer au SDK Places pour Android :
implementation("com.google.android.libraries.places:places:4.3.1")
Si vous utilisez actuellement la version des services Play du SDK Places pour Android :
Remplacez la ligne suivante dans la section
dependencies:implementation 'com.google.android.gms:play-services-places:X.Y.Z'
Avec cette ligne pour passer au SDK Places pour Android :
implementation("com.google.android.libraries.places:places:4.3.1")
Synchronisez votre projet Gradle.
Définissez le paramètre
minSdkVersiondu projet de votre application sur 23 ou une version ultérieure.Mettez à jour vos composants "Optimisé par Google" :
@drawable/powered_by_google_light // OLD @drawable/places_powered_by_google_light // NEW @drawable/powered_by_google_dark // OLD @drawable/places_powered_by_google_dark // NEW
Compilez votre application. Si des erreurs de compilation s'affichent en raison de votre conversion au SDK Places pour Android, consultez les sections ci-dessous pour savoir comment les résoudre.
Initialiser le nouveau client SDK Places
Initialisez le nouveau client SDK Places, comme indiqué dans l'exemple suivant :
// Add an import statement for the client library.
import com.google.android.libraries.places.api.Places;
...
// Initialize Places.
Places.initialize(getApplicationContext(), apiKey);
// Create a new Places client instance.
PlacesClient placesClient = Places.createClient(this);
Codes d'état
Le code d'état des erreurs liées à la limite de RPS a changé. Les erreurs de limite de RPS sont désormais renvoyées via PlaceStatusCodes.OVER_QUERY_LIMIT. Il n'y a plus de limites de QPD.
Les codes d'état suivants ont été ajoutés :
REQUEST_DENIED: la demande a été refusée. Les raisons suivantes peuvent expliquer ces différences :- Aucune clé API n'a été fournie.
- Une clé API non valide a été fournie.
- L'API Places n'a pas été activée dans la console Cloud.
- Une clé API a été fournie avec des restrictions incorrectes.
INVALID_REQUEST: la requête n'est pas valide en raison d'un argument manquant ou non valide.NOT_FOUND: aucun résultat n'a été trouvé pour la requête donnée.
Nouvelles méthodes
La nouvelle version du SDK Places pour Android introduit de toutes nouvelles méthodes, conçues pour assurer la cohérence. Toutes les nouvelles méthodes respectent les règles suivantes :
- Les points de terminaison n'utilisent plus le verbe
get. - Les objets de requête et de réponse portent le même nom que la méthode client correspondante.
- Les objets de requête disposent désormais de compilateurs. Les paramètres obligatoires sont transmis en tant que paramètres de compilateur de requête.
- Les tampons ne sont plus utilisés.
Cette section présente les nouvelles méthodes et explique comment elles fonctionnent.
Récupérer un lieu par son ID
Utilisez fetchPlace() pour obtenir des informations sur un lieu spécifique. fetchPlace() fonctionne de la même manière que getPlaceById().
Pour récupérer un lieu, procédez comme suit :
Appelez
fetchPlace()en transmettant un objetFetchPlaceRequestqui spécifie un ID de lieu et une liste de champs qui spécifient les données de lieu à renvoyer.// Define a Place ID. String placeId = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME); // Construct a request object, passing the place ID and fields array. FetchPlaceRequest request = FetchPlaceRequest.builder(placeId, placeFields) .build();Appelez
addOnSuccessListener()pour gérerFetchPlaceResponse. Un seul résultatPlaceest renvoyé.// Add a listener to handle the response. placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { ApiException apiException = (ApiException) exception; int statusCode = apiException.getStatusCode(); // Handle error with given status code. Log.e(TAG, "Place not found: " + exception.getMessage()); } });
Récupérer la photo d'un lieu
Utilisez fetchPhoto() pour obtenir une photo d'un lieu. fetchPhoto() renvoie les photos d'un lieu. Le modèle de demande de photo a été simplifié. Vous pouvez désormais demander PhotoMetadata directement à partir de l'objet Place. Il n'est plus nécessaire d'envoyer une requête distincte.
La largeur ou la hauteur des photos ne doit pas dépasser 1 600 pixels. Les fonctions fetchPhoto() sont semblables à getPhoto().
Pour récupérer des photos de lieux, procédez comme suit :
Configurez un appel vers
fetchPlace(). Veillez à inclure le champPHOTO_METADATASdans votre demande :List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);Obtenez un objet Place (cet exemple utilise
fetchPlace(), mais vous pouvez également utiliserfindCurrentPlace()) :FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();Ajoutez un
OnSuccessListenerpour obtenir les métadonnées de la photo à partir duPlacerésultant dans leFetchPlaceResponse, puis utilisez les métadonnées de la photo résultantes pour obtenir un bitmap et un texte d'attribution :placesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -> { Place place = response.getPlace(); // Get the photo metadata. PhotoMetadata photoMetadata = place.getPhotoMetadatas().get(0); // Get the attribution text. String attributions = photoMetadata.getAttributions(); // Create a FetchPhotoRequest. FetchPhotoRequest photoRequest = FetchPhotoRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build(); placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse) -> { Bitmap bitmap = fetchPhotoResponse.getBitmap(); imageView.setImageBitmap(bitmap); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { ApiException apiException = (ApiException) exception; int statusCode = apiException.getStatusCode(); // Handle error with given status code. Log.e(TAG, "Place not found: " + exception.getMessage()); } }); });
Trouver un lieu à partir de la position de l'utilisateur
Utilisez findCurrentPlace() pour trouver la position actuelle de l'appareil de l'utilisateur. findCurrentPlace() renvoie une liste de PlaceLikelihood indiquant les lieux où l'appareil de l'utilisateur est le plus susceptible de se trouver. findCurrentPlace() fonctionne de la même manière que getCurrentPlace().
Pour obtenir la position actuelle de l'appareil de l'utilisateur, procédez comme suit :
Assurez-vous que votre application demande les autorisations
ACCESS_FINE_LOCATIONetACCESS_WIFI_STATE. L'utilisateur doit autoriser l'accès à la position actuelle de son appareil. Pour en savoir plus, consultez Demander des autorisations pour l'application.Créez un
FindCurrentPlaceRequest, y compris une liste des types de données de lieu à renvoyer.// Use fields to define the data types to return. List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME); // Use the builder to create a FindCurrentPlaceRequest. FindCurrentPlaceRequest request = FindCurrentPlaceRequest.builder(placeFields).build();Appelez findCurrentPlace et gérez la réponse, en vérifiant d'abord que l'utilisateur a accordé l'autorisation d'utiliser la position de son appareil.
// Call findCurrentPlace and handle the response (first check that the user has granted permission). if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { placesClient.findCurrentPlace(request).addOnSuccessListener(((response) -> { for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) { Log.i(TAG, String.format("Place '%s' has likelihood: %f", placeLikelihood.getPlace().getName(), placeLikelihood.getLikelihood())); textView.append(String.format("Place '%s' has likelihood: %f\n", placeLikelihood.getPlace().getName(), placeLikelihood.getLikelihood())); } })).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + apiException.getStatusCode()); } }); } else { // A local method to request required permissions; // See https://developer.android.com/training/permissions/requesting getLocationPermission(); }
Trouver des prédictions de saisie semi-automatique
Utilisez findAutocompletePredictions() pour renvoyer des prédictions de lieux en réponse aux requêtes de recherche des utilisateurs.
findAutocompletePredictions() fonctionne de la même manière que getAutocompletePredictions().
L'exemple suivant vous montre comment appeler findAutocompletePredictions() :
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();
// Create a RectangularBounds object.
RectangularBounds bounds = RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596));
// Use the builder to create a FindAutocompletePredictionsRequest.
FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
.setLocationBias(bounds)
//.setLocationRestriction(bounds)
.setCountry("au")
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.setSessionToken(token)
.setQuery(query)
.build();
placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
Log.i(TAG, prediction.getPlaceId());
Log.i(TAG, prediction.getPrimaryText(null).toString());
}
}).addOnFailureListener((exception) -> {
if (exception instanceof ApiException) {
ApiException apiException = (ApiException) exception;
Log.e(TAG, "Place not found: " + apiException.getStatusCode());
}
});
Jetons de session
Les jetons de session regroupent les phases de requête et de sélection d'une recherche d'utilisateur dans une session distincte à des fins de facturation. Nous vous recommandons d'utiliser des jetons de session pour toutes les sessions de saisie semi-automatique. La session commence lorsque l'utilisateur commence à saisir une requête et se termine lorsqu'il sélectionne un lieu. Chaque session peut comporter plusieurs requêtes, suivies d'une sélection de lieu. Lorsque la session prend fin, le jeton n'est plus valide. Votre application doit générer un nouveau jeton pour chaque session.
Masques de champ
Dans les méthodes qui renvoient des détails sur un lieu, vous devez spécifier les types de données de lieu à renvoyer avec chaque requête. Cela vous permet de ne demander (et de ne payer) que les données que vous utiliserez réellement.
Pour spécifier les types de données à renvoyer, transmettez un tableau de Place.Field dans votre FetchPlaceRequest, comme indiqué dans l'exemple suivant :
// Include address, ID, and phone number.
List<Place.Field> placeFields = Arrays.asList(Place.Field.FORMATTED_ADDRESS,
Place.Field.ID,
Place.Field.INTERNATIONAL_PHONE_NUMBER);
Pour obtenir la liste des champs que vous pouvez utiliser dans un masque de champ, consultez Champs de données sur les lieux (nouveaux) .
En savoir plus sur les SKU Places Data
Mises à jour du sélecteur de lieux et d'Autocomplete
Cette section décrit les modifications apportées aux widgets Places (sélecteur de lieux et saisie semi-automatique).
Saisie semi-automatique programmatique
Les modifications suivantes ont été apportées à la saisie semi-automatique :
PlaceAutocompletea été renomméAutocomplete.PlaceAutocomplete.getPlacea été renomméAutocomplete.getPlaceFromIntent.PlaceAutocomplete.getStatusa été renomméAutocomplete.getStatusFromIntent.
PlaceAutocomplete.RESULT_ERRORest renomméAutocompleteActivity.RESULT_ERROR(la gestion des erreurs pour le fragment de saisie semi-automatique n'a PAS changé).
Sélecteur de lieux
Place Picker a été abandonné le 29 janvier 2019. Elle a été désactivée le 29 juillet 2019 et n'est plus disponible. Si vous continuez à l'utiliser, un message d'erreur s'affichera. Le nouveau SDK n'est pas compatible avec le sélecteur de lieux.
Widgets de saisie semi-automatique
Les widgets de saisie semi-automatique ont été mis à jour :
- Le préfixe
Placea été supprimé de toutes les classes. - Ajout de la prise en charge des jetons de session. Le widget gère automatiquement les jetons pour vous en arrière-plan.
- Ajout de la compatibilité avec les masques de champ, qui vous permettent de choisir les types de données de lieu à renvoyer une fois que l'utilisateur a fait une sélection.
Les sections suivantes vous expliquent comment ajouter un widget de saisie semi-automatique à votre projet.
Intégrer un AutocompleteFragment
Pour ajouter un fragment d'autocomplétion, procédez comme suit :
Ajoutez un fragment à la mise en page XML de votre activité, comme illustré dans l'exemple suivant.
<fragment android:id="@+id/autocomplete_fragment" android:layout_width="match_parent" android:layout_height="wrap_content" android:name= "com.google.android.libraries.places.widget.AutocompleteSupportFragment" />Pour ajouter le widget de saisie semi-automatique à l'activité, procédez comme suit :
- Initialisez
Placesen transmettant le contexte de l'application et votre clé API. - Initialisez le
AutocompleteSupportFragment. - Appelez
setPlaceFields()pour indiquer les types de données de lieu que vous souhaitez obtenir. - Ajoutez un
PlaceSelectionListenerpour faire quelque chose avec le résultat et gérer les éventuelles erreurs.
L'exemple suivant montre comment ajouter un widget de saisie semi-automatique à une activité :
/** * Initialize Places. For simplicity, the API key is hard-coded. In a production * environment we recommend using a secure mechanism to manage API keys. */ if (!Places.isInitialized()) { Places.initialize(getApplicationContext(), "YOUR_API_KEY"); } // Initialize the AutocompleteSupportFragment. AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment) getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment); autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME)); autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() { @Override public void onPlaceSelected(Place place) { // TODO: Get info about the selected place. Log.i(TAG, "Place: " + place.getName() + ", " + place.getId()); } @Override public void onError(Status status) { // TODO: Handle the error. Log.i(TAG, "An error occurred: " + status); } });- Initialisez
Utiliser un intent pour lancer l'activité de saisie semi-automatique
- Initialisez
Placesen transmettant le contexte de l'application et votre clé API. - Utilisez
Autocomplete.IntentBuilderpour créer un intent, en transmettant le modePlaceAutocompletesouhaité (plein écran ou superposition). L'intent doit appelerstartActivityForResulten transmettant un code de requête qui identifie votre intent. - Remplacez le rappel
onActivityResultpour recevoir le lieu sélectionné.
L'exemple suivant montre comment utiliser une intention pour lancer la saisie semi-automatique, puis gérer le résultat :
/**
* Initialize Places. For simplicity, the API key is hard-coded. In a production
* environment we recommend using a secure mechanism to manage API keys.
*/
if (!Places.isInitialized()) {
Places.initialize(getApplicationContext(), "YOUR_API_KEY");
}
...
// Set the fields to specify which types of place data to return.
List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);
// Start the autocomplete intent.
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.build(this);
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);
...
/**
* Override the activity's onActivityResult(), check the request code, and
* do something with the returned place data (in this example its place name and place ID).
*/
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
if (resultCode == RESULT_OK) {
Place place = Autocomplete.getPlaceFromIntent(data);
Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
} else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
// TODO: Handle the error.
Status status = Autocomplete.getStatusFromIntent(data);
Log.i(TAG, status.getStatusMessage());
} else if (resultCode == RESULT_CANCELED) {
// The user canceled the operation.
}
}
}
Place Picker n'est plus disponible
Place Picker a été abandonné le 29 janvier 2019. Elle a été désactivée le 29 juillet 2019 et n'est plus disponible. Si vous continuez à l'utiliser, un message d'erreur s'affichera. Le nouveau SDK n'est pas compatible avec le sélecteur de lieux.