Zum neuen Places SDK Client migrieren

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In diesem Leitfaden werden die Änderungen zwischen der Places-Kompatibilitätsbibliothek und der neuen eigenständigen Version des Places SDK for Android erläutert. Wenn Sie die Places-Kompatibilitätsbibliothek verwendet haben, anstatt zur neuen eigenständigen Version des Places SDK for Android zu migrieren, erfahren Sie in diesem Leitfaden, wie Sie Ihre Projekte auf die Verwendung der neuen 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 von der Kompatibilitätsbibliothek auf die neue Version des Places SDK for Android zu aktualisieren.

Was hat sich geändert?

Die wichtigsten Änderungen:

  • Die neue Version des Places SDK for Android wird als statische Clientbibliothek bereitgestellt. Vor Januar 2019 wurde das Places SDK for Android über die Google Play-Dienste bereitgestellt. Seitdem wurde eine Places-Kompatibilitätsbibliothek zur Verfügung gestellt, um den Übergang zum neuen 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 festlegen, welche Arten von Ortsdaten zurückgegeben werden sollen.
  • Die zur Meldung von Fehlern verwendeten Statuscodes wurden verbessert.
  • Die automatische Vervollständigung unterstützt jetzt Sitzungstokens.
  • Die Ortsauswahl ist nicht mehr verfügbar.

Über die Places-Kompatibilitätsbibliothek

Mit der Version 1.0 des eigenständigen Places SDK for Android hat Google im Januar 2019 eine Kompatibilitätsbibliothek zur Unterstützung der Migration von der außer Betrieb genommenen Version der Places API for Android (com.google.android.gms:play-services-places) bereitgestellt.

Diese Bibliothek wurde vorübergehend bereitgestellt, um API-Aufrufe an die Google Play-Dienste-Version weiterzuleiten und zu übersetzen, bis Entwickler ihren Code migrieren konnten, um die neuen Namen im eigenständigen SDK zu verwenden. Für jede Version des Places SDK for Android, die zwischen Version 1.0 und 2.6.0 veröffentlicht wurde, wurde eine entsprechende Version der Places-Kompatibilitätsbibliothek veröffentlicht, um die entsprechende Funktionalität bereitzustellen.

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. Funktionen und Fehlerkorrekturen im Places SDK for Android ab Version 2.6.0 können nur über das Places SDK for Android abgerufen werden.

Google empfiehlt, zum Places SDK for Android zu migrieren, um neue Funktionen und kritische Fehlerkorrekturen für Releases vor Version 2.6.0 zu erhalten. Wenn Sie derzeit die Kompatibilitätsbibliothek verwenden, folgen Sie der Anleitung im Abschnitt Places SDK for Android installieren, 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 das Places SDK for Android Ihrem Android Studio-Projekt hinzuzufügen:

  1. Wenn Sie derzeit die Places-Kompatibilitätsbibliothek verwenden:

    1. Ersetzen Sie die folgende Zeile im Abschnitt dependencies:

          implementation 'com.google.android.libraries.places:places-compat:X.Y.Z'

      Mit dieser Zeile wechseln Sie zum Places SDK for Android:

          implementation 'com.google.android.libraries.places:places:2.6.0'

  2. Wenn Sie derzeit die Play Services-Version des Places SDK for Android verwenden:

    1. Ersetzen Sie die folgende Zeile im Abschnitt dependencies:

          implementation 'com.google.android.gms:play-services-places:X.Y.Z'

      Mit dieser Zeile wechseln Sie zum Places SDK for Android:

          implementation 'com.google.android.libraries.places:places:2.6.0'

  3. Synchronisiere dein Gradle-Projekt.

  4. Legen Sie minSdkVersion für das Anwendungsprojekt auf 16 oder höher fest.

  5. Assets von 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
    
  6. Erstellen Sie Ihre App. Falls Build-Fehler aufgrund Ihrer Konvertierung in das Places SDK for Android 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 Fehler bei der Anzahl der Abfragen pro Sekunde hat sich geändert. Fehler bei Abfragen pro Sekunde werden jetzt über PlaceStatusCodes.OVER_QUERY_LIMIT zurückgegeben. Es gibt keine weiteren Einschränkungen im Hinblick auf die Abfragen pro Tag.

