In diesem Leitfaden werden die Unterschiede zwischen der Places-Kompatibilitätsbibliothek und der neuen eigenständigen Version des Places SDK for Android erläutert. Wenn Sie bisher die Places-Kompatibilitätsbibliothek verwendet haben, statt zur neuen eigenständigen Version des Places SDK for Android zu migrieren, erfahren Sie in diesem Leitfaden, wie Sie Ihre Projekte auf die neue Version des Places SDK for Android aktualisieren.
Nach Version 2.6.0 des Places SDK for Android kann nur noch direkt über das SDK auf Funktionen und Fehlerkorrekturen zugegriffen werden. Google empfiehlt, so schnell wie möglich ein Update von der Kompatibilitätsbibliothek auf die neue Version des Places SDK for Android durchzuführen.
Was hat sich geändert?
Die wichtigsten Änderungen sind:
- Die neue Version des Places SDK for Android wird als statische Clientbibliothek bereitgestellt. Vor Januar 2019 wurde das Places SDK for Android über Google Play-Dienste zur Verfügung gestellt. Seitdem wurde eine Places-Kompatibilitätsbibliothek zur Verfügung gestellt, um die Umstellung auf das neue Places SDK for Android zu erleichtern.
- Es gibt ganz neue Methoden.
- Feldmasken werden jetzt für Methoden unterstützt, die Ortsdetails zurückgeben. Mit Feldmasken können Sie angeben, welche Arten von Ortsdaten zurückgegeben werden sollen.
- Die Statuscodes zum Melden von Fehlern wurden verbessert.
- Die automatische Vervollständigung unterstützt jetzt Sitzungstokens.
- Die Ortsauswahl ist nicht mehr verfügbar.
Places-Kompatibilitätsbibliothek
Im Januar 2019 hat Google mit der Veröffentlichung von Version 1.0 des eigenständigen Places SDK for Android eine Kompatibilitätsbibliothek zur Unterstützung der Migration von der außer Betrieb genommenen Version des Places SDK for Android (com.google.android.gms:play-services-places
) zur Verfügung gestellt.
Diese Kompatibilitätsbibliothek wurde vorübergehend zur Verfügung gestellt, um API-Aufrufe für die Version der Google Play-Dienste in die neue eigenständige Version weiterzuleiten, bis Entwickler ihren Code auf die neuen Namen im eigenständigen SDK umstellen konnten. Für jede Version des Places SDK for Android, die von Version 1.0 bis Version 2.6.0 veröffentlicht wurde, wurde eine entsprechende Version der Places-Kompatibilitätsbibliothek veröffentlicht, die gleichwertige Funktionen bietet.
Places-Kompatibilitätsbibliothek einfrieren und einstellen
Alle Versionen der Kompatibilitätsbibliothek für das Places SDK for Android wurden am 31. März 2022 eingestellt. Version 2.6.0 ist die letzte Version der Places-Kompatibilitätsbibliothek. Ab Version 2.6.0 des Places SDK for Android kann nur noch über das Places SDK for Android auf Funktionen und Fehlerkorrekturen zugegriffen werden.
Google empfiehlt die Migration zum Places SDK for Android, um neue Funktionen und wichtige Fehlerkorrekturen für Releases nach Version 2.6.0 zu erhalten. Wenn Sie derzeit die Kompatibilitätsbibliothek verwenden, führen Sie die Schritte unten im Abschnitt Places SDK for Android installieren aus, um zum Places SDK for Android zu migrieren.
Clientbibliothek installieren
Die neue Version des Places SDK for Android wird als statische Clientbibliothek bereitgestellt.
Verwenden Sie Maven, um Ihrem Android Studio-Projekt das Places SDK for Android hinzuzufügen:
Wenn Sie derzeit die Places-Kompatibilitätsbibliothek verwenden:
Ersetzen Sie die folgende Zeile im Abschnitt
dependencies
:implementation 'com.google.android.libraries.places:places-compat:X.Y.Z'
Mit dieser Zeile können Sie zum Places SDK for Android wechseln:
implementation 'com.google.android.libraries.places:places:3.3.0'
Wenn Sie derzeit die Play-Dienste-Version des Places SDK for Android verwenden:
Ersetzen Sie die folgende Zeile im Abschnitt
dependencies
:implementation 'com.google.android.gms:play-services-places:X.Y.Z'
Mit dieser Zeile können Sie zum Places SDK for Android wechseln:
implementation 'com.google.android.libraries.places:places:3.3.0'
Synchronisiere dein Gradle-Projekt.
Legen Sie
minSdkVersion
für Ihr Anwendungsprojekt auf 16 oder höher fest.Assets mit dem Zusatz „Powered by Google“ aktualisieren:
@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
Erstellen Sie Ihre App. Falls bei der Konvertierung in das Places SDK for Android Build-Fehler auftreten, finden Sie in den folgenden Abschnitten Informationen zum Beheben dieser Fehler.
Neuen Places SDK-Client initialisieren
Initialisieren Sie den neuen Places SDK-Client wie im folgenden Beispiel gezeigt:
// 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);
Statuscodes
Der Statuscode für die Anzahl der Abfragen pro Sekunde hat sich geändert. Fehler in Bezug auf die maximale Anzahl von Abfragen pro Sekunde werden jetzt über PlaceStatusCodes.OVER_QUERY_LIMIT
zurückgegeben. Es gibt keine Limits für die QPD mehr.
Die folgenden Statuscodes wurden hinzugefügt:
REQUEST_DENIED
: Die Anfrage wurde abgelehnt. Mögliche Gründe sind z. B. folgende:- Es wurde kein API-Schlüssel angegeben.
- Es wurde ein ungültiger API-Schlüssel angegeben.
- Die Places API wurde in der Cloud Console nicht aktiviert.
- Es wurde ein API-Schlüssel mit falschen Schlüsseleinschränkungen angegeben.
INVALID_REQUEST
: Die Anfrage ist aufgrund eines fehlenden oder ungültigen Arguments ungültig.NOT_FOUND
: Für die angegebene Anfrage wurde kein Ergebnis gefunden.
Neue Methoden
Mit der neuen Version des Places SDK for Android werden komplett neue Methoden eingeführt, die auf Konsistenz ausgelegt sind. Alle neuen Methoden entsprechen den folgenden Anforderungen:
- Endpunkte verwenden nicht mehr das Verb
get
. - Anfrage- und Antwortobjekte haben denselben Namen wie die entsprechende Clientmethode.
- Anfrageobjekte haben jetzt Builder. Erforderliche Parameter werden als Parameter des Anfrage-Builders übergeben.
- Puffer werden nicht mehr verwendet.
In diesem Abschnitt werden die neuen Methoden vorgestellt und ihre Funktionsweise erläutert.
Ort über die ID abrufen
Verwenden Sie fetchPlace()
, um Details zu einem bestimmten Ort abzurufen. fetchPlace()
funktioniert ähnlich wie getPlaceById()
.
So rufen Sie einen Ort ab:
Rufen Sie
fetchPlace()
auf und übergeben Sie einFetchPlaceRequest
-Objekt, in dem eine Orts-ID und eine Liste von Feldern angegeben werden, mit denen die zurückzugebenden Ortsdaten angegeben werden.// 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();
Rufen Sie
addOnSuccessListener()
auf, um dieFetchPlaceResponse
zu verarbeiten. Es wird ein einzelnesPlace
-Ergebnis zurückgegeben.// 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()); } });
Foto eines Ortes abrufen
Verwenden Sie fetchPhoto()
, um ein Foto von einem Ort abzurufen. fetchPhoto()
gibt Fotos für einen Ort zurück. Das Muster zum Anfordern eines Fotos wurde vereinfacht. Sie können PhotoMetadata
jetzt direkt vom Place
-Objekt anfordern. Eine separate Anfrage ist nicht mehr erforderlich.
Die maximale Breite oder Höhe von Fotos darf maximal 1.600 Pixel betragen. fetchPhoto()
funktioniert ähnlich wie getPhoto()
.
So rufen Sie Fotos von Orten ab:
Vereinbaren Sie einen Anruf bei
fetchPlace()
. Achten Sie darauf, in Ihrer Anfrage das FeldPHOTO_METADATAS
anzugeben:List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);
Rufen Sie ein „Place“-Objekt ab (in diesem Beispiel wird
fetchPlace()
verwendet, Sie können aber auchfindCurrentPlace()
verwenden):FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
Füge ein
OnSuccessListener
hinzu, um die Fotometadaten aus dem resultierendenPlace
imFetchPlaceResponse
abzurufen. Verwende dann die resultierenden Fotometadaten, um eine Bitmap und einen Quellenangabentext zu erhalten: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()); } }); });
Ort am Standort des Nutzers suchen
Mit findCurrentPlace()
können Sie den aktuellen Standort des Geräts des Nutzers ermitteln. findCurrentPlace()
gibt eine Liste von PlaceLikelihood
s zurück, die Orte angibt, an denen sich das Gerät des Nutzers am wahrscheinlichsten befindet. findCurrentPlace()
funktioniert ähnlich wie getCurrentPlace()
.
So ermitteln Sie den aktuellen Standort des Nutzergeräts:
Ihre App muss die Berechtigungen
ACCESS_FINE_LOCATION
undACCESS_WIFI_STATE
anfordern. Der Nutzer muss die Berechtigung erteilen, auf seinen aktuellen Gerätestandort zuzugreifen. Weitere Informationen finden Sie unter App-Berechtigungen anfordern.Erstellen Sie eine
FindCurrentPlaceRequest
, einschließlich einer Liste der Ortsdatentypen, die zurückgegeben werden sollen.// 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();
Rufe findCurrentPlace auf und verarbeite die Antwort. Prüfe zuerst, ob der Nutzer die Berechtigung zur Verwendung seines Gerätestandorts erteilt hat.
// 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(); }
Automatisch vervollständigte Suchanfragen suchen
Verwenden Sie findAutocompletePredictions()
, um als Antwort auf Suchanfragen von Nutzern Ortsvorschläge zurückzugeben.
findAutocompletePredictions()
funktioniert ähnlich wie getAutocompletePredictions()
.
Hier sehen Sie, wie findAutocompletePredictions()
aufgerufen wird:
// 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());
}
});
Sitzungstokens
Sitzungstokens fassen die Abfrage- und Auswahlphasen einer Nutzersuche zu Abrechnungszwecken in einer separaten Sitzung zusammen. Wir empfehlen, Sitzungstokens für alle Sitzungen zu verwenden, bei denen eine automatische Vervollständigung erfolgt. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen enthalten, gefolgt von einer Ortsauswahl. Nach Abschluss einer Sitzung ist das Token nicht mehr gültig. Ihre App muss für jede Sitzung ein neues Token generieren.
Feldmasken
In Methoden, die Ortsdetails zurückgeben, müssen Sie angeben, welche Arten von Ortsdaten bei jeder Anfrage zurückgegeben werden sollen. So können Sie nur Daten anfordern (und bezahlen), die Sie auch tatsächlich nutzen.
Übergeben Sie ein Array von Place.Field
-Werten in Ihrem FetchPlaceRequest
, um anzugeben, welche Datentypen zurückgegeben werden sollen, wie im folgenden Beispiel gezeigt:
// Include address, ID, and phone number.
List<Place.Field> placeFields = Arrays.asList(Place.Field.ADDRESS,
Place.Field.ID,
Place.Field.PHONE_NUMBER);
Sie können eines oder mehrere der folgenden Felder verwenden:
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
Weitere Informationen zu Places-Daten-SKUs
Updates für Place Picker und automatische Vervollständigung
In diesem Abschnitt werden die Änderungen an den Places-Widgets (Place Picker und Autocomplete) erläutert.
Programmatische automatische Vervollständigung
Bei der automatischen Vervollständigung wurden folgende Änderungen vorgenommen:
PlaceAutocomplete
wurde inAutocomplete
umbenannt.PlaceAutocomplete.getPlace
wurde inAutocomplete.getPlaceFromIntent
umbenannt.PlaceAutocomplete.getStatus
wurde inAutocomplete.getStatusFromIntent
umbenannt.
PlaceAutocomplete.RESULT_ERROR
wird inAutocompleteActivity.RESULT_ERROR
umbenannt (die Fehlerbehandlung für das Fragment für die automatische Vervollständigung hat sich NICHT geändert).
Ortsauswahl
Die Ortsauswahl wurde am 29. Januar 2019 eingestellt. Sie wurde am 29. Juli 2019 deaktiviert und ist nicht mehr verfügbar. Die weitere Verwendung führt zu einer Fehlermeldung. Das neue SDK unterstützt die Ortsauswahl nicht.
Widgets für die automatische Vervollständigung
Die Widgets für die automatische Vervollständigung wurden aktualisiert:
- Das Präfix
Place
wurde aus allen Klassen entfernt. - Unterstützung für Sitzungstokens wurde hinzugefügt. Das Widget verwaltet Tokens automatisch im Hintergrund.
- Unterstützung für Feldmasken, mit denen Sie auswählen können, welche Arten von Ortsdaten zurückgegeben werden sollen, nachdem der Nutzer eine Auswahl getroffen hat.
In den folgenden Abschnitten wird beschrieben, wie Sie Ihrem Projekt ein Widget für die automatische Vervollständigung hinzufügen.
AutocompleteFragment
einbetten
So fügen Sie ein Fragment für die automatische Vervollständigung hinzu:
Füge dem XML-Layout deiner Aktivität ein Fragment hinzu, wie im folgenden Beispiel gezeigt.
<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" />
So fügen Sie der Aktivität das Widget zur automatischen Vervollständigung hinzu:
- Initialisieren Sie
Places
und übergeben Sie den Anwendungskontext und Ihren API-Schlüssel. - Initialisieren Sie
AutocompleteSupportFragment
. - Rufen Sie
setPlaceFields()
auf, um anzugeben, welche Arten von Ortsdaten Sie abrufen möchten. - Fügen Sie
PlaceSelectionListener
hinzu, um eine Aktion mit dem Ergebnis auszuführen und Fehler zu beheben, die möglicherweise auftreten.
Das folgende Beispiel zeigt, wie einer Aktivität ein Widget für die automatische Vervollständigung hinzugefügt wird:
/** * 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); } });
- Initialisieren Sie
Intent zum Starten der Aktivität zur automatischen Vervollständigung verwenden
- Initialisieren Sie
Places
und übergeben Sie den App-Kontext und Ihren API-Schlüssel - Erstellen Sie mit
Autocomplete.IntentBuilder
einen Intent und übergeben Sie den gewünschtenPlaceAutocomplete
-Modus (Vollbild oder Overlay). Der Intent mussstartActivityForResult
aufrufen und einen Anfragecode übergeben, der den Intent identifiziert. - Überschreibe den
onActivityResult
-Callback, um den ausgewählten Ort zu erhalten.
Das folgende Beispiel zeigt, wie Sie mit einem Intent die automatische Vervollständigung starten und dann das Ergebnis verarbeiten:
/**
* 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.
}
}
}
Ortsauswahl ist nicht mehr verfügbar
Die Ortsauswahl wurde am 29. Januar 2019 eingestellt. Sie wurde am 29. Juli 2019 deaktiviert und ist nicht mehr verfügbar. Die weitere Verwendung führt zu einer Fehlermeldung. Das neue SDK unterstützt die Ortsauswahl nicht.