Zum neuen Places SDK Client migrieren

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 statt der Migration zur neuen eigenständigen Version des Places SDK for Android Ihre Places API-Bibliothek verwendet haben, lesen Sie in dieser Anleitung, wie Sie Ihre Projekte zur 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 Google Play-Dienste verfügbar gemacht. Seitdem wurde eine Places-Kompatibilitätsbibliothek bereitgestellt, um den Wechsel 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 angeben, welche Arten von Ortsdaten zurückgegeben werden sollen.
  • Die Statuscodes, die beim Melden von Fehlern verwendet werden, wurden verbessert.
  • Die automatische Vervollständigung unterstützt jetzt Sitzungstokens.
  • Die Ortsauswahl ist nicht mehr verfügbar.

Places-Kompatibilitätsbibliothek

Im Januar 2019 wurde mit Version 1.0 des eigenständigen Places SDK for Android eine Kompatibilitätsbibliothek zur Unterstützung bei der Migration der außer Betrieb genommenen Version des Places SDK for Android (com.google.android.gms:play-services-places) bereitgestellt.

Diese Kompatibilitätsbibliothek wurde vorübergehend bereitgestellt, um API-Aufrufe an die Google Play-Dienste-Version an die neue eigenständige 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 von Version 1.0 bis Version 2.6.0 veröffentlicht wurde, wurde eine entsprechende Version der Places-Kompatibilitätsbibliothek veröffentlicht, um eine entsprechende Funktionalität zu bieten.

Places-Kompatibilitätsbibliothek einfrieren und einstellen

Am 31. März 2022 wurden alle Versionen der Kompatibilitätsbibliothek für das Places SDK for Android eingestellt. Version 2.6.0 ist die letzte Version der Places-Kompatibilitätsbibliothek. Mit dem Places SDK for Android können Sie nur auf Funktionen und Fehlerkorrekturen in Version 2.6.0 des Places SDK for Android zugreifen.

Google empfiehlt, zum Places SDK for Android zu migrieren, um auf neue Funktionen und wichtige Fehlerkorrekturen für Versionen vor Version 2.6.0 zugreifen zu können. Wenn Sie die Kompatibilitätsbibliothek derzeit 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 auf das Places SDK for Android:

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

  2. Wenn Sie derzeit die Play-Dienste-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 auf das Places SDK for Android:

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

  3. Synchronisiere dein Gradle-Projekt.

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

  5. Aktualisieren Sie Ihre Assets von „Powered by 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

  6. Erstellen Sie Ihre App. Wenn Sie Build-Fehler aufgrund der Konvertierung in das Places SDK for Android feststellen, finden Sie in den folgenden Abschnitten Informationen dazu, wie Sie diese Fehler beheben.

Neuen Places SDK-Client initialisieren

Initialisieren Sie den neuen Places SDK-Client wie im folgenden Beispiel:

// 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 der maximalen Anzahl von Abfragen pro Sekunde hat sich geändert. Die Fehler der maximalen Anzahl von Abfragen pro Sekunde werden jetzt über PlaceStatusCodes.OVER_QUERY_LIMIT zurückgegeben. Es gibt keine weiteren Einschränkungen für die Anzahl der Abfragen pro Quartal.

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

  • INVALID_REQUEST: Die Anfrage ist aufgrund eines fehlenden oder ungültigen Arguments ungültig.

  • NOT_FOUND: Für die 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 die folgenden Anforderungen:

  • Endpunkte verwenden das Verb get nicht mehr.
  • Anfrage- und Antwortobjekte haben denselben Namen wie die entsprechende Clientmethode.
  • Anfrageobjekte haben jetzt Builder. Die erforderlichen Parameter werden als Anfrage-Builder-Parameter übergeben.
  • Puffer werden nicht mehr verwendet.

In diesem Abschnitt werden die neuen Methoden vorgestellt und ihre Funktionsweise erläutert.

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 Orts-ID und eine Liste von Feldern mit den zurückgegebenen Ortsdaten angibt.

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

Ortsfoto abrufen

Verwenden Sie fetchPhoto(), um ein Foto 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. Es ist keine separate Anfrage mehr erforderlich. Fotos dürfen maximal 1.600 Pixel breit oder hoch sein. fetchPhoto() funktioniert ähnlich wie getPhoto().