Die folgenden Statuscodes wurden hinzugefügt:

  • REQUEST_DENIED: Die Anfrage wurde abgelehnt. Dies kann z. B. folgende Gründe haben:

    • Es wurde kein API-Schlüssel angegeben.
    • Ein ungültiger API-Schlüssel wurde angegeben.
    • Die Places API wurde in der Cloud Console nicht aktiviert.
    • Ein API-Schlüssel wurde mit falschen Schlüsseleinschränkungen bereitgestellt.
  • 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

In der neuen Version des Places SDK for Android werden neue Methoden eingeführt, die auf Konsistenz ausgelegt sind. Alle neuen Methoden erfüllen Folgendes:

  • 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 für Anfrageersteller übergeben.
  • Zwischenspeicher werden nicht mehr verwendet.

In diesem Abschnitt werden die neuen Methoden vorgestellt und ihre Funktionsweise erklärt.

Ort nach ID abrufen

Mit fetchPlace() können Sie Details zu einem bestimmten Ort abrufen. fetchPlace() funktioniert ähnlich wie getPlaceById().

So rufen Sie einen Ort ab:

  1. Rufen Sie fetchPlace() auf und übergeben Sie ein FetchPlaceRequest-Objekt, das eine Place ID und eine Liste von Feldern angibt, die die zurückzugebenden Ortsdaten angeben.

    // 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();
    
    
  2. Rufe addOnSuccessListener() auf, um FetchPlaceResponse zu verarbeiten. Es wird ein einzelnes Place-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());
        }
    });
    

Ortsfotos abrufen

Verwenden Sie fetchPhoto(), um ein Ortsfoto aufzunehmen. fetchPhoto() gibt Fotos für einen Ort zurück. Das Muster zum Anfordern eines Fotos wurde vereinfacht. Sie können jetzt PhotoMetadata direkt über das Place-Objekt anfordern. Eine separate Anfrage ist nicht mehr erforderlich. Die maximale Breite oder Höhe von Fotos beträgt 1600 Pixel. fetchPhoto() funktioniert ähnlich wie getPhoto().

So rufen Sie Ortsfotos ab:

  1. Rufen Sie fetchPlace() an. Achten Sie darauf, in Ihrer Anfrage das Feld PHOTO_METADATAS anzugeben:

    List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);
    
  2. Rufen Sie ein Place-Objekt ab (in diesem Beispiel wird fetchPlace() verwendet, aber Sie können auch findCurrentPlace() verwenden):

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
    
  3. Füge OnSuccessListener hinzu, um die Fotometadaten aus der resultierenden Place in FetchPlaceResponse zu erhalten. Verwende dann die daraus resultierenden Fotometadaten, um eine Bitmap und einen Attributionstext 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() kannst du den aktuellen Standort des Geräts des Nutzers ermitteln. findCurrentPlace() gibt eine Liste von PlaceLikelihoods zurück, die die Orte angeben, an denen sich das Gerät des Nutzers vermutlich befindet. findCurrentPlace() funktioniert ähnlich wie getCurrentPlace().

So rufen Sie den aktuellen Standort des Geräts ab:

  1. Prüfe, ob deine App die Berechtigungen ACCESS_FINE_LOCATION und ACCESS_WIFI_STATE anfordert. Der Nutzer muss die Berechtigung für den Zugriff auf seinen aktuellen Gerätestandort erteilen. Weitere Informationen finden Sie unter Anwendungsberechtigungen anfordern.

  2. Erstellen Sie eine FindCurrentPlaceRequest mit einer Liste von 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();
    
  3. Rufen Sie FindCurrentPlace auf und verarbeiten Sie die Antwort. Prüfen Sie zuerst, ob der Nutzer die Berechtigung zur Verwendung des 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();
      }
    

Automatische Vervollständigungen finden

Verwenden Sie findAutocompletePredictions(), um Ortsvorhersagen als Antwort auf die Suchanfragen von Nutzern zurückzugeben. findAutocompletePredictions() funktioniert ähnlich wie getAutocompletePredictions().

