Bu sayfa, Cloud Translation API ile çevrilmiştir.

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.

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

Neler değişti?

Temel 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. Ocak 2019'dan önce, Android için Yerler SDK'sı Google Play Hizmetleri üzerinden kullanıma sunuluyordu. O zamandan bu yana, Android için yeni Yerler SDK'sına geçişi kolaylaştırmak amacıyla bir Yerler uyumluluk kitaplığı sağlanmıştır.
Tamamen yeni yöntemler mevcuttur.
Alan maskeleri artık yer ayrıntılarını döndüren yöntemlerde desteklenmektedir. Döndürülecek yer verisi türlerini 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ığı, Google Play Hizmetleri sürümüne hedeflenen API çağrılarını yeni bağımsız sürüme yönlendirmek ve çevirmek amacıyla, geliştiriciler bağımsız SDK'daki yeni adları kullanacak şekilde kodlarını taşıyana kadar geçici olarak sağlanmıştır. Android için Yerler SDK'sının Sürüm 1.0 ile Sürüm 2.6.0 arasında yayınlanan her sürümü için, eşdeğer işlev sunmak üzere Yerler uyumluluk kitaplığının karşılık gelen bir sürümü yayınlanmıştır.

Yerler uyumluluk kitaplığını dondurma ve kullanımdan kaldırma

Android için Yerler SDK'sı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 Yerler SDK'sının 2.6.0 sürümünü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 üzere 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 için aşağıdaki Android için Yerler SDK'sını yükleme bölümündeki adımları izleyin.

İ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:

Şu anda Yerler 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'
```
  Bu satırı kullanarak Android için Yerler SDK'sına geçebilirsiniz:
```
    implementation 'com.google.android.libraries.places:places:3.3.0'
```
Ş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'
```
  Bu satırı kullanarak Android için Yerler SDK'sına geçebilirsiniz:
```
    implementation 'com.google.android.libraries.places:places:3.3.0'
```
Gradle projenizi senkronize edin.
Uygulama projeniz için minSdkVersion değerini 16 veya daha yüksek bir değere ayarlayın.

"Powered by Google" öğ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

Uygulamanızı oluşturun. Android için Yerler SDK'sını dönüştürmeniz nedeniyle derleme hataları görürseniz bu hataların çözümüyle ilgili bilgiler için aşağıdaki bölümlere bakın.

Yeni Yerler SDK istemcisini başlatma

Yeni Yerler SDK 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ı için durum kodu değişti. QPS sınır hataları artık PlaceStatusCodes.OVER_QUERY_LIMIT üzerinden döndürülüyor. Artık QPD sınırı yok.

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ına sahip bir API anahtarı sağlandı.
INVALID_REQUEST — İstek, eksik veya geçersiz bir bağımsız değişken nedeniyle geçersiz.
NOT_FOUND: Belirtilen istek için hiçbir sonuç bulunamadı.

Yeni yöntemler

Android için Yerler SDK'sının yeni sürümü, tutarlılık sağlamak üzere tasarlanmış yepyeni yöntemleri kullanıma sunar. Tüm yeni yöntemler şunlara uyar:

Uç noktalar artık get fiilini kullanmaz.
İstek ve yanıt nesneleri, ilgili istemci yöntemiyle aynı adı paylaşır.
İstek nesnelerinin artık oluşturucuları vardır; 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 nasıl çalıştıkları gösterilmektedir.

Kimliğe göre bir yeri getirin

Belirli bir yerle ilgili ayrıntıları almak için fetchPlace() aracını kullanın. fetchPlace(), getPlaceById() ile benzer şekilde çalışır.

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

Bir Yer Kimliği ve döndürülecek Yer verilerini belirten alanların bir listesini belirten bir FetchPlaceRequest nesnesi ileterek fetchPlace() çağrısı yapı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.NAME);

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

FetchPlaceResponse işlemini tamamlamak 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 yer fotoğrafı getir

Bir yer fotoğrafı almak için fetchPhoto() uygulamasını kullanın. fetchPhoto(), bir yere ait fotoğrafları döndürür. Fotoğraf isteme kalıbı basitleştirilmiştir. Artık doğrudan Place nesnesinden PhotoMetadata isteğinde bulunabilirsiniz. Ayrı bir istek artık gerekli değildir. Fotoğrafların genişliği veya yüksekliği en fazla 1.600 piksel olabilir. fetchPhoto(), getPhoto() işlevine benzer şekilde çalışır.

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