So laden Sie Fotos von Orten herunter:

  1. Richten Sie einen Anruf an fetchPlace() ein. Das Feld PHOTO_METADATAS muss in der Anfrage enthalten sein:

    List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);

  2. Rufen Sie ein „Place“-Objekt ab. In diesem Beispiel wird fetchPlace() verwendet. Sie können aber auch findCurrentPlace() verwenden:

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();

  3. Fügen Sie einen OnSuccessListener hinzu, um die Fotometadaten aus dem Ergebnis-Place in der FetchPlaceResponse abzurufen, und verwenden Sie dann die resultierenden Foto-Metadaten, um eine Bitmap und einen Attributionstext abzurufen:

    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 vom Standort des Nutzers aus suchen

Verwenden Sie findCurrentPlace(), um den aktuellen Standort des Geräts zu ermitteln. findCurrentPlace() gibt eine Liste von PlaceLikelihoods zurück, die angeben, wo sich das Gerät des Nutzers am wahrscheinlichsten befindet. findCurrentPlace() funktioniert ähnlich wie getCurrentPlace().

Gehen Sie so vor, um den aktuellen Standort des Geräts abzurufen:

  1. Achten Sie darauf, dass Ihre Anwendung die Berechtigungen ACCESS_FINE_LOCATION und ACCESS_WIFI_STATE anfordert. Der Nutzer muss die Berechtigung für den Zugriff auf den aktuellen Gerätestandort erteilen. Weitere Informationen finden Sie unter App-Berechtigungen anfordern.

  2. Erstellen Sie einen FindCurrentPlaceRequest mit 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();

  3. Rufen Sie findCurrentPlace auf und verarbeiten Sie die Antwort. Prüfen Sie 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();
  }

Automatische Vervollständigungen finden

Verwenden Sie findAutocompletePredictions(), um Ortsantworten als Reaktion auf Suchanfragen von Nutzern 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 gruppieren die Abfrage- und Auswahlphasen einer Nutzersuche zu Abrechnungszwecken in eine separate Sitzung. 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 und dann eine Ortsauswahl umfassen. Sobald eine Sitzung beendet wird, 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 angeben, welche Arten von Ortsdaten mit den einzelnen Anfragen zurückgegeben werden sollen. Auf diese Weise stellen Sie sicher, dass Sie nur Daten anfragen (und bezahlen).

Um anzugeben, welche Datentypen zurückgegeben werden sollen, übergeben Sie ein Array von 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 bei der Ortsauswahl und automatischen Vervollständigungen

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

Programmatische automatische Vervollständigung

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

  • PlaceAutocomplete wird in Autocomplete umbenannt.
    • PlaceAutocomplete.getPlace wird in Autocomplete.getPlaceFromIntent umbenannt.
    • PlaceAutocomplete.getStatus wird in Autocomplete.getStatusFromIntent umbenannt.
  • PlaceAutocomplete.RESULT_ERROR wird in AutocompleteActivity.RESULT_ERROR umbenannt (Fehlerbehandlung für das Autocomplete-Fragment wurde 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.

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.
  • Feldmasken werden jetzt unterstützt. Damit können Sie auswählen, 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.

Ein AutocompleteFragment einbetten

So fügen Sie ein Fragment mit automatischer Vervollständigung hinzu:

  1. Fügen Sie dem XML-Layout Ihrer 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 für die automatische Vervollständigung hinzu:

    • Initialisieren Sie Places und übergeben Sie den Anwendungskontext und Ihren API-Schlüssel.
    • Initialisiere AutocompleteSupportFragment.
    • Rufen Sie setPlaceFields() auf, um die Arten der Ortsdaten anzugeben, die Sie abrufen möchten.
    • Fügen Sie einen PlaceSelectionListener hinzu, um das Ergebnis zu verarbeiten und mögliche Fehler zu beheben.

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

Intent verwenden, um die Aktivität für die automatische Vervollständigung zu starten

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

Das folgende Beispiel zeigt, wie Sie mit einem Intent die automatische Vervollständigung starten und das Ergebnis dann 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.