Zum neuen Places SDK Client migrieren

In diesem Leitfaden werden die Unterschiede zwischen den Orten und die neue eigenständige Version des Places SDK for Android Wenn Sie bisher die Places-Kompatibilitätsbibliothek verwendet haben, statt zu der neuen eigenständigen Version des Places SDK for Android. 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 ein Update von der Kompatibilitätsbibliothek auf die neue Version des Places SDK for Android so bald wie möglich an.

Was hat sich geändert?

Die wichtigsten Änderungen sind:

• Die neue Version des Places SDK for Android wird veröffentlicht als statische Clientbibliothek. Vor Januar 2019 hat das Places SDK for Android über die Google Play-Dienste bereitgestellt wurde. Seitdem hat ein Places- wurde bereitgestellt, um die Umstellung auf das neue Places SDK for Android
• Es gibt ganz neue Methoden.
• Feldmasken werden jetzt für Methoden unterstützt, die Orte zurückgeben Details. Mithilfe von Feldmasken können Sie angeben, welche Arten von Ortsdaten zurück.
• 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

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

Diese Kompatibilitätsbibliothek wurde vorübergehend zur Weiterleitung und Übersetzung zur Verfügung gestellt API-Aufrufe für die Version der Google Play-Dienste für die neue eigenständige Version , bis die Entwickler ihren Code migrieren konnten, um die neuen Namen im eigenständiges SDK. Für jede Version des Places SDK for Android, die von Version 1.0 bis Version 2.6.0, eine entsprechende Version der Places-Kompatibilitätsbibliothek wurde veröffentlicht, um eine gleichwertige Funktionalität.

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 des Places-Kompatibilitätsbibliothek. Die einzige Möglichkeit, auf Funktionen und Fehlerkorrekturen in Places zuzugreifen Für das SDK for Android nach Version 2.6.0 wird das Places SDK for Android verwendet.

Google empfiehlt eine Migration zum Places SDK for Android , um Zugang zu neuen Funktionen und wichtigen Fehlerkorrekturen für Releases nach Version 2.6.0 zu erhalten. Wenn Sie derzeit die Kompatibilitätsbibliothek verwenden, führen Sie die folgenden Schritte in der Abschnitt Places SDK for Android installieren für die Migration auf das Places SDK for Android.

Clientbibliothek installieren

Die neue Version des Places SDK for Android wird als statische Clientbibliothek.

Verwenden Sie Maven, um den Parameter Places SDK for Android zu Ihrem Android Studio-Projekt hinzufü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 können Sie zum Places SDK for Android wechseln:

          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 können Sie zum Places SDK for Android wechseln:

          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. „Powered by Google“ aktualisieren 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 Ihnen aufgrund der Umwandlung in Places SDK for Android verwenden, finden Sie in den folgenden Abschnitten zur Behebung 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 des Limits für Abfragen pro Sekunde sind jetzt Zurückgegeben über PlaceStatusCodes.OVER_QUERY_LIMIT. 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 Elements ungültig. .

• NOT_FOUND: Für die angegebene Anfrage wurde kein Ergebnis gefunden.

Neue Methoden

Mit der neuen Version des Places SDK for Android erhalten Sie die auf Konsistenz ausgelegt sind. Alle neuen Methoden beachten Sie Folgendes:

• Endpunkte verwenden nicht mehr das Verb get.
• Anfrage- und Antwortobjekte haben denselben Namen wie die entsprechenden Objekte. client-Methode.
• Anfrageobjekte haben jetzt Builder. Erforderliche Parameter werden als Anfrage übergeben. Builder-Parameter.
• Puffer werden nicht mehr verwendet.

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

Ort über die ID abrufen

fetchPlace() verwenden um Details zu einem bestimmten Ort zu erhalten. fetchPlace() funktioniert ähnlich wie getPlaceById()

So rufen Sie einen Ort ab:

1. Rufen Sie fetchPlace() auf und übergeben Sie ein FetchPlaceRequest-Objekt, das einen Ort angibt. ID und eine Liste von Feldern zur Angabe der zurückzugebenden Ortsdaten.

   // 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 die FetchPlaceResponse zu verarbeiten. Eine einzelne Ergebnis Place 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 eines Ortes abrufen

fetchPhoto() verwenden um ein Foto von einem Ort zu erhalten. fetchPhoto() gibt Fotos für einen Ort zurück. Das Muster zum Anfordern eines Fotos vereinfacht. Sie können jetzt PhotoMetadata anfordern direkt vom Place-Objekt aus; ist keine separate Anfrage mehr erforderlich. Die maximale Breite oder Höhe von Fotos darf maximal 1.600 Pixel betragen. fetchPhoto() Funktionen ähnlich wie getPhoto().

So rufen Sie Fotos von Orten ab:

1. Vereinbaren Sie einen Anruf bei fetchPlace(). Achten Sie darauf, PHOTO_METADATAS-Feld in Ihrer Anfrage:

   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())

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

3. Fügen Sie ein OnSuccessListener hinzu, um die Fotometadaten aus dem Ergebnis abzurufen. Place in FetchPlaceResponse und verwenden Sie dann die resultierenden Fotometadaten, um Bitmap und Quellenangabe 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

findCurrentPlace() verwenden um den aktuellen Standort des Geräts des Nutzers zu ermitteln. findCurrentPlace() gibt eine Liste von PlaceLikelihoods zurück, die Orte angibt, an denen sich das Gerät des Nutzers befindet. am wahrscheinlichsten befindet. findCurrentPlace() funktioniert ähnlich wie getCurrentPlace().

So ermitteln Sie den aktuellen Standort des Nutzergeräts:

1. Achten Sie darauf, dass Ihre App die ACCESS_FINE_LOCATION und ACCESS_WIFI_STATE-Berechtigungen. Der Nutzer muss eine Zugriffsberechtigung für seine aktuellen Gerätestandort. Siehe App anfordern Berechtigungen für Details.

2. Erstellen Sie eine FindCurrentPlaceRequest, einschließlich einer Liste von Ortsdatentypen, zurück.

     // 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 bearbeiten Sie die Antwort. Überprüfen Sie zuerst, ob Der Nutzer hat die Berechtigung erteilt, den Gerätestandort zu verwenden.

     // 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

findAutocompletePredictions() verwenden um Ortsvorschläge als Antwort 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 fassen die Abfrage- und Auswahlphasen einer Nutzersuche in eine diskrete Sitzung zu Abrechnungszwecken Wir empfehlen, Sitzungstokens für alle Sitzungen zu verwenden, bei denen eine automatische Vervollständigung erfolgt. Die Sitzung beginnt, wenn der Nutzer beginnt, einen und endet, wenn sie einen Ort auswählen. Jede Sitzung kann mehrere Abfragen gefolgt von einer Ortsauswahl. Sobald eine Sitzung beendet ist, Token ist nicht mehr gültig. muss Ihre App für jedes Sitzung.

Feldmasken

In Methoden, die Ortsdetails zurückgeben, müssen Sie angeben, welche Arten von Orten Daten, die bei jeder Anfrage zurückgegeben werden sollen. So stellen Sie sicher, dass Sie (und zahlen für) Daten, die Sie tatsächlich nutzen werden.

Um anzugeben, welche Datentypen zurückgegeben werden sollen, übergeben Sie ein Array mit 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 Place Picker und automatische Vervollständigung

In diesem Abschnitt werden die Änderungen an den Places-Widgets (Place Picker und Autocomplete).

Programmatische automatische Vervollständigung

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

• PlaceAutocomplete wurde in Autocomplete umbenannt.
  • PlaceAutocomplete.getPlace wurde in Autocomplete.getPlaceFromIntent umbenannt.
  • PlaceAutocomplete.getStatus wird in Autocomplete.getStatusFromIntent umbenannt.
• PlaceAutocomplete.RESULT_ERROR wird in AutocompleteActivity.RESULT_ERROR umbenannt (Die Fehlerbehandlung für das Autocomplete-Fragment hat sich NICHT geändert.)

Ortsauswahl

Die Ortsauswahl wurde am 29. Januar 2019 eingestellt. Sie war deaktiviert am und nicht mehr verfügbar. Die weitere Nutzung führt zu eine Fehlermeldung angezeigt. 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 für Sie automatisch im Hintergrund laufen.
• Unterstützung für Feldmasken hinzugefügt, mit denen Sie die Ortstypen auswählen können Daten, die 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:

1. Fügen Sie dem XML-Layout Ihrer Aktivität ein Fragment hinzu, wie im Folgenden gezeigt: Beispiel.

   <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.
   • Initialisieren Sie AutocompleteSupportFragment.
   • Rufen Sie setPlaceFields() auf, um anzugeben, welche Arten von Ortsdaten Sie verwenden möchten. erhalten möchten.
   • Fügen Sie PlaceSelectionListener hinzu, um mit dem Ergebnis etwas zu tun, und Fehler beheben, die auftreten können.

   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 zum Starten der Aktivität zur automatischen Vervollständigung verwenden

1. Initialisieren Sie Places und übergeben Sie den App-Kontext und Ihren API-Schlüssel
2. Verwenden Sie Autocomplete.IntentBuilder, um einen Intent zu erstellen und den gewünschten Intent zu übergeben. PlaceAutocomplete-Modus (Vollbild oder Overlay). Der Intent muss folgendes aufrufen: startActivityForResult, wobei ein Anfragecode übergeben wird, der Ihre Nutzerabsicht verstehen.
3. Ü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 verarbeitet dann das Ergebnis:

    /**
     * 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 war deaktiviert am und nicht mehr verfügbar. Die weitere Verwendung führt zu eine Fehlermeldung angezeigt. Das neue SDK unterstützt die Ortsauswahl nicht.