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 bisher 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 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 eine Aktualisierung der Kompatibilitätsbibliothek auf die neue Version des Places SDK for Android vorzunehmen.

Was hat sich geändert?

Die Hauptänderungen sind folgende:

  • Die neue Version des Places SDK for Android wird als statische Clientbibliothek bereitgestellt. Bis Januar 2019 war das Places SDK for Android über Google Play-Dienste verfügbar. 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. Sie können Feldmasken verwenden, um anzugeben, welche Arten von Ortsdaten zurückgegeben werden sollen.
  • Die Statuscodes, die zum 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

Mit der Veröffentlichung von Version 1.0 des eigenständigen Places SDK for Android hat Google im Januar 2019 eine Kompatibilitätsbibliothek zur Verfügung gestellt, die Sie bei der Migration von der außer Betrieb genommenen Version der Google Play-Dienste des Places SDK for Android (com.google.android.gms:play-services-places) unterstützt.

Diese Kompatibilitätsbibliothek wurde vorübergehend bereitgestellt, um API-Aufrufe für die Version der Google Play-Dienste in 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 zwischen Version 1.0 und Version 2.6.0 veröffentlicht wurde, wurde eine entsprechende Version der Places-Kompatibilitätsbibliothek veröffentlicht.

Places-Kompatibilitätsbibliothek einfrieren und verwerfen

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. Nach 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, zum Places SDK for Android zu migrieren, um neue Funktionen und wichtige Fehlerkorrekturen für Releases nach Version 2.6.0 zu erhalten. Wenn Sie derzeit die Kompatibilitätsbibliothek verwenden, folgen Sie den Schritten 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 Ihrem Android Studio-Projekt das Places SDK for Android 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:3.3.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 wechseln Sie zum Places SDK for Android:

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

  3. Synchronisiere dein Gradle-Projekt.

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

  5. Aktualisieren Sie Ihre „Powered by Google“-Assets:

    @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 Build-Fehler aufgrund der Umwandlung auf 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 beim Limit für Abfragen pro Sekunde hat sich geändert. Fehler beim Limit für Abfragen pro Sekunde werden jetzt über PlaceStatusCodes.OVER_QUERY_LIMIT zurückgegeben. Es gibt keine QPD-Limits 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.
    • Der angegebene API-Schlüssel ist ungültig.
    • 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 angegebene Anfrage wurde kein Ergebnis gefunden.

Neue Methoden

In der neuen Version des Places SDK for Android werden ganz neue Methoden eingeführt, die auf Konsistenz ausgerichtet sind. Alle neuen Methoden entsprechen den folgenden Anforderungen:

  • Endpoints verwendet 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 und ihre Funktionsweise vorgestellt.

Ort nach ID abrufen

Verwenden Sie fetchPlace(), um Details zu einem bestimmten Ort abzurufen. fetchPlace() funktioniert ähnlich wie getPlaceById().

So rufen Sie einen Ort ab:

  1. Rufen Sie fetchPlace() auf und übergeben Sie ein FetchPlaceRequest-Objekt, in dem eine Orts-ID und eine Liste von Feldern angegeben werden, in denen die Ortsdaten angegeben werden, die zurückgegeben werden sollen.

    // 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. Rufen Sie addOnSuccessListener() auf, um FetchPlaceResponse zu verarbeiten. Ein einzelnes Place-Ergebnis wird 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 von einem Ort abrufen

Verwenden Sie fetchPhoto(), um ein Foto von einem Ort zu erhalten. fetchPhoto() gibt Fotos für einen Ort zurück. Das Muster zum Anfordern eines Fotos wurde vereinfacht. Sie können PhotoMetadata jetzt direkt über das Place-Objekt anfordern. Eine separate Anfrage ist nicht mehr erforderlich. Fotos dürfen eine maximale Breite oder Höhe von 1.600 Pixeln haben. fetchPhoto() funktioniert ähnlich wie getPhoto().

So rufen Sie Fotos von Orten ab:

  1. Vereinbaren Sie einen Anruf bei fetchPlace(). 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, Sie können aber auch findCurrentPlace() verwenden:

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
    
  3. Fügen Sie ein OnSuccessListener hinzu, um die Fotometadaten aus dem resultierenden Place im FetchPlaceResponse abzurufen. Verwenden Sie dann die resultierenden Fotometadaten, um eine Bitmap und einen Quellenangabetext 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 anhand des Standorts des Nutzers suchen

Mit findCurrentPlace() können Sie den aktuellen Standort des Geräts des Nutzers ermitteln. findCurrentPlace() gibt eine Liste von PlaceLikelihoods zurück, die Orte angeben, 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:

  1. Sorgen Sie dafür, dass Ihre App die Berechtigungen ACCESS_FINE_LOCATION und ACCESS_WIFI_STATE anfordert. Der Nutzer muss die Berechtigung erteilen, auf seinen aktuellen Gerätestandort zuzugreifen. Weitere Informationen finden Sie unter App-Berechtigungen anfordern.

  2. Erstellen Sie einen 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();
    
  3. Rufen Sie „findCurrentPlace“ auf, verarbeiten Sie die Antwort und 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();
      }
    

Automatisch vervollständigte Vorschläge finden

Mit findAutocompletePredictions() können Sie Ortsvorschläge als Antwort auf Nutzersuchanfragen zurückgeben. 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 zu 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 einer Abfrage beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen und eine Ortsauswahl umfassen. Sobald eine Sitzung beendet ist, ist das Token nicht mehr gültig. Ihre App muss für jede Sitzung ein neues Token generieren.

Feldmasken

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

Um anzugeben, welche Datentypen zurückgegeben werden sollen, übergeben Sie ein Array von Place.Fields in Ihrem 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 die Ortsauswahl und die automatische Vervollständigung

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 wurde in AutocompleteActivity.RESULT_ERROR umbenannt (die Fehlerbehandlung für das Fragment der automatischen Vervollständigung 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. Bei wiederholter Verwendung erhalten Sie eine 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.
  • Sitzungstokens werden jetzt unterstützt. Das Widget verwaltet Tokens automatisch im Hintergrund.
  • Feldmasken werden jetzt unterstützt, sodass 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 ein Autocomplete-Widget zu Ihrem Projekt hinzufügen können.

AutocompleteFragment einbetten

So fügen Sie ein Fragment für die automatische 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. Gehen Sie folgendermaßen vor, um das Widget für die automatische Vervollständigung zur Aktivität hinzuzufügen:

    • 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 einen PlaceSelectionListener hinzu, um etwas mit dem Ergebnis zu tun und mögliche Fehler zu beheben.

    Das folgende Beispiel zeigt, wie ein Autocomplete-Widget zu einer Aktivität 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. Places initialisieren und den App-Kontext und Ihren API-Schlüssel übergeben
  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. Überschreibe den onActivityResult-Callback, damit der ausgewählte Ort empfangen wird.

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.
            }
        }
    }

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. Bei wiederholter Verwendung erhalten Sie eine Fehlermeldung. Das neue SDK unterstützt die Ortsauswahl nicht.