Yeni Yerler SDK İstemcisine Taşıma

Bu kılavuzda, Yerler uyumluluk kitaplığı ile Android için Yerler SDK'sının 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çmek yerine Yerler uyumluluk kitaplığını kullanıyorsanız bu kılavuzda, projelerinizi Android için Yerler SDK'sının yeni sürümünü kullanacak şekilde nasıl güncelleyeceğiniz gösterilmektedir.

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

Neler değişti?

Değişiklik yapılan başlıca alanlar şunlardır:

  • Android için Yerler SDK'sının yeni sürümü statik istemci kitaplığı olarak dağıtılır. Ocak 2019'dan önce Android için Yerler SDK'sı Google Play Hizmetleri aracılığıyla kullanıma sunuluyordu. O zamandan beri, Android için yeni Yerler SDK'sına geçişi kolaylaştırmak amacıyla bir Yerler uyumluluk kitaplığı sağlandı.
  • Yepyeni yöntemler vardır.
  • Alan maskeleri artık yer ayrıntılarını döndüren yöntemler için destekleniyor. Hangi tür yer verilerinin döndürüleceğini belirtmek için alan maskelerini kullanabilirsiniz.
  • Hataları bildirmek için kullanılan durum kodları iyileştirildi.
  • Otomatik tamamlama artık oturum jetonlarını destekliyor.
  • Yer Seçici artık kullanılamıyor.

Yerler uyumluluk kitaplığı hakkında

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

Bu uyumluluk kitaplığı, geliştiriciler kodlarını bağımsız SDK'daki yeni adları kullanacak şekilde taşıyana kadar Google Play Hizmetleri sürümüne yönelik API çağrılarını yeni bağımsız sürüme yönlendirmek ve çevirmek için geçici olarak sağlanmıştır. Android için Yerler SDK'sının 1.0 sürümünden 2.6.0 sürümüne kadar yayınlanan her sürümü için, eşdeğer işlevsellik sağlamak amacıyla Yerler uyumluluk kitaplığının ilgili sürümü yayınlanmıştır.

Places uyumluluk kitaplığını dondurma ve desteğini sonlandırma

Android için Yerler SDK'sı uyumluluk kitaplığının tüm sürümleri 31 Mart 2022'den itibaren kullanımdan kaldırıldı. 2.6.0 sürümü, Yerler uyumluluk kitaplığının son sürümüdür. Android için Yerler SDK'sının 2.6.0 sürümünden sonraki sürümlerindeki özelliklere ve hata düzeltmelerine erişmenin tek yolu Android için Yerler SDK'sını kullanmaktır.

Google, 2.6.0 sürümünden sonraki sürümlerde yeni özelliklere ve kritik hata düzeltmelerine erişmek için Android için Yerler SDK'sına geçmenizi önerir. Şu anda uyumluluk kitaplığını kullanıyorsanız Android için Yerler SDK'sına geçmek ü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 istemci kitaplığı olarak dağıtılır.

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

  1. Şu anda Places uyumluluk 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çmek üzere şu satırı kullanın:

          implementation 'com.google.android.libraries.places:places:3.3.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çmek üzere şu satırı kullanın:

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

  3. Gradle projenizi senkronize edin.

  4. Uygulama projeniz için minSdkVersion değerini 16 veya daha yüksek bir değere ayarlayın.

  5. "Google Tarafından Güçlendirilmiştir" öğ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ı derleyin. Android için Yerler SDK'sına geçişiniz nedeniyle derleme hataları görürseniz bu hataları çözme hakkında bilgi edinmek için aşağıdaki bölümlere bakın.

Yeni Places SDK istemcisini başlatma

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üyor. Artık QPS 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ı.
    • Places API, Cloud Console'da etkinleştirilmedi.
    • Yanlış anahtar kısıtlamaları içeren bir API anahtarı sağlandı.

  • INVALID_REQUEST: Eksik veya geçersiz bir bağımsız değişken nedeniyle istek 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ünde, tutarlılık için tasarlanmış yepyeni yöntemler sunulmaktadır. Yeni yöntemlerin tümü aşağıdakilere uyar:

  • Uç noktalar artık get fiili kullanmıyor.
  • İstek ve yanıt nesneleri, ilgili istemci yöntemiyle aynı ada sahiptir.
  • İstek nesnelerinde artık oluşturucular var; zorunlu parametreler, istek oluşturucu parametreleri olarak iletilir.
  • Tamponlar artık kullanılmamaktadır.

Bu bölümde yeni yöntemler tanıtılmakta ve bunların işleyiş şekli açıklanmaktadır.

Kimliğe göre yer getirme

Belirli bir yerle ilgili ayrıntıları görmek için fetchPlace() simgesini kullanın. fetchPlace(), getPlaceById() işlevine benzer şekilde çalışır.

Bir yer almak için aşağıdaki adımları uygulayın:

  1. Bir yer kimliğini ve döndürülecek yer verilerini belirten bir alan listesi belirten bir FetchPlaceRequest nesnesi göndererek fetchPlace() işlevini çağırın.

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

// Construct a request object, passing the place ID and fields array.
FetchPlaceRequest request = FetchPlaceRequest.builder(placeId, placeFields)
        .build();

  2. FetchPlaceResponse ile ilgili işlem yapmak 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());
    }
});

Yer fotoğrafı getirme

Yer fotoğrafı almak için fetchPhoto() simgesini kullanın. fetchPhoto(), bir yerle ilgili fotoğrafları döndürür. Fotoğraf isteme şekli basitleştirildi. Artık PhotoMetadata'yi doğrudan Place nesnesinden isteyebilirsiniz. Ayrı bir istek göndermeniz gerekmez. Fotoğrafların genişliği veya yüksekliği en fazla 1.600 piksel olabilir. fetchPhoto(), getPhoto()'e benzer şekilde çalışır.

Yer fotoğraflarını almak için aşağıdaki 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ılmaktadır ancak findCurrentPlace() da kullanılabilir):

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

  3. FetchPlaceResponse içinde oluşturulan Place öğesinden fotoğraf meta verilerini almak için bir OnSuccessListener ekleyin, ardından elde edilen fotoğraf meta verilerini kullanarak bir bitmap ve ilişkilendirme metni alı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() simgesini kullanın. findCurrentPlace() kullanıcı cihazının büyük olasılıkla bulunduğu yerleri belirten PlaceLikelihood değerlerinin listesini döndürür. findCurrentPlace(), getCurrentPlace()'e benzer şekilde çalışır.

Kullanıcının cihazının mevcut konumunu almak için aşağıdaki 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şmek için izin vermesi gerekir. Ayrıntılar için Uygulama İzinleri İsteme başlıklı makaleyi inceleyin.

  2. Döndürülecek yer veri 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.DISPLAY_NAME);

  // Use the builder to create a FindCurrentPlaceRequest.
  FindCurrentPlaceRequest request =
          FindCurrentPlaceRequest.builder(placeFields).build();

  3. findCurrentPlace işlevini çağırın ve yanıtı işleyin. Öncelikle kullanıcının cihaz konumunu kullanma izni verip vermediğini kontrol edin.

      // 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() öğesini kullanın. findAutocompletePredictions(), getAutocompletePredictions()'e benzer şekilde çalışır.

Aşağıdaki örnekte findAutocompletePredictions() çağrısı gösterilmektedir:

// 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ı, faturalandırma amacıyla kullanıcı aramasının sorgu ve seçim aşamalarını ayrı bir oturumda gruplandırır. Tüm otomatik tamamlama oturumları için oturum jetonlarını kullanmanızı öneririz. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından bir yer seçimi olabilir. Bir oturum sona erdiğinde jeton artık geçerli olmaz. 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 hangi yer verisi türlerinin döndürüleceğini belirtmeniz gerekir. Bu sayede yalnızca gerçekten kullanacağınız verileri istemenizi (ve bunlar için ödeme yapmanızı) sağlar.

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

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

Alan maskesinde kullanabileceğiniz alanların listesi için Yer Veri Alanları (Yeni) bölümüne bakın.

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

Yer Seçici ve Otomatik Tamamlama güncellemeleri

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

Programatik otomatik tamamlama

Otomatik tamamlama özelliğinde 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 DEĞİŞMEDİ).

Yer Seçici

Yer Seçici'nin desteği 29 Ocak 2019'da sonlandırıldı. Bu özellik 29 Temmuz 2019'da devre dışı bırakıldı ve artık kullanılamıyor. Devam eden kullanım, bir hata mesajıyla sonuçlanır. Yeni SDK, yer seçiciyi desteklemez.

Otomatik tamamlama widget'ları

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ı arka planda otomatik olarak sizin için yönetir.
  • Kullanıcı bir seçim yaptıktan sonra hangi yer verisi türlerinin döndürüleceğini seçmenize olanak tanıyan alan maskeleri için destek eklendi.

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

AutocompleteFragment yerleştirme

Otomatik tamamlama snippet'i 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 öğesini başlatın.
    • AutocompleteSupportFragment öğesini başlatın.
    • Almak istediğiniz yer verisi türlerini belirtmek için setPlaceFields() işlevini çağırın.
    • Sonuçla ilgili bir işlem yapmak ve oluşabilecek hataları ele almak 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.DISPLAY_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 intent kullanma

  1. Uygulama bağlamını ve API anahtarınızı göndererek Places'ü başlatma
  2. İstediğiniz PlaceAutocomplete modunu (tam ekran veya yer paylaşımı) ileterek intent oluşturmak için Autocomplete.IntentBuilder kullanın. Intent, startActivityForResult işlevini çağırarak intent'inizi tanımlayan bir istek kodu göndermelidir.
  3. Seçilen yeri almak için onActivityResult geri çağırma işlevini geçersiz kılın.

Aşağıdaki örnekte, otomatik tamamlamayı başlatmak ve ardından sonucu işlemek için bir intent'in 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.DISPLAY_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'nin desteği 29 Ocak 2019'da sonlandırıldı. Bu özellik 29 Temmuz 2019'da devre dışı bırakıldı ve artık kullanılamıyor. Devam eden kullanım, bir hata mesajıyla sonuçlanır. Yeni SDK, yer seçiciyi desteklemez.