Yeni Yerler SDK İstemcisine Taşıma

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Bu kılavuzda, Yerler uyumluluk kitaplığı ve Yerler SDK'sı Android'in yeni bağımsız sürümü arasındaki değişiklikler açıklanmaktadır. Android için Yerler SDK'sının yeni bağımsız sürümüne geçiş yapmak yerine Yerler uyumluluk kitaplığını kullanıyorsanız bu kılavuzda, Android için Yerler SDK'sının yeni sürümünü kullanmak üzere projelerinizi nasıl güncelleyeceğinizi görebilirsiniz.

Android için Yerler SDK'sının 2.6.0 sürümünden sonraki özelliklere ve hata düzeltmelerine erişmenin tek yolu Android için Yerler SDK'sını kullanmaktır. Google, uyumluluk kitaplığından Android için yeni Yerler SDK'sına mümkün olan en kısa sürede güncellemenizi önerir.

Neler değişti?

Ana değişiklik alanları şunlardır:

  • Android için Yerler SDK'sının yeni sürümü, statik bir istemci kitaplığı olarak dağıtılır. Android için Yerler SDK'sı, Ocak 2019'dan önce Google Play Hizmetleri üzerinden kullanıma sunuluyordu. O zamandan beri, Android için yeni Yerler SDK'sına geçişi kolaylaştırmak üzere bir Yerler uyumluluk kitaplığı sağlandı.
  • Yepyeni yöntemler var.
  • Alan maskeleri artık yer ayrıntılarını döndüren yöntemler için desteklenmektedir. Döndürülecek yer verisi türlerini belirtmek için alan maskelerinden yararlanabilirsiniz.
  • Hataları bildirmek için kullanılan durum kodları iyileştirildi.
  • Otomatik tamamlama artık oturum jetonlarını destekliyor.
  • Yer Seçici artık kullanılamamaktadır.

Yerler uyumluluk kitaplığı hakkında

Ocak 2019'da Android için bağımsız Yerler SDK'sının 1.0 sürümüyle birlikte Google, Android için Yerler SDK'sının (com.google.android.gms:play-services-places) kullanımdan kaldırılan Google Play Hizmetleri sürümünden taşımaya yardımcı olmak amacıyla bir uyumluluk kitaplığı sundu.

Bu uyumluluk kitaplığı, geliştiriciler bağımsız SDK'da yeni adları kullanmak için kodlarını taşıyabilene kadar, Google Play Hizmetleri sürümünü hedefleyen API çağrılarını yeni bağımsız sürüme yönlendirmek ve çevirmek için geçici olarak sağlandı. Android için Yerler SDK'sının 1.0 sürümünden 2.6.0'a kadar yayınlanan her bir sürümü için eşdeğer işlevler sunmak amacıyla Yerler uyumluluk kitaplığının karşılık gelen bir sürümü yayınlandı.

Yerler uyumluluk kitaplığının dondurulması ve kullanımdan kaldırılması

Android için Yerler SDK'sı için uyumluluk kitaplığının tüm sürümleri 31 Mart 2022 itibarıyla kullanımdan kaldırılmıştır. Sürüm 2.6.0, Yerler uyumluluk kitaplığının son sürümüdür. Android için Sürüm SDK'sının 2.6.0'ın üzerindeki özelliklerine ve hata düzeltmelerine erişmenin tek yolu Android için Yerler SDK'sını kullanmaktır.

Google, Sürüm 2.6.0'ın üzerindeki sürümlerde yeni özelliklere ve kritik hata düzeltmelerine erişmek için Android için Yerler SDK'sına geçiş yapmanızı önerir. Şu anda uyumluluk kitaplığını kullanıyorsanız Android için Yerler SDK'sına geçiş yapmak üzere Android için Yerler SDK'sını yükleme bölümündeki adımları uygulayın.

İstemci kitaplığını yükleme

Android için Yerler SDK'sının yeni sürümü, statik bir istemci kitaplığı olarak dağıtılır.

Android için Yerler SDK'sını Android Studio projenize eklemek üzere Maven'i kullanın:

  1. Şu anda Yerler uyumluluğu kitaplığını kullanıyorsanız:

    1. dependencies bölümünde aşağıdaki satırı değiştirin:

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

      Android için Yerler SDK'sına geçiş yapmak üzere bu satırla:

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

  2. Şu anda Android için Yerler SDK'sının Play Hizmetleri sürümünü kullanıyorsanız:

    1. dependencies bölümünde aşağıdaki satırı değiştirin:

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

      Android için Yerler SDK'sına geçiş yapmak üzere bu satırla:

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

  3. Gradle projenizi senkronize edin.

  4. Uygulama projenizin minSdkVersion değerini 16 veya daha yüksek bir değere ayarlayın.

  5. "Google Tarafından Desteklenmektedir" öğelerinizi güncelleyin:

    @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. Uygulamanızı geliştirin. Android için Yerler SDK'sına dönüştürme işleminiz nedeniyle herhangi bir yapı hatası görürseniz bu hataları gidermeyle ilgili bilgi için aşağıdaki bölümlere bakın.

