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 Places SDK for 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ğiniz açıklanmaktadır.

Android için Yerler SDK'sında Sürüm 2.6.0'ın üzerindeki ö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üncelleme yapmanızı önerir.

Neler değişti?

Başlıca 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ğlandı.
  • Tamamen yeni yöntemler mevcuttur.
  • Alan maskeleri artık yer ayrıntıları döndüren yöntemler için 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 kullanıma sunulmasıyla 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ünün taşınmasına yardımcı olmak amacıyla bir uyumluluk kitaplığı sunmuştur.

Bu uyumluluk kitaplığı, geliştiriciler 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ı. Geliştiriciler, bağımsız SDK'da yeni adları kullanmak için kodlarını taşıyabildiler. Sürüm 1.0'dan 2.6.0'a kadar yayınlanmış olan Android için Yerler SDK'sının her bir sürümünde, eşdeğer işlevi sağlamak üzere Yerler uyumluluk kitaplığının karşılık gelen bir sürümü yayınlandı.

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, Yerler uyumluluk kitaplığının son sürümüdür. Android için Yerler SDK'sındaki 2.6.0 sürümünden sonra özelliklere 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ümler için yeni özelliklere ve kritik hata düzeltmelerine erişmek amacıyla 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'ı kullanın:

  1. Ş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'

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

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

  2. 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ırı kullanarak:

          implementation 'com.google.android.libraries.places:places:2.7.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 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 bir derleme hatası görürseniz bu hataları çözmeyle ilgili bilgi için aşağıdaki bölümlere bakın.

Yeni Places SDK istemcisini ilk kullanıma hazırlama

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. Başka 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ı girildi.
    • Places API, Cloud Console'da etkinleştirilmemiş.
    • Hatalı anahtar kısıtlamaları olan bir API anahtarı sağlandı.
  • INVALID_REQUEST: İstek, eksik veya geçersiz bir bağımsız değişken nedeniyle geçersizdir.

  • 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 sağlamak üzere tasarlanan yepyeni yöntemler sunuyor. Yeni yöntemlerin tümü aşağıdakilere uyar:

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

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

Kimliği kullanarak bir yeri getirme

Belirli bir yer hakkında ayrıntılı bilgi edinmek için fetchPlace() simgesini kullanın. fetchPlace(), getPlaceById() ile 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 nesnesini ve döndürülecek Yer verilerini belirten bir alanların listesini 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 özelliğini işlemek 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ı getirin

Yer fotoğrafı çekmek için fetchPhoto() aracını kullanın. fetchPhoto() bir yerin fotoğraflarını döndürür. Fotoğraf isteği gönderme modeli basitleştirilmiştir. Artık doğrudan Place nesnesinden PhotoMetadata isteğinde bulunabilirsiniz. Artık ayrı bir istek gerekli değildir. Fotoğrafların genişliği veya yüksekliği en fazla 1600 piksel olabilir. fetchPhoto(), getPhoto() ile benzer şekilde çalışır.

Yer fotoğraflarını getirmek 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ılmıştır ancak findCurrentPlace() değerini de kullanabilirsiniz):

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();
    
  3. Elde edilen Place öğesinden FetchPlaceResponse meta verisini almak için bir OnSuccessListener ekleyin, ardından elde edilen fotoğraf meta verilerini kullanarak bit eşlem 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 bulunduğu yeri 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 büyük olasılıkla bulunduğu yerleri gösteren bir PlaceLikelihood listesi döndürür. findCurrentPlace(), getCurrentPlace() işlevine 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şim izni vermesi gerekir. Ayrıntılar için Uygulama İzinleri İ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ğırarak yanıtı ele alın ve önce 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() 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ı, 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ı 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 devamında tek bir yer seçilebilir. 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 ne tür yer verisi döndürüleceğini belirtmeniz gerekir. Bu, yalnızca gerçek anlamda 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 öğenizde bir Place.Field dizisi geçirin:

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

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 işlevi DEĞİŞTİRİLMEMİŞTİR).

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 bir hata mesajı alırsınız. Yeni SDK, Yer Seçici'yi desteklemez.

Widget'ları otomatik tamamla

Otomatik tamamlama widget'ları güncellendi:

  • Place ön eki tüm sınıflardan kaldırıldı.
  • Oturum jetonları için destek eklendi. Widget, arka planda jetonları sizin için otomatik olarak yönetir.
  • Kullanıcı bir seçim yaptıktan sonra hangi tür yer verilerinin 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ı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. 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"
      />
    
  2. Otomatik tamamlama widget'ını etkinliğe eklemek için şu adımları uygulayın:

    • Uygulama bağlamını ve API anahtarınızı ileterek Places öğesini başlatın.
    • AutocompleteSupportFragment başlatılıyor.
    • Almak istediğiniz yer verisi türlerini belirtmek için setPlaceFields() numaralı telefonu arayın.
    • Sonuçta yer alacak bir işlem yapmak için PlaceSelectionListener ekleyin ve oluşabilecek hataları giderin.

    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 bir niyet kullanın

  1. Uygulama bağlamını ve API anahtarınızı ileterek Places başlatılıyor
  2. Amaç oluşturmak için istediğiniz PlaceAutocomplete modunu (tam ekran veya yer paylaşımlı) kullanarak Autocomplete.IntentBuilder kullanın. Amaç, kimliğinizi tanımlayan bir istek kodu ileterek startActivityForResult kodunu çağırmalıdır.
  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 amacın 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 bir hata mesajı alırsınız. Yeni SDK, Yer Seçici'yi desteklemez.