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ç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 amacıyla projelerinizi nasıl güncelleyebileceğiniz gösterilmektedir.

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

Neler değişti?

Değişimin yaşandığı başlıca alanlar aşağıdaki gibidir:

  • 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 sunulmuştu. O zamandan beri, yeni Android için Yerler SDK'sına geçişi kolaylaştırmak için Yerler uyumluluk kitaplığı sağlanmıştır.
  • Yepyeni yöntemler mevcuttur.
  • Alan maskeleri, artık yer ayrıntılarını döndüren yöntemler için desteklenmektedir. Ne tür yer verilerinin döndürüleceğini belirtmek için alan maskeleri 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.

Rehber uyumluluk kitaplığı hakkında

Ocak 2019'da Android için 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ı olacak bir uyumluluk kitaplığı sağladı.

Bu uyumluluk kitaplığı, 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, geliştiriciler kodlarını bağımsız SDK'daki yeni adları kullanmak üzere kullanana kadar 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üne karşılık eşdeğer işlevler sağlamak ü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 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, Yer uyumluluğu kitaplığının son sürümüdür. Android için Yerler SDK'sı sürüm 2.6.0'dan sonraki ö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ünün üzerindeki sürümlerle ilgili yeni özelliklere ve önemli 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çiş yapmak üzere aşağıdaki Android için Yerler SDK'sını yükleme bölümünde yer alan 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.

Maven'i kullanarak Android için Yerler SDK'sını Android Studio projenize ekleyin:

  1. Şu anda Rehber 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çiş yapı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'

      Bu satırı kullanarak Android için Yerler SDK'sına geçiş yapın:

          implementation 'com.google.android.libraries.places:places:3.3.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ı oluşturun. Android için Yerler SDK'sına dönüştürme işleminiz nedeniyle yapı hataları görürseniz bu hataların çözümü ile ilgili bilgiler için aşağıdaki bölümlere bakın.

Yeni Yerler SDK'sı istemcisini başlatma

Aşağıdaki örnekte gösterildiği gibi yeni Yerler SDK'sı istemcisini 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 QPD sınırı yok.

Aşağıdaki durum kodları eklendi:

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

    • API anahtarı belirtilmedi.
    • Geçersiz bir API anahtarı girildi.
    • Places API, Cloud konsolunda etkinleştirilmedi.
    • Sağlanan anahtar kısıtlamaları yanlış olan bir API anahtarı.

  • INVALID_REQUEST: İstek, eksik veya geçersiz bir 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ış yepyeni yöntemleri sunuyor. Yeni yöntemlerin tümü aşağıdakilere uyar:

  • Uç noktalar artık get fiilini kullanmıyor.
  • İ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 iletilir.
  • Arabellekler artık kullanılmıyor.

Bu bölümde yeni yöntemler tanıtılmakta ve bunların nasıl çalıştığı gösterilmektedir.

Kimliğe göre bir yer getir

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

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

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

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

  2. FetchPlaceResponse 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

Bir yer fotoğrafı almak için fetchPhoto() simgesini 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. Bunun için ayrı bir istekte bulunmanıza gerek yoktur. Fotoğrafların genişliği veya yüksekliği maksimum 1.600 piksel olabilir. fetchPhoto(), getPhoto() ile benzer şekilde çalışır.

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

  1. fetchPlace() için arama ayarlayın. İsteğinize PHOTO_METADATAS alanını eklediğinizden emin olun:

    List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);

  2. Yer nesnesi alın (bu örnekte fetchPlace() kullanılmaktadır, ancak findCurrentPlace() öğesini de kullanabilirsiniz):

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

  3. FetchPlaceResponse içinde elde edilen Place sonucundan fotoğraf meta verilerini almak için OnSuccessListener ekleyin, ardından elde edilen fotoğraf meta verilerini kullanarak bit eşlem ve atıf 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 yeri bulma

Kullanıcının cihazının geçerli konumunu bulmak için findCurrentPlace() simgesini kullanın. findCurrentPlace(), kullanıcının cihazının bulunma olasılığının en yüksek olduğu yerleri gösteren PlaceLikelihood öğelerinin bir listesini döndürür. findCurrentPlace(), getCurrentPlace() ile benzer şekilde çalışır.

Kullanıcının cihazının geçerli 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ı, mevcut cihaz konumuna erişim izni vermelidir. Ayrıntılar için Uygulama İzni İsteme bölümüne bakın.

  2. Döndürülecek yer verisi türlerinin listesini de 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 yanıtı işleyin. Öncelikle kullanıcının cihaz konumunu kullanma izni verdiğini doğrulamak için bunu 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() simgesini kullanın. findAutocompletePredictions(), getAutocompletePredictions() ile benzer şekilde çalışır.

Aşağıdaki örnekte findAutocompletePredictions() işlevinin çağrılması 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ı, 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ı sorgu yazmaya başladığında başlar ve kullanıcı bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu bulunabilir ve ardından tek bir yer seçimi yapılabilir. 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, 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 öğenizde 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

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ı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ĞİŞTİRİLMEDİ).

Yer Seçici

Yer Seçici 29 Ocak 2019'da kullanımdan kaldırıldı. 29 Temmuz 2019'da kapatılmıştı ve artık kullanılamıyor. Kullanmaya devam ederseniz hata mesajı alırsınız. 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ı arka planda otomatik olarak sizin için yönetir.
  • Kullanıcı bir seçim yaptıktan sonra ne tür yer verilerinin döndürüleceğini seçmenizi sağlayan alan maskeleri desteği eklendi.

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

AutocompleteFragment yerleştirme

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 uygulamasını başlatın.
    • AutocompleteSupportFragment uygulamasını başlatın.
    • Almak istediğiniz yer verisi türlerini belirtmek için setPlaceFields() çağrısı yapın.
    • Sonuçla ilgili işlem yapmak ve oluşabilecek hataları gidermek için PlaceSelectionListener ekleyin.

    Aşağıdaki örnekte bir etkinliğe otomatik tamamlama widget'ının eklenmesi 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 bir intent kullan

  1. Uygulama bağlamını ve API anahtarınızı ileterek Places uygulamasını başlatın
  2. İstenen PlaceAutocomplete modunu (tam ekran veya yer paylaşımlı) geçirerek intent oluşturmak için Autocomplete.IntentBuilder kullanın. Niyetin, amacınızı tanımlayan bir istek kodu ileterek startActivityForResult çağrısı yapması gerekir.
  3. Seçilen yeri almak için onActivityResult geri çağırmasını geçersiz kılın.

Aşağıdaki örnekte, otomatik tamamlamayı başlatmak için bir niyetin nasıl kullanılacağı ve ardından sonucun nasıl işleneceği 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ıştı ve artık kullanılamıyor. Kullanmaya devam ederseniz hata mesajı alırsınız. Yeni SDK, Yer Seçici'yi desteklemiyor.