Android için Yerler SDK'sındaki otomatik tamamlama hizmeti, kullanıcı arama sorgularına yanıt olarak tahminlerde bulunur. Kullanıcı yazarken otomatik tamamlama hizmeti; işletmeler, adresler, artı kodları ve önemli yerler gibi yerler için öneriler döndürür.
Otomatik tamamlamayı uygulamanıza aşağıdaki şekillerde ekleyebilirsiniz:
- Geliştirme zamanından tasarruf etmek ve tutarlı bir kullanıcı deneyimi sağlamak için otomatik tamamlama widget'ı ekleyin.
- Özelleştirilmiş bir kullanıcı deneyimi oluşturmak için yer tahminlerini programatik olarak alın.
Otomatik tamamlama widget'ı ekleme
Otomatik tamamlama widget'ı, yerleşik otomatik tamamlama işlevine sahip bir arama iletişim kutusudur. Kullanıcı arama terimleri girdiğinde widget, aralarından seçim yapabileceğiniz tahmini
yerlerin bir listesini sunar. Kullanıcı seçim yaptığında, uygulamanız seçili yerle ilgili ayrıntıları almak için kullanabileceği bir Place
örneği döndürülür.
Otomatik tamamlama widget'ını uygulamanıza eklemek için iki seçenek vardır:
- 1. Seçenek:
AutocompleteSupportFragment
yerleştirme - 2. Seçenek: Otomatik tamamlama etkinliğini başlatmak için bir amaç kullanın.
1. Seçenek: AutocompleteSupportFragment yerleştirme
Uygulamanıza AutocompleteSupportFragment
eklemek için aşağıdaki adımları uygulayın:
- Etkinliğinizin XML düzenine bir parça ekleyin.
- Etkinliğinize veya parçanıza bir işleyici ekleyin.
Bir etkinliğe AutocompleteSupportFragment ekleme
Bir etkinliğe AutocompleteSupportFragment
eklemek için XML düzenine yeni bir parça ekleyin. Örneğin:
<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"
/>
- Varsayılan olarak, parçanın kenarlığı veya arka planı yoktur. Tutarlı bir görsel görünüm sağlamak için parçayı CardView gibi başka bir düzen öğesinin içine yerleştirin.
- Otomatik tamamlama parçasını kullanıyorsanız ve
onActivityResult
öğesini geçersiz kılmanız gerekiyorsasuper.onActivityResult
öğesini çağırmanız gerekir. Aksi takdirde parça düzgün çalışmaz.
Bir etkinliğe PlaceSelectionListener ekleme
PlaceSelectionListener
, kullanıcının seçimine yanıt olarak yer döndürme işlemini gerçekleştirir. Aşağıdaki kod, parçaya başvuru oluşturmayı ve AutocompleteSupportFragment
öğenize bir işleyici eklemeyi gösterir:
Kotlin
// Initialize the AutocompleteSupportFragment. val autocompleteFragment = supportFragmentManager.findFragmentById(R.id.autocomplete_fragment) as AutocompleteSupportFragment // Specify the types of place data to return. autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME)) // Set up a PlaceSelectionListener to handle the response. autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener { override fun onPlaceSelected(place: Place) { // TODO: Get info about the selected place. Log.i(TAG, "Place: ${place.name}, ${place.id}") } override fun onError(status: Status) { // TODO: Handle the error. Log.i(TAG, "An error occurred: $status") } })
Java
// Initialize the AutocompleteSupportFragment. AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment) getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment); // Specify the types of place data to return. autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME)); // Set up a PlaceSelectionListener to handle the response. autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() { @Override public void onPlaceSelected(@NonNull Place place) { // TODO: Get info about the selected place. Log.i(TAG, "Place: " + place.getName() + ", " + place.getId()); } @Override public void onError(@NonNull Status status) { // TODO: Handle the error. Log.i(TAG, "An error occurred: " + status); } });
2. Seçenek: Otomatik tamamlama etkinliğini başlatmak için bir amaç kullanma
Uygulamanızın farklı bir gezinme akışı kullanmasını (örneğin, otomatik tamamlama deneyimini arama alanından değil bir simgeden tetiklemek için) istiyorsanız uygulamanız bir amaç kullanarak otomatik tamamlamayı başlatabilir.
Otomatik tamamlama widget'ını bir amaç kullanarak başlatmak için aşağıdaki adımları uygulayın:
- İstenen
Autocomplete
modunu ileterek intent oluşturmak içinAutocomplete.IntentBuilder
kullanın. - Amacı başlatmak ve sonuçta kullanıcının seçtiği yer tahminini işlemek için kullanılabilecek bir etkinlik sonucu başlatıcı
registerForActivityResult
tanımlayın.
Otomatik tamamlama amacı oluşturun
Aşağıdaki örnekte, otomatik tamamlama widget'ını bir amaç olarak başlatma niyeti oluşturmak için Autocomplete.IntentBuilder
kullanılmaktadır:
Kotlin
// Set the fields to specify which types of place data to // return after the user has made a selection. val fields = listOf(Place.Field.ID, Place.Field.NAME) // Start the autocomplete intent. val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .build(this) startAutocomplete.launch(intent)
Java
// Set the fields to specify which types of place data to // return after the user has made a selection. 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); startAutocomplete.launch(intent);
Otomatik tamamlama widget'ını başlatmak için bir intent kullanırken yer paylaşımlı veya tam ekran görüntüleme modları arasından seçim yapabilirsiniz. Aşağıdaki ekran görüntülerinde her bir görüntüleme modu sırasıyla gösterilmektedir:
Amaç sonucu için bir geri çağırma kaydedin
Kullanıcı bir yer seçtiğinde bildirim almak için etkinliği başlatan ve aşağıdaki örnekte gösterildiği gibi sonucu işleyen bir registerForActivityResult()
başlatıcı tanımlayın. Kullanıcı bir tahmin seçtiyse bu tahmin, sonuç nesnesinde yer alan amaçta iletilir. Amaç Autocomplete.IntentBuilder
tarafından derlendiği için Autocomplete.getPlaceFromIntent()
yöntemi, Yer nesnesini bu öğeden ayıklayabilir.
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == Activity.RESULT_OK) { val intent = result.data if (intent != null) { val place = Autocomplete.getPlaceFromIntent(intent) Log.i( TAG, "Place: ${place.name}, ${place.id}" ) } } else if (result.resultCode == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete") } }
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}"); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } });
Yer tahminlerini programatik olarak alma
Otomatik tamamlama widget'ının sağladığı kullanıcı arayüzüne alternatif olarak özel bir arama kullanıcı arayüzü oluşturabilirsiniz. Bunun için uygulamanızın yer tahminlerini programatik olarak alması gerekir. Uygulamanız, aşağıdaki parametrelere sahip bir FindAutocompletePredictionsRequest
nesnesi ileterek PlacesClient.findAutocompletePredictions()
yöntemini çağırarak otomatik tamamlama API'sinden tahmini yer adlarının ve/veya adreslerinin bir listesini alabilir:
- Zorunlu: Kullanıcının yazdığı metni içeren bir
query
dizesi. - Önerilen:
AutocompleteSessionToken
, faturalandırma amacıyla bir kullanıcı aramasının sorgu ve seçim aşamalarını ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve kullanıcı bir yer seçtiğinde sona erer. - Önerilen: Sonuçları belirtilen bölgeyle sınırlamak için enlem ve boylam sınırlarını belirten bir
RectangularBounds
nesnesi. - İsteğe bağlı: Sonuçların kısıtlanması gereken ülke veya ülkeleri belirten bir veya daha fazla iki harfli ülke kodu (ISO 3166-1 Alpha-2).
İsteğe bağlı: Sonuçları belirtilen yer türüyle kısıtlamak için kullanabileceğiniz
TypeFilter
. Aşağıdaki yer türleri desteklenir:TypeFilter.GEOCODE
– İşletmeler yerine yalnızca coğrafi kodlama sonuçlarını döndürür. Belirtilen konumun belirsiz olabileceği durumlarda sonuçları netleştirmek için bu isteği kullanın.TypeFilter.ADDRESS
– Yalnızca tam adres içeren otomatik tamamlama sonuçlarını döndürür. Kullanıcının tam olarak belirtilmiş bir adresi aradığını biliyorsanız bu türü kullanın.TypeFilter.ESTABLISHMENT
– Yalnızca işletme olan yerleri döndürür.TypeFilter.REGIONS
– Yalnızca aşağıdaki türlerden biriyle eşleşen yerleri döndürür:LOCALITY
SUBLOCALITY
POSTAL_CODE
COUNTRY
ADMINISTRATIVE_AREA_LEVEL_1
ADMINISTRATIVE_AREA_LEVEL_2
TypeFilter.CITIES
– YalnızcaLOCALITY
veyaADMINISTRATIVE_AREA_LEVEL_3
ile eşleşen sonuçları döndürür.
İsteğe bağlı: İsteğin kaynak konumunu belirten bir
LatLng
.setOrigin()
çağrısı yaptığınızda hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen kaynaktan uzaklığı metre (distanceMeters
) cinsinden döndürür.
Yer türleri hakkında bilgi için yer türleri kılavuzuna bakın.
Aşağıdaki örnekte, PlacesClient.findAutocompletePredictions()
için yapılan tam bir çağrı gösterilmektedir.
Kotlin
// 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()). val token = AutocompleteSessionToken.newInstance() // Create a RectangularBounds object. val bounds = RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) // Use the builder to create a FindAutocompletePredictionsRequest. val request = FindAutocompletePredictionsRequest.builder() // Call either setLocationBias() OR setLocationRestriction(). .setLocationBias(bounds) //.setLocationRestriction(bounds) .setOrigin(LatLng(-33.8749937, 151.2041382)) .setCountries("AU", "NZ") .setTypesFilter(listOf(PlaceTypes.ADDRESS)) .setSessionToken(token) .setQuery(query) .build() placesClient.findAutocompletePredictions(request) .addOnSuccessListener { response: FindAutocompletePredictionsResponse -> for (prediction in response.autocompletePredictions) { Log.i(TAG, prediction.placeId) Log.i(TAG, prediction.getPrimaryText(null).toString()) } }.addOnFailureListener { exception: Exception? -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") } }
Java
// 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) .setOrigin(new LatLng(-33.8749937, 151.2041382)) .setCountries("AU", "NZ") .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()); } });
API,
Task
içinde bir FindAutocompletePredictionsResponse
döndürür. FindAutocompletePredictionsResponse
, tahmin edilen yerleri temsil eden AutocompletePrediction
nesnelerinin bir listesini içerir. Sorguya ve filtre ölçütlerine karşılık gelen bilinen bir yer yoksa liste boş olabilir.
Tahmin edilen her yer için yer ayrıntılarını almak üzere aşağıdaki yöntemleri çağırabilirsiniz:
getFullText(CharacterStyle)
, bir yer açıklamasının tam metnini döndürür. Bu, birincil ve ikincil metnin bir kombinasyonudur. Örnek: "Eyfel Kulesi, Avenue Anatole France, Paris, Fransa". Buna ek olarak, bu yöntemCharacterStyle
kullanarak açıklamanın aramayla eşleşen bölümlerini istediğiniz bir stille vurgulamanıza olanak tanır.CharacterStyle
parametresi isteğe bağlıdır. Vurgulamaya ihtiyacınız yoksa bu değeri null olarak ayarlayın.getPrimaryText(CharacterStyle)
, bir yeri açıklayan ana metni döndürür. Bu genellikle yerin adıdır. Örnekler: "Eyfel Kulesi" ve "İstiklal Caddesi No:123".getSecondaryText(CharacterStyle)
, bir yer açıklamasının yan metnini döndürür. Bu, örneğin otomatik tamamlama tahminlerini gösterirken ikinci bir satır olarak yararlıdır. Örnekler: "Ameka Anatole France, Paris, Fransa" ve "Sidney, Yeni Güney Galler".getPlaceId()
, tahmin edilen yerin yer kimliğini döndürür. Yer kimliği, bir yeri benzersiz şekilde tanımlayan vePlace
nesnesini daha sonra tekrar almak için kullanabileceğiniz metin biçimli bir tanımlayıcıdır. Android için Yerler SDK'sındaki yer kimlikleri hakkında daha fazla bilgi için Yer Ayrıntıları'na bakın. Yer kimlikleri hakkında genel bilgi için Yer Kimliğine genel bakış sayfasına bakın.getPlaceTypes()
, bu yerle ilişkili yer türlerinin listesini döndürür.getDistanceMeters()
, bu yer ile istekte belirtilen kaynak arasındaki mesafeyi metre cinsinden döndürür.
Oturum jetonları
Oturum jetonları, faturalandırma amacıyla bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını ayrı bir oturumda gruplandırır. 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 bulunabilir ve ardından tek bir yer seçimi yapılabilir. Bir oturum sonlandırıldıktan sonra jeton artık geçerli olmaz. Uygulamanızın her oturum için yeni bir jeton oluşturması gerekir. Tüm programatik otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz (bir parçayı yerleştirdiğinizde veya bir intent kullanarak otomatik tamamlama başlattığınızda API bunu otomatik olarak yapar).
Android için Yerler SDK'sı her oturumu tanımlamak için bir AutocompleteSessionToken
kullanır. Uygulamanız her yeni oturumun başlangıcında yeni bir oturum jetonu iletmeli, ardından kullanıcı tarafından seçilen yerin Yer Ayrıntılarını almak için fetchPlace()
'e yapılan sonraki çağrıda bir Yer Kimliği ile birlikte aynı jetonu iletmelidir.
Oturum jetonları hakkında daha fazla bilgi
Otomatik tamamlama sonuçlarını sınırla
Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle sınırlandırabilir ve/veya sonuçları bir veya daha fazla yer türüne ya da en fazla beş ülkeye göre filtreleyebilirsiniz. Bu kısıtlamaları otomatik tamamlama etkinliğine, AutocompleteSupportFragment
ve programatik otomatik tamamlama API'lerine uygulayabilirsiniz.
Sonuçları sınırlamak için aşağıdakileri yapın:
- Tanımlanan bölge dahilindeki sonuçları tercih etmek için
setLocationBias()
yöntemini çağırın (tanımlanan bölgenin dışından bazı sonuçlar yine de döndürülebilir). - Yalnızca tanımlanan bölgedeki sonuçları göstermek için
setLocationRestriction()
yöntemini çağırın (yalnızca tanımlanan bölgedeki sonuçlar döndürülür). - Yalnızca belirli bir yer türüne uygun sonuçları döndürmek için
setTypesFilter()
komutunu çağırın (örneğin,TypeFilter.ADDRESS
belirtildiğinde yalnızca tam adresli sonuçlar döndürülür). - Yalnızca en fazla beş ülke içindeki sonuçları döndürmek için
setCountries()
numaralı telefonu arayın. Ülkeler iki karakterlik, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.
Belirli bir bölge için yanlı sonuçlar
Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre etkilemek için RectangularBounds
ileterek setLocationBias()
komutunu çağırın.
Aşağıdaki kod örneğinde, otomatik tamamlama önerilerinin Avustralya, Sidney'in bir bölgesine göre şekillendirilmesi için parça örneğinde setLocationBias()
çağrısı gösterilmektedir.
Kotlin
autocompleteFragment.setLocationBias( RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) )
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
Sonuçları belirli bir bölgeyle sınırlandırın
Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle kısıtlamak için bir RectangularBounds
ileterek setLocationRestriction()
komutunu çağırın.
Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine göre etkilemek için bir parça örneğinde setLocationRestriction()
çağrısı gösterilmektedir.
Kotlin
autocompleteFragment.setLocationRestriction( RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) )
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
Not: Bu kısıtlama yalnızca tüm rotalara uygulanır. Dikdörtgen sınırların dışında bulunan yapay sonuçlar, konum kısıtlamasıyla çakışan bir rotaya göre döndürülebilir.
Sonuçları yer türlerine veya koleksiyon türüne göre filtreleyin
Otomatik tamamlama isteğindeki sonuçları, yalnızca belirli bir yer türünü döndürecek şekilde kısıtlayabilirsiniz. Yer Türleri'ndeki 1, 2 ve 3. Tablolar'da listelenen yer türlerini veya bir tür koleksiyonunu kullanarak bir filtre belirtin. Hiçbir şey belirtilmezse tüm türler döndürülür.
Otomatik tamamlama sonuçlarını filtrelemek için setTypesFilter()
çağrısı yaparak filtreyi ayarlayın.
Bir tür veya tür koleksiyon filtresi belirtmek için:
setTypesFilter()
yöntemini çağırın ve Yer Türleri'nde gösterilen Tablo 1 ve Tablo 2'den en fazla beş tür değeri belirtin. Tür değerleri, PlaceTypes içindeki sabitlerle tanımlanır.setTypesFilter()
yöntemini çağırın ve Yer Türleri bölümünde gösterilen Tablo 3'ten bir tür koleksiyonu belirtin. Koleksiyon değerleri, PlaceTypes içindeki sabitlerle tanımlanır.İstekte Tablo 3'ten yalnızca bir türe izin verilir. Tablo 3'ten bir değer belirtirseniz Tablo 1'den veya Tablo 2'den değer belirtemezsiniz. Aksi takdirde bir hata oluşur.
Aşağıdaki kod örneği, AutocompleteSupportFragment
üzerinde setTypesFilter()
yöntemini çağırır ve birden fazla tür değeri belirtir.
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
Aşağıdaki kod örneğinde, bir tür koleksiyonu belirterek yalnızca kesin adrese sahip sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment
üzerinde setTypesFilter()
çağrısı gösterilmektedir.
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
Aşağıdaki kod örneğinde, bir tür koleksiyonu belirterek yalnızca kesin adrese sahip sonuçları döndüren bir filtre ayarlamak için IntentBuilder
üzerinde setTypesFilter()
çağrısı gösterilmektedir.
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(listOf(PlaceTypes.ADDRESS)) .build(this)
Java
Intent intent = new Autocomplete.IntentBuilder( AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS)) .build(this);
Sonuçları ülkeye göre filtreleyin
Otomatik tamamlama sonuçlarını en fazla beş ülkeye göre filtrelemek için
setCountries()
numarasını arayarak ülke kodunu ayarlayın.
Ardından filtreyi bir parçaya veya amaca iletin. Ülkeler iki karakterlik, ISO 3166-1 Alfa-2 uyumlu ülke kodu olarak iletilmelidir.
Aşağıdaki kod örneğinde, yalnızca belirtilen ülkeler içindeki sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment
için setCountries()
çağrısı gösterilmektedir.
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Java
autocompleteFragment.setCountries("AU", "NZ");
Kullanım sınırları
Android için Yerler SDK'sı da dahil olmak üzere Places API kullanımınız artık günlük maksimum istek sayısı (QPD) ile sınırlı değil. Ancak aşağıdaki kullanım sınırları geçerli olmaya devam eder:
- Hız sınırı 6.000 QPM'dir (dakika başına istek sayısı). Aynı projenin kimlik bilgilerini kullanan tüm uygulamalar için istemci taraflı ve sunucu tarafı isteklerin toplamı olarak hesaplanır.
İlişkilendirmeleri uygulamanızda gösterme
- Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüzde "Google tarafından desteklenmektedir" ilişkilendirmesi ya da Google markalı bir haritada yer alması gerekir.
- Uygulamanızda otomatik tamamlama widget'ı kullanılıyorsa başka bir işlem yapmanız gerekmez (varsayılan olarak gerekli ilişkilendirme gösterilir).
- Kimliğe göre bir yer aldıktan sonra ek yer bilgileri alıp görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.
Daha fazla bilgi için ilişkilendirmeler hakkındaki belgeleri inceleyin.
Yer Otomatik Tamamlama optimizasyonu
Bu bölümde Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Bazı genel kurallar şunlardır:
- Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu, Maps JavaScript API Otomatik tamamlama widget'ı, Android için Yerler SDK'sı Otomatik tamamlama widget'ı veya iOS için Yerler SDK'sı Otomatik tamamlama kullanıcı arayüzü kontrolü'nü kullanmaktır
- Otomatik Yer Tamamlama veri alanları hakkında en baştan bilgi edinin.
- Konuma ağırlık verme ve konum kısıtlaması alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
- API'nin hata döndürdüğü durumlarda uygulamanızın sorunsuz şekilde geri çekildiğinden emin olmak için hata işlemeyi kullanın.
- Uygulamanızın seçim yapılmadığında bunu işlendiğinden ve kullanıcılara devam etmeleri için bir yol sunduğundan emin olun.
Maliyet optimizasyonuyla ilgili en iyi uygulamalar
Temel maliyet optimizasyonu
Otomatik Yer Tamamlama hizmetini kullanma maliyetini optimize etmek için, Yer Ayrıntıları ve Otomatik Yer Tamamlama widget'larındaki alan maskelerini kullanarak yalnızca ihtiyacınız olan yer verisi alanlarını döndürün.
Gelişmiş maliyet optimizasyonu
İstek Başına Fiyatlandırma'ya erişmek ve seçilen yer hakkında Yer Ayrıntıları yerine Coğrafi Kodlama API'si sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik olarak uygulanmasını göz önünde bulundurun. Aşağıdaki koşulların her ikisi de karşılanırsa İstek Başına Fiyatlandırma, Geocoding API ile eşleştirilen Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
- Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyaç duyarsanız Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir ücret karşılığında sunar.
- Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmin isteği içinde bir otomatik tamamlama tahmini seçerse, İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
Uygulamanız, seçilen tahminin adresi ve enlem/boylam dışında herhangi bir bilgi gerektiriyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gerektirdiğinden, Yer Otomatik Tamamlama özelliği programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunan bir oturum jetonu (programatik, Android ya da iOS widget'larında yerleşik) kullanmalıdır.Bunun için toplam maliyet 0, 017 ABD doları (oturum başına ve geçerli Yer Verileri SKU'ları yer verileri SKU'ları olmalıdır{/15).
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak eklenir. Buna hem otomatik Yer Tamamlama istekleri hem de seçilen tahmindeki Yer Ayrıntısı isteği dahildir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields
parametresini belirttiğinizden emin olun.
Programatik uygulama
Otomatik Yer Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isterken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtındaki yer kimliği
- Otomatik Yer Tamamlama isteğinde kullanılan oturum jetonu
- İhtiyacınız olan yer verisi alanlarını belirten
fields
parametresi
Hayır, yalnızca adres ve konum gerekiyor
Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak Coğrafi Kodlama API'sı, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Otomatik Tamamlama verimliliği, hangi kullanıcıların giriş yaptığına, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların uygulanıp uygulanmadığına bağlı olarak değişiklik gösterir.
Aşağıdaki soruyu yanıtlamak için, bir kullanıcının uygulamanızda Yer Otomatik Tamamlama tahmini seçmeden önce ortalama kaç karakter yazdığını analiz edin.
Kullanıcılarınız ortalama olarak dört veya daha az istekte Yer Otomatik Tamamlama tahminini seçiyor mu?
Evet
Otomatik Yer Tamamlama özelliğini oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Coğrafi Kodlama API'sini çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını istek başına 0,005 ABD doları karşılığında sunar. Dört adet Otomatik Otomatik Tamamlama - İstek Başına istek göndermenin maliyeti 0,01132 ABD dolarıdır. Bu nedenle, seçilen yer tahminiyle ilgili dört isteğin toplam maliyeti ile birlikte Coğrafi Kodlama API'si çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu da oturum başına 0,017 ABD doları olan Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.1
Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performans en iyi uygulamalarından yararlanmayı düşünebilirsiniz.
Hayır
Yer Ayrıntıları ile oturuma dayalı Otomatik Yer Tamamlama özelliğini kullanın.
Bir kullanıcı Otomatik Yer Tamamlama tahminini seçmeden önce gerçekleştirmeyi beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmayı aştığından, Yer Otomatik Tamamlama özelliği hem Otomatik Yer Tamamlama istekleri hem de bununla ilişkili Yer Ayrıntısı isteği için toplam oturum başına 0,017 ABD doları olmak üzere bir oturum jetonu kullanmalıdır.1
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak eklenir. Buna hem otomatik Yer Tamamlama istekleri hem de seçilen tahmindeki Yer Ayrıntısı isteği dahildir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields
parametresini belirttiğinizden emin olun.
Programatik uygulama
Otomatik Yer Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isterken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtındaki yer kimliği
- Otomatik Yer Tamamlama isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veri alanlarını belirten
fields
parametresi
Otomatik Yer Tamamlama isteklerini ertelemeyi düşünün
Otomatik Yer Tamamlama isteğini, kullanıcı ilk üç veya dört karakteri yazana kadar ertelemek gibi stratejiler kullanarak uygulamanızın daha az istek göndermesini sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Tamamlama isteklerinde bulunmak, kullanıcı yedi karakteri yazdıktan sonra bir Coğrafi Kodlama API'si isteği gönderdiğiniz bir tahmin seçerse toplam maliyetin 0,01632 ABD doları (4 * 0,00283 ABD doları Otomatik Tamamlama + 0,005 ABD doları Coğrafi Kodlama) olacağı anlamına gelir.1
İstekleri ertelemek ortalama programatik isteğinizin dörtün altına düşmesine neden oluyorsa Geocoding API ile otomatik yer tamamlama performansı uygulama yönergelerinden yararlanabilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahmin görmeyi bekleyen kullanıcılar tarafından gecikme olarak algılanabileceğini unutmayın.
Kullanıcılarınızın aradıkları tahmini daha kısa sürede elde etmelerine yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
-
Burada listelenen maliyetler ABD doları cinsindendir. Tam fiyatlandırma bilgileri için lütfen Google Haritalar Platformu Faturalandırma sayfasına bakın.
Performansla ilgili en iyi uygulamalar
Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansının optimize edilmesi için izlenecek yöntemler açıklanmaktadır:
- Otomatik Yer Tamamlama uygulamanıza ülke kısıtlamaları, konuma ağırlık verme ve (programatik uygulamalar için) dil tercihi ekleyin. Widget'lar dil tercihlerini kullanıcının tarayıcısından veya mobil cihazdan seçtiği için widget'larda dil tercihi yapmanız gerekmez.
- Otomatik Yer Tamamlama'ya bir harita eşlik ediyorsa, konumu harita görünümüne göre değiştirebilirsiniz.
- Kullanıcının Otomatik Tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığından, daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
- Kullanıcının yalnızca adres bilgilerini girmesini bekliyorsanız Geocoding API'ye yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
- Kullanıcının belirli bir yer için ada veya adrese göre sorgu girmesini bekliyorsanız, Yer Bulma isteğini kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
- Şirket içi adresler için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerdeki (ör. Çekya, Estonya ve Litvanya) bina alt adreslerini giren kullanıcılar. Örneğin, Çekçedeki "Stroupežnického 3191/17, Praha" adresi, Yer Otomatik Tamamlama'da kısmi bir tahmin verir.
- New York City'de "23-30 29th St, Queens" veya Hawaii'deki Kauai Adası'nda "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleriyle adresler giren kullanıcılar.
Sorun giderme
Çok çeşitli hatalar ortaya çıkabilse de uygulamanızın karşılaşabileceği hataların çoğu genellikle yapılandırma hatalarından (ör. yanlış API anahtarının kullanılması veya API anahtarının yanlış yapılandırılmış olması) veya kota hatalarından (uygulamanızın kotasını aşması) kaynaklanır. Kotalar hakkında daha fazla bilgi için Kullanım Sınırları bölümüne bakın.
Otomatik tamamlama denetimleri kullanılırken ortaya çıkan hatalar onActivityResult()
geri çağırmasında döndürülür. Sonucun durum mesajını almak için Autocomplete.getStatus()
numaralı telefonu arayın.