Yeni Yerler SDK'sı istemcisini ilk kullanıma hazırlayın

Yeni Yerler SDK'sı istemcisini aşağıdaki örnekte gösterildiği gibi başlatın:

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

Durum kodları

QPS sınırı hatalarının durum kodu değişti. QPS sınırı hataları artık PlaceStatusCodes.OVER_QUERY_LIMIT üzerinden döndürülür. Artık QPD sınırı yoktur.

Aşağıdaki durum kodları eklendi:

  • REQUEST_DENIED - İstek reddedildi. Bunun olası nedenleri şunlardır:

    • API anahtarı sağlanmadı.
    • Geçersiz bir API anahtarı sağlandı.
    • Place API, Cloud Console'da etkinleştirilmemiştir.
    • Hatalı anahtar kısıtlamalarına sahip bir API anahtarı sağlandı.
  • INVALID_REQUEST: İstek, eksik veya geçersiz bağımsız değişken nedeniyle geçersiz.

  • NOT_FOUND: Belirtilen istek için sonuç bulunamadı.

Yeni yöntemler

Android için Yerler SDK'sının yeni sürümü, tutarlılık için tasarlanmış tüm yeni yöntemleri kullanıma sunuyor. Tüm yeni yöntemler aşağıdaki koşullara uyar:

  • Uç noktalar artık get fiilini kullanmaz.
  • İstek ve yanıt nesneleri, karşılık gelen istemci yöntemiyle aynı adı paylaşır.
  • İstek nesneleri artık oluşturuculara sahiptir; gerekli parametreler, istek oluşturucu parametreleri olarak aktarılır.
  • Arabellekler artık kullanılmıyor.

Bu bölümde yeni yöntemler tanıtılmakta ve bunların işleyiş şekli gösterilmektedir.

Kimliğe göre bir yer getir

Belirli bir yerle ilgili ayrıntılı bilgi almak için fetchPlace() simgesini kullanın. fetchPlace(), getPlaceById() işlevine benzer şekilde çalışır.

Bir yeri getirmek için şu adımları uygulayın:

  1. fetchPlace() işlevini çağırarak bir Yer Kimliği belirten FetchPlaceRequest nesnesi ve döndürülecek Yer verilerini belirten bir alanlar listesi iletin.

    // 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. FetchPlaceResponse ile ilgilenmek için addOnSuccessListener() numaralı telefonu arayın. Tek bir Place sonucu döndürülür.

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

Bir yerin fotoğrafını getir

Yer fotoğrafı çekmek için fetchPhoto() özelliğini kullanın. fetchPhoto() bir yerin fotoğraflarını döndürür. Fotoğraf isteme deseni basitleştirilmiş. Artık doğrudan Place nesnesinden PhotoMetadata isteyebilirsiniz. Ayrı bir istek gerekmez. Fotoğraflar en fazla 1.600 piksel genişliğinde veya yüksekliğinde olabilir. fetchPhoto(), getPhoto() işlevine benzer şekilde çalışır.

Yer fotoğrafları getirmek için şu adımları uygulayın:

  1. fetchPlace() numaralı telefonu arayın. İsteğinize PHOTO_METADATAS alanını eklediğinizden emin olun:

    List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);
    
  2. Bir Yer nesnesi alın (bu örnekte fetchPlace() kullanılır, ancak findCurrentPlace() komutunu da kullanabilirsiniz):

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
    
  3. FetchPlaceResponse içinde elde edilen Place öğesinden fotoğraf meta verisi almak için bir OnSuccessListener ekleyin, ardından bit eşlem ve ilişkilendirme metni almak için sonuçta elde edilen fotoğraf meta verilerini kullanın:

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

Kullanıcının konumundan bir yer bulma

Kullanıcının cihazının mevcut konumunu bulmak için findCurrentPlace() aracını kullanın. findCurrentPlace(), kullanıcının cihazının bulunma olasılığının en yüksek olduğu yerleri belirten bir PlaceLikelihood listesi döndürür. findCurrentPlace(), getCurrentPlace() işlevine benzer şekilde çalışır.

Kullanıcının cihazının geçerli konumunu almak için şu adımları uygulayın:

  1. Uygulamanızın ACCESS_FINE_LOCATION ve ACCESS_WIFI_STATE izinlerini istediğinden emin olun. Kullanıcının mevcut cihaz konumuna erişim izni vermesi gerekir. Ayrıntılar için Uygulama İzni İsteme bölümüne bakın.

  2. Döndürülecek yer verisi türlerinin listesini içeren bir FindCurrentPlaceRequest oluşturun.

      // 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. findCurrentPlace'i çağırın ve ardından, kullanıcının cihaz konumunu kullanma izni verdiğinden emin olmak için yanıtı işleyin.

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

Otomatik tamamlama tahminlerini bulma

Kullanıcı arama sorgularına yanıt olarak yer tahminleri döndürmek için findAutocompletePredictions() aracını kullanın. findAutocompletePredictions(), getAutocompletePredictions() işlevine benzer şekilde çalışır.

Aşağıdaki örnekte findAutocompletePredictions() aranır:

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

Oturum jetonları

