Ce guide explique les différences entre les deux services bibliothèque de compatibilité et la nouvelle version autonome 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 afin d'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 recommande de passer de la bibliothèque de compatibilité à la nouvelle SDK Places pour Android dès que possible.
Modifications apportées
Voici les principaux domaines de changement:
- La nouvelle version du SDK Places pour Android est distribuée en tant que bibliothèque cliente statique. Avant janvier 2019, le SDK Places pour Android a été rendue disponible via les services Google Play. Depuis, une application Places bibliothèque de compatibilité 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 compatibles avec les méthodes qui renvoient des lieux. plus de détails. Vous pouvez utiliser des masques de champ pour spécifier les types de données de lieu à retour.
- 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.
- L'outil de sélection de lieux 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 autonome pour Android,
Google a fourni une bibliothèque de compatibilité pour faciliter la migration
de la version hors service des services Google Play du SDK Places pour Android ;
(com.google.android.gms:play-services-places
).
Cette bibliothèque de compatibilité a été fournie temporairement pour rediriger et traduire Appels d'API ciblant 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 SDK autonome. Pour chaque version du SDK Places pour Android qui a été publiée de la version 1.0 à la version 2.6.0, une version correspondante de la bibliothèque de compatibilité Places a été publiée pour fournir des de Google Cloud.
Figer et abandonner 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 du Bibliothèque de compatibilité Places. Le seul moyen d'accéder aux fonctionnalités et aux corrections de bugs dans Places Le SDK pour Android version 2.6.0 ultérieure utilisera 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 ultérieures à la version 2.6.0. Si vous utilisez actuellement la bibliothèque de compatibilité, suivez les étapes ci-dessous dans Section Installer le SDK Places pour Android pour effectuer la migration au SDK Places pour Android.
Installer la bibliothèque cliente
La nouvelle version du SDK Places pour Android est distribuée bibliothèque cliente statique.
Utilisez Maven pour ajouter la classe SDK Places pour Android vers 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'
Utilisez cette ligne pour passer au SDK Places pour Android:
implementation 'com.google.android.libraries.places:places:3.3.0'
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'
Utilisez cette ligne pour passer au SDK Places pour Android:
implementation 'com.google.android.libraries.places:places:3.3.0'
Synchronisez votre projet Gradle.
Définissez le paramètre
minSdkVersion
de votre projet d'application sur 16 ou une valeur supérieure.Mettre à jour la mention "Fourni par Google" éléments:
@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
Créez votre application. Si vous constatez des erreurs de compilation en raison de votre conversion vers le SDK Places pour Android, consultez les sections ci-dessous pour en savoir plus pour résoudre ces erreurs.
Initialiser le nouveau client du SDK Places
Initialisez le nouveau client du SDK Places comme illustré 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 de limite de RPS a été modifié. Les erreurs de limite de RPS
renvoyé via PlaceStatusCodes.OVER_QUERY_LIMIT
. Il n'y a plus de limites de RPJ.
Les codes d'état suivants ont été ajoutés:
REQUEST_DENIED
: la requête 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 de clé incorrectes.
INVALID_REQUEST
: la requête n'est pas valide en raison d'un élément 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 inclut de nouveaux qui ont été conçues dans un souci de cohérence. Toutes les nouvelles méthodes respecter 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 les client standard.
- Les objets de requête ont désormais des compilateurs. les paramètres requis sont transmis en tant que requêtes paramètres du compilateur.
- Les tampons ne sont plus utilisés.
Cette section présente les nouvelles méthodes et vous montre leur fonctionnement.
Récupérer un lieu par son ID
Utiliser fetchPlace()
pour obtenir des informations
sur un lieu en particulier. fetchPlace()
fonctionne de la même manière que
getPlaceById()
Pour extraire un lieu, procédez comme suit:
Appelez
fetchPlace()
en transmettant un objetFetchPlaceRequest
spécifiant un lieu. ID et liste de champs spécifiant 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.NAME); // Construct a request object, passing the place ID and fields array. FetchPlaceRequest request = FetchPlaceRequest.builder(placeId, placeFields) .build();
Appelez
addOnSuccessListener()
pour gérerFetchPlaceResponse
. Une seulePlace
résultat 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
Utiliser fetchPhoto()
pour obtenir une photo de lieu. fetchPhoto()
renvoie les photos d'un lieu. Le modèle
de demander une photo
a été simplifiée. Vous pouvez désormais demander PhotoMetadata
directement depuis l'objet Place
; une demande distincte n'est plus nécessaire.
La largeur ou la hauteur des photos ne doivent pas dépasser 1 600 pixels. fetchPhoto()
fonctions
comme pour getPhoto()
.
Pour récupérer des photos de lieux, procédez comme suit:
Planifiez un appel vers
fetchPlace()
. N'oubliez pas d'inclure lePHOTO_METADATAS
dans votre requête:List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);
Obtenez un objet Place (cet exemple utilise
fetchPlace()
, mais vous pouvez aussi utiliserfindCurrentPlace()
):FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
Ajoutez un
OnSuccessListener
pour obtenir les métadonnées de la photo à partir du résultatPlace
dansFetchPlaceResponse
, puis utilisez les métadonnées de photo obtenues 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
Utiliser findCurrentPlace()
pour trouver la position actuelle
de l'appareil de l'utilisateur. findCurrentPlace()
Renvoie une liste de PlaceLikelihood
indiquant les endroits où l'appareil de l'utilisateur
le plus de chances
d’être localisé. 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 le
ACCESS_FINE_LOCATION
et AutorisationsACCESS_WIFI_STATE
. L'utilisateur doit autoriser l'accès la position actuelle de l'appareil. Voir la section Demander une application Autorisations pour plus de détails.Créer un
FindCurrentPlaceRequest
, y compris une liste de types de données de lieu à retour.// Use fields to define the data types to return. List<Place.Field> placeFields = Arrays.asList(Place.Field.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 autorisé l'utilisation de 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(); }
Rechercher des prédictions de saisie semi-automatique
Utiliser findAutocompletePredictions()
pour renvoyer des prédictions de lieu 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 un 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 requête, et se termine lorsqu'il sélectionne un lieu. Chaque session peut avoir plusieurs puis sélectionner un lieu. Une fois la session terminée, 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 lieux. à renvoyer avec chaque requête. Cela vous permet de ne demander (et payer) les données que vous utiliserez réellement.
Pour spécifier les types de données à renvoyer, transmettez un tableau de Place.Field
s dans votre
FetchPlaceRequest
, comme illustré dans l'exemple suivant:
// Include address, ID, and phone number.
List<Place.Field> placeFields = Arrays.asList(Place.Field.ADDRESS,
Place.Field.ID,
Place.Field.PHONE_NUMBER);
Vous pouvez utiliser un ou plusieurs des champs suivants:
Place.Field.ADDRESS
Place.Field.ID
Place.Field.LAT_LNG
Place.Field.NAME
Place.Field.OPENING_HOURS
Place.Field.PHONE_NUMBER
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRICE_LEVEL
Place.Field.RATING
Place.Field.TYPES
Place.Field.USER_RATINGS_TOTAL
Place.Field.VIEWPORT
Place.Field.WEBSITE_URI
En savoir plus sur les SKU Places Data
Mises à jour du sélecteur de lieu et d'Autocomplete
Cette section explique les modifications apportées aux widgets Places (Place Picker et de saisie semi-automatique).
Saisie semi-automatique programmatique
Les modifications suivantes ont été apportées à la saisie semi-automatique:
PlaceAutocomplete
a été renomméAutocomplete
.PlaceAutocomplete.getPlace
a été renomméAutocomplete.getPlaceFromIntent
.PlaceAutocomplete.getStatus
a été renomméAutocomplete.getStatusFromIntent
.
- Changement de nom :
PlaceAutocomplete.RESULT_ERROR
devientAutocompleteActivity.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ée le 29 janvier 2019. Elle était éteinte depuis le 29 juillet 2019. L'utilisation continue entraînera un message d'erreur. Le nouveau SDK n'est pas compatible avec Place Picker.
Widgets de saisie semi-automatique
Les widgets de saisie semi-automatique ont été mis à jour:
- Le préfixe
Place
a été supprimé de toutes les classes. - Ajout de la prise en charge des jetons de session. Le widget gère les jetons à votre place automatiquement en arrière-plan.
- Ajout de la prise en charge des masques de champ, qui vous permettent de choisir quels types de lieux données à renvoyer après que l'utilisateur a fait une sélection.
Les sections suivantes expliquent comment ajouter un widget de saisie semi-automatique à votre projet.
Intégrer un AutocompleteFragment
Pour ajouter un fragment de saisie semi-automatique, procédez comme suit:
Ajoutez un fragment à la mise en page XML de votre activité, comme indiqué ci-dessous. à titre d'exemple.
<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
Places
en transmettant le contexte de l'application et votre clé API. - Initialisez
AutocompleteSupportFragment
. - Appelez
setPlaceFields()
pour indiquer les types de données de lieu souhaités à obtenir. - Ajoutez un
PlaceSelectionListener
pour effectuer une action avec le résultat, ainsi que gérer toutes les erreurs qui pourraient se produire.
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.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
- Initialiser
Places
en transmettant le contexte de l'application et votre clé API - Utilisez
Autocomplete.IntentBuilder
pour créer un intent en transmettant l'objet ModePlaceAutocomplete
(plein écran ou superposition). L'intent doit appelerstartActivityForResult
, en transmettant un code de requête qui identifie votre l'intention. - Ignorez le rappel
onActivityResult
pour recevoir le lieu sélectionné.
L'exemple suivant vous montre comment utiliser un intent 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.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ée le 29 janvier 2019. Elle était éteinte depuis le 29 juillet 2019. L'utilisation continue entraînera un message d'erreur. Le nouveau SDK n'est pas compatible avec Place Picker.