Hier siehst du, 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")
   .setTypeFilter(TypeFilter.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

Sitzungstoken gruppieren die Abfrage- und Auswahlphasen einer Nutzersuche zu Abrechnungszwecken in eine separate Sitzung. Wir empfehlen die Verwendung von Sitzungstokens für alle automatisch vervollständigten Sitzungen. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe einer Abfrage beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen enthalten, gefolgt von einer Ortsauswahl. Nach Beendigung einer Sitzung ist das Token nicht mehr gültig. Ihre Anwendung muss für jede Sitzung ein neues Token generieren.

Feldmasken

Bei Methoden, die Ortsdetails zurückgeben, müssen Sie bei jeder Anfrage angeben, welche Arten von Ortsdaten zurückgegeben werden sollen. Dadurch wird sichergestellt, dass Sie nur Daten anfordern und bezahlen, die Sie tatsächlich verwenden.

Wenn Sie festlegen möchten, welche Datentypen zurückgegeben werden sollen, übergeben Sie ein Array mit Place.Fields in Ihrer FetchPlaceRequest, 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 Autocomplete

In diesem Abschnitt werden die Änderungen an den Places-Widgets (Ortsauswahl und automatische Vervollständigung) erläutert.

Programmatische automatische Vervollständigung

An der automatischen Vervollständigung wurden folgende Änderungen vorgenommen:

  • PlaceAutocomplete wurde in Autocomplete umbenannt.
    • PlaceAutocomplete.getPlace wurde in Autocomplete.getPlaceFromIntent umbenannt.
    • PlaceAutocomplete.getStatus wurde in Autocomplete.getStatusFromIntent umbenannt.
  • PlaceAutocomplete.RESULT_ERROR wird in AutocompleteActivity.RESULT_ERROR umbenannt (Fehlerbehandlung für das Fragment der automatischen 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. Eine weitere Verwendung führt zu einer Fehlermeldung. Das neue SDK unterstützt die Ortsauswahl nicht.

Autocomplete-Widgets

Die Widgets für die automatische Vervollständigung wurden aktualisiert:

  • Das Präfix Place wurde aus allen Klassen entfernt.
  • Sitzungs-Tokens werden jetzt unterstützt. Das Widget verwaltet Tokens automatisch im Hintergrund.
  • Es werden jetzt Feldmasken unterstützt, 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 gezeigt, wie Sie Ihrem Projekt ein Widget zur automatischen Vervollständigung hinzufügen.

AutocompleteFragment einbetten

So fügst du ein Fragment einer automatischen Vervollständigung hinzu:

  1. 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"
      />
    
  2. 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.
    • Rufe setPlaceFields() auf, um die Arten von Ortsdaten anzugeben, die du erhalten möchtest.
    • Fügen Sie einen PlaceSelectionListener hinzu, um etwas mit dem Ergebnis zu tun und mögliche Fehler zu beheben.

    Das folgende Beispiel zeigt, wie Sie einer Aktivität ein Widget zur automatischen Vervollständigung hinzufügen:

    /**
     * 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);
        }
    });
    

Intent zum Starten der Autocomplete-Aktivität verwenden

  1. Initialisieren Sie Places und übergeben Sie den Anwendungskontext sowie Ihren API-Schlüssel
  2. Verwenden Sie Autocomplete.IntentBuilder, um einen Intent zu erstellen, und übergeben Sie den gewünschten PlaceAutocomplete-Modus (Vollbild oder Overlay). Der Intent muss startActivityForResult aufrufen und einen Anfragecode übergeben, der den Intent identifiziert.
  3. Überschreiben Sie den Callback onActivityResult, um den ausgewählten Ort zu erhalten.

Das folgende Beispiel zeigt, wie Sie einen Intent verwenden, um die automatische Vervollständigung zu starten und dann das Ergebnis zu 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.
            }
        }
    }

Die 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. Eine weitere Verwendung führt zu einer Fehlermeldung. Das neue SDK unterstützt die Ortsauswahl nicht.