Oturum jetonları, kullanıcı aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturum halinde gruplandırır. Tüm otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçildiğinde sona erer. Her oturumda birden fazla sorgu ve bunu izleyen tek bir yer seçilebilir. Bir oturum sona erdiğinde, jeton artık geçerli değildir. Uygulamanız, her oturum için yeni bir jeton oluşturmalıdır.

Alan maskeleri

Yer ayrıntılarını döndüren yöntemlerde, her istekle birlikte döndürülecek yer verisi türlerini belirtmelisiniz. Bu, yalnızca gerçekten kullanacağınız verileri talep ettiğinizden (ve ödeme yaptığınızdan) emin olmanıza yardımcı olur.

Döndürülecek veri türlerini belirtmek için aşağıdaki örnekte gösterildiği gibi FetchPlaceRequest işlevinizde bir Place.Field dizisi iletin:

// Include address, ID, and phone number.
List<Place.Field> placeFields = Arrays.asList(Place.Field.ADDRESS,
                                              Place.Field.ID,
                                              Place.Field.PHONE_NUMBER);

Aşağıdaki alanlardan birini veya daha fazlasını kullanabilirsiniz:

  • 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

Yerler veri SKU'ları hakkında daha fazla bilgi edinin.

Yer Seçici ve Otomatik Tamamlama güncellemeleri

Bu bölümde, Yerler widget'larındaki (Yer Seçici ve Otomatik Tamamlama) yapılan değişiklikler açıklanmaktadır.

Programatik otomatik tamamlama

Otomatik tamamlamada aşağıdaki değişiklikler yapıldı:

  • PlaceAutocomplete, Autocomplete olarak yeniden adlandırıldı.
    • PlaceAutocomplete.getPlace, Autocomplete.getPlaceFromIntent olarak yeniden adlandırıldı.
    • PlaceAutocomplete.getStatus, Autocomplete.getStatusFromIntent olarak yeniden adlandırıldı.
  • PlaceAutocomplete.RESULT_ERROR, AutocompleteActivity.RESULT_ERROR olarak yeniden adlandırıldı (otomatik tamamlama parçası için hata işleme durumu DEĞİŞTİRİLMEDİ).

Yer Seçici

Yer Seçici, 29 Ocak 2019'da kullanımdan kaldırıldı. 29 Temmuz 2019'da kapatılmış ve artık kullanılamamaktadır. Kullanmaya devam ederseniz bir hata mesajı alırsınız. Yeni SDK'da Yer Seçici desteklenmiyor.

Widget'ları otomatik tamamlama

Otomatik tamamlama widget'ları güncellendi:

  • Place ön eki tüm sınıflardan kaldırıldı.
  • Oturum jetonları için destek eklendi. Widget, jetonları sizin için otomatik olarak arka planda yönetir.
  • Kullanıcı seçim yaptıktan sonra döndürülecek yer verisi türlerini seçmenize olanak tanıyan alan maskeleri için destek eklendi.

Aşağıdaki bölümlerde, projenize otomatik tamamlama widget'ının nasıl ekleneceği gösterilmektedir.

AutocompleteFragment yerleştir

Otomatik tamamlama parçası eklemek için aşağıdaki adımları uygulayın:

  1. Aşağıdaki örnekte gösterildiği gibi etkinliğinizin XML düzenine bir parça ekleyin.

    <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. Otomatik tamamlama widget'ını etkinliğe eklemek için aşağıdaki adımları uygulayın:

    • Uygulama bağlamını ve API anahtarınızı ileterek Places ilk kullanıma hazırlayın.
    • AutocompleteSupportFragment öğesini ilk kullanıma hazırlayın.
    • Almak istediğiniz yer verisi türlerini belirtmek için setPlaceFields() numaralı telefonu arayın.
    • Sonuçla bir şeyler yapmak ve ortaya çıkabilecek hataları düzeltmek için bir PlaceSelectionListener ekleyin.

    Aşağıdaki örnekte bir etkinliğe otomatik tamamlama widget'ı ekleme gösterilmektedir:

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

Otomatik tamamlama etkinliğini başlatmak için amaç kullanın

  1. Uygulama bağlamı ve API anahtarınız ile Places uygulaması başlatılıyor
  2. Bir amaç oluşturmak ve istediğiniz PlaceAutocomplete modunu (tam ekran veya yer paylaşımı) iletmek için Autocomplete.IntentBuilder özelliğini kullanın. Amaç, startActivityForResult işlevini çağırmalı ve amacınızı tanımlayan bir istek kodu iletmelidir.
  3. Seçili yeri almak için onActivityResult geri çağırmasını geçersiz kılın.

Aşağıdaki örnekte otomatik tamamlamayı başlatmak ve ardından sonucu işlemek için niyetin nasıl kullanılacağı gösterilmektedir:

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

Yer Seçici artık kullanılamıyor

Yer Seçici, 29 Ocak 2019'da kullanımdan kaldırıldı. 29 Temmuz 2019'da kapatılmış ve artık kullanılamamaktadır. Kullanmaya devam ederseniz bir hata mesajı alırsınız. Yeni SDK'da Yer Seçici desteklenmiyor.