fetchPlace() numaralı telefona bir görüşme ayarlayın. İsteğinize PHOTO_METADATAS alanını eklemeyi unutmayın:
```
List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);
```
Bir Yer nesnesi alın (bu örnekte fetchPlace() kullanılmıştır, ancak findCurrentPlace() öğesini de kullanabilirsiniz):
```
FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
```

FetchPlaceResponse içinde elde edilen Place öğesinden fotoğraf meta verilerini almak için OnSuccessListener ekleyin, ardından bit eşlem ve atıf metni almak için 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 bulun

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ığı en yüksek olan yerleri belirten bir PlaceLikelihood listesi döndürür. findCurrentPlace(), getCurrentPlace() ile benzer şekilde çalışır.

Kullanıcının cihazının geçerli konumunu öğrenmek için aşağıdaki adımları uygulayın:

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 İzinleri İsteme bölümüne bakın.

Döndürülecek yer verisi türlerinin listesiyle birlikte 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();

findCurrentPlace'i çağırın ve önce kullanıcının cihaz konumunu kullanma izni verdiğini doğrulamak için yanıtı 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();
  }

ÖNEMLİ! findCurrentPlace() şu alanları desteklemez: Place.Field.ADDRESS_COMPONENTS, Place.Field.OPENING_HOURS, Place.Field.PHONE_NUMBER ve Place.Field.WEBSITE_URI.

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() ile 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ı, bir kullanıcı aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda 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 kullanıcı bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu yapılabilir ve ardından bir yer seçimi yapılabilir. Bir oturum sona erdiğinde jeton artık geçerli olmaz; uygulamanızın her oturum için yeni bir jeton oluşturması gerekir.

Alan maskeleri

Yer ayrıntılarını döndüren yöntemlerde, her bir istekle ne tür yer verilerinin döndürüleceğini belirtmeniz gerekir. Bu, yalnızca gerçekten kullanacağınız verileri istediğinizden (ve bunlar için ödeme yaptığınızdan) emin olmanıza yardımcı olur.

Döndürülecek veri türlerini belirtmek için FetchPlaceRequest etiketinizde aşağıdaki örnekte gösterildiği gibi 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

ÖNEMLİ! findCurrentPlace() şu alanları desteklemez: Place.Field.ADDRESS_COMPONENTS, Place.Field.OPENING_HOURS, Place.Field.PHONE_NUMBER ve Place.Field.WEBSITE_URI.

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

Yer Seçici ve Otomatik Tamamlama güncellemeleri

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

Programlı 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ıyla ilgili hata işleme DEĞİŞTİRİLMEDİ).

Yer Seçici

Yer Seçici 29 Ocak 2019'da kullanımdan kaldırıldı. Bu hizmet, 29 Temmuz 2019'da devre dışı bırakılmıştı ve artık kullanılamayacak. Kullanım devam ederse bir hata mesajı gösterilir. Yeni SDK Yer Seçici'yi desteklemiyor.

Otomatik tamamlama widget'ları

Otomatik tamamlama widget'ları güncellendi:

Place öneki tüm sınıflardan kaldırıldı.
Oturum jetonları için destek eklendi. Widget, jetonları sizin için arka planda otomatik olarak yönetir.
Kullanıcı bir seçim yaptıktan sonra ne tür yer verileri döndürüleceğini seçebilmenizi sağlayan alan maskeleri için destek eklendi.

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

`AutocompleteFragment` yerleştir

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

Etkinliğinizin XML düzenine aşağıdaki örnekte gösterildiği gibi 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"
  />

Etkinliğe otomatik tamamlama widget'ını eklemek için aşağıdaki adımları uygulayın:

Uygulama bağlamını ve API anahtarınızı ileterek Places uygulamasını başlatın.
AutocompleteSupportFragment uygulamasını başlatın.
Almak istediğiniz yer verisi türlerini belirtmek için setPlaceFields() yöntemini çağırın.
Sonuçla ilgili bir işlem yapmak ve oluşabilecek hataları düzeltmek için bir PlaceSelectionListener ekleyin.

Aşağıdaki örnekte, bir etkinliğe otomatik tamamlama widget'ı ekleme işlemi 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 intent kullanma

Uygulama bağlamını ve API anahtarınızı ileterek Places uygulamasını başlatın
İstediğiniz PlaceAutocomplete modunu (tam ekran veya yer paylaşımlı) geçerek bir amaç oluşturmak için Autocomplete.IntentBuilder kullanın. Amaç, amacınızı tanımlayan bir istek kodu ileterek startActivityForResult işlevini çağırmalıdır.
Seçilen 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 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.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.
            }
        }
    }