Android için Yerler SDK'sındaki otomatik tamamlama hizmeti, kullanıcı arama sorgularına yanıt olarak yer tahminleri döndürür. Kullanıcı yazı yazarken otomatik tamamlama hizmeti; işletmeler, adresler, artı kodları ve önemli yerler gibi yerler için öneriler döndürür.
Aşağıdaki yöntemlerle uygulamanıza otomatik tamamlama ekleyebilirsiniz:
- Geliştirme süresinden tasarruf etmek ve tutarlı bir kullanıcı deneyimi sunmak 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 terimlerini girdiğinde widget, aralarından seçim yapabileceği tahmin edilen yerlerin bir listesini sunar. Kullanıcı bir seçim yaptığında, uygulamanız seçilen 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çeneğiniz vardır:
- 1. Seçenek:
AutocompleteSupportFragmentyerleştirin. - 2. Seçenek: Otomatik tamamlama etkinliğini başlatmak için bir intent kullanın.
1. Seçenek: Bir 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 dinleyici 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"
/>
- Parçanın varsayılan olarak sınırı 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.onActivityResultyöntemini ç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 bir yer döndürme işlemini gerçekleştirir. Aşağıdaki kod, parçaya bir referans oluşturmayı ve AutocompleteSupportFragment öğenize işleyici eklemeyi göstermektedir:
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 intent kullanma
Uygulamanızın farklı bir gezinme akışı kullanmasını istiyorsanız (örneğin, otomatik tamamlama deneyimini arama alanından değil bir simgeden tetiklemek için) uygulamanız bir amaç kullanarak otomatik tamamlamayı başlatabilir.
Niyet kullanarak otomatik tamamlama widget'ını başlatmak için aşağıdaki adımları uygulayın:
- İstenen
Autocompletemodunu geçerek niyet oluşturmak içinAutocomplete.IntentBuilderkodunu kullanın. - Niyeti 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ısı
registerForActivityResulttanımlayın.
Otomatik tamamlama amacı oluşturma
Aşağıdaki örnekte, otomatik tamamlama widget'ını amaç olarak başlatmak üzere bir amaç 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 niyet 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 sırasıyla her bir görüntüleme modu 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 sonucu aşağıdaki örnekte gösterildiği gibi işleyen bir registerForActivityResult() başlatıcı tanımlayın. Kullanıcı bir tahmin seçtiyse bu tahmin, sonuç nesnesindeki amaçta sunulur. Amaç Autocomplete.IntentBuilder tarafından oluşturulduğundan Autocomplete.getPlaceFromIntent() yöntemi, Place nesnesini bu nesneden çıkarabilir.
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");
}
});
Programlı bir şekilde yer tahminleri alma
Otomatik tamamlama widget'ının sağladığı kullanıcı arayüzüne alternatif olarak özel arama kullanıcı arayüzü oluşturabilirsiniz. Bunun için uygulamanızın programatik olarak yer tahminleri alması gerekir. Uygulamanız, PlacesClient.findAutocompletePredictions() yöntemini çağırarak ve aşağıdaki parametrelere sahip bir FindAutocompletePredictionsRequest nesnesi ileterek otomatik tamamlama API'sinden tahmin edilen yer adlarının ve/veya adreslerinin bir listesini alabilir:
- Zorunlu: Kullanıcı tarafından yazılan metni içeren bir
querydizesi. - Önerilen: Kullanıcı aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandıran bir
AutocompleteSessionToken. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. - Önerilen: Sonuçları belirtilen bölgeyle sınırlamak için enlem ve boylam sınırları belirten bir
RectangularBoundsnesnesi. - İsteğe bağlı: Sonuçların kısıtlanması gereken ülkeyi veya ülkeleri belirten bir veya daha fazla iki harfli ülke kodu (ISO 3166-1 Alfa-2).
İsteğe bağlı: Sonuçları belirtilen yer türüyle sınırlamak için kullanabileceğiniz bir
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 sonuçları netleştirmek için bu isteği kullanın.TypeFilter.ADDRESS- Yalnızca kesin adrese sahip 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:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES– YalnızcaLOCALITYveyaADMINISTRATIVE_AREA_LEVEL_3ile eşleşen sonuçları döndürür.
İsteğe bağlı: İsteğin kaynak konumunu belirten
LatLng.setOrigin()çağrısı yaptığınızda hizmet, yanıttaki her otomatik tamamlama tahmini için belirtilen kaynaktan metre (distanceMeters) cinsinden mesafeyi döndürür.
Yer türleri hakkında bilgi için yer türleri kılavuzunu inceleyin.
Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() için yapılan eksiksiz 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 bilinmeyen bir yer yoksa liste boş olabilir.
Tahmin edilen her bir yerle ilgili olarak, yer ayrıntılarını almak için 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, Fransa Anatole Caddesi, Paris, Fransa". Ayrıca bu yöntem,CharacterStylekullanarak açıklamanın aramayla eşleşen bölümlerini istediğiniz bir stille vurgulamanızı sağlar.CharacterStyleparametresi isteğe bağlıdır. Vurgulamaya ihtiyacınız yoksa null değerine ayarlayın.getPrimaryText(CharacterStyle), bir yeri açıklayan ana metni döndürür. Bu genellikle yerin adıdır. Örnekler: "Eyfel Kulesi" ve "123 Pitt Street".getSecondaryText(CharacterStyle), bir yer açıklamasının yan kuruluş metnini döndürür. Bu, örneğin otomatik tamamlama tahminlerini gösterirken ikinci bir satır olarak kullanılması yararlıdır. Örnekler: "Anatole Fransa, 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 vePlacenesnesini daha sonra tekrar almak için kullanabileceğiniz metinsel 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ı bölümüne bakın. Yer kimlikleri hakkında genel bilgi için Yer kimliğine genel bakış sayfasını inceleyin.getPlaceTypes(), bu yerle ilişkili yer türlerinin listesini döndürür.getDistanceMeters(), bu yer ile istekte belirtilen kaynak arasındaki düz çizgi mesafesini metre cinsinden döndürür.
Oturum jetonları
Oturum jetonları, kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırır. Oturum, kullanıcı bir sorgu yazmaya başladığında başlar ve bir yer seçtiğinde sona erer. Her oturumda birden fazla sorgu ve ardından tek 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. Tüm programatik otomatik tamamlama oturumları için oturum jetonları kullanmanızı öneririz (bir parça yerleştirdiğinizde veya amaç kullanarak otomatik tamamlamayı başlattığınızda API bunu otomatik olarak gerçekleştirir).
Android için Yerler SDK'sı her bir oturumu tanımlamak için bir AutocompleteSessionToken kullanır. Uygulamanız her yeni oturum başladığında yeni bir oturum jetonu iletmeli ve ardından kullanıcı tarafından seçilen yerin Yer Ayrıntılarını almak için bir sonraki fetchPlace() çağrısında aynı jetonu bir Yer Kimliği ile aktarmalıdır.
Oturum jetonları hakkında daha fazla bilgi edinin.
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 beş ülkeye göre filtreleyebilirsiniz. Bu kısıtlamaları otomatik tamamlama etkinliği, AutocompleteSupportFragment ve programatik otomatik tamamlama API'lerine uygulayabilirsiniz.
Sonuçları sınırlandırmak için aşağıdakileri yapın:
- Tanımlı bölge içindeki 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()çağrısı yapı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()yöntemini çağırın (örneğin,TypeFilter.ADDRESSbelirtilmesi yalnızca tam adrese sahip sonuçları döndürür). - Yalnızca en fazla beş belirtilen ülkedeki sonuçları döndürmek için
setCountries()numaralı telefonu arayın. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir.
Belirli bir bölgeyle ilgili yanlılık sonuçları
Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeye göre ağırlıklandırmak için RectangularBounds ileterek setLocationBias() yöntemini çağırın.
Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney şehrine göre ağırlıklandırmak için bir parça örneğinde setLocationBias() çağrısının yapılması 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ırlama
Otomatik tamamlama sonuçlarını belirli bir coğrafi bölgeyle kısıtlamak için RectangularBounds ileterek setLocationRestriction() yöntemini çağırın.
Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine göre ağırlıklandırmak için 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 rotaların tamamına uygulanır. Dikdörtgen sınırların dışında kalan sentetik sonuçlar, konum kısıtlamasıyla çakışan bir rotaya bağlı olarak döndürülebilir.
Sonuçları yer türlerine veya koleksiyon türüne göre filtreleme
Otomatik tamamlama isteğinden gelen sonuçları, yalnızca belirli bir yer türünü döndürmeleri için kısıtlayabilirsiniz. Yer Türleri bölümünde Tablo 1, 2 ve 3'te 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.
Tür veya tür koleksiyonu filtresi belirtmek için:
setTypesFilter()yöntemini çağırın ve Yer Türleri'nde gösterilen Tablo 1 ile Tablo 2'den beş adede kadar tür değeri belirtin. Tür değerleri, PlaceTypes'taki sabit değerlerle tanımlanır.setTypesFilter()yöntemini çağırın ve Yer Türleri'nde gösterilen Tablo 3'ten bir tür koleksiyonu belirtin. Koleksiyon değerleri PlaceTypes'taki sabit değerlerle tanımlanır.İstekte yalnızca Tablo 3'teki tek bir türe izin verilir. Tablo 3'ten bir değer belirtirseniz Tablo 1 veya Tablo 2'den bir değer belirtemezsiniz. Bunu yaparsanız bir hata oluşur.
Aşağıdaki kod örneği, AutocompleteSupportFragment öğesinde setTypesFilter() komutunu çağırır ve birden çok 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ği, 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ını gösterir.
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 adresli sonuçları döndüren bir filtre ayarlamak için IntentBuilder üzerinde setTypesFilter() çağrısı yapılması 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 filtrele
Otomatik tamamlama sonuçlarını en fazla beş ülkeye kadar filtrelemek için setCountries() numaralı telefonu arayarak ülke kodunu ayarlayın.
Ardından filtreyi bir parçaya veya amaca iletin. Ülkeler iki karakterli, ISO 3166-1 Alpha-2 uyumlu ülke kodu olarak iletilmelidir.
Aşağıdaki kod örneğinde, yalnızca belirtilen ülkelerdeki sonuçları döndüren bir filtre ayarlamak için AutocompleteSupportFragment üzerinde 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ı dahil olmak üzere Places API kullanımınız artık günlük maksimum istek sayısıyla (QPD) sınırlı değildir. Ancak aşağıdaki kullanım sınırları geçerliliğini korur:
- 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 tarafı ve sunucu tarafı isteklerinin toplamı olarak hesaplanır.
İlişkilendirmeleri uygulamanızda gösterme
- Uygulamanız otomatik tamamlama hizmetini programatik olarak kullanıyorsa kullanıcı arayüzünüz "Powered by Google" ilişkilendirmesi görüntülemeli veya Google markalı bir haritada görünmelidir.
- Uygulamanız otomatik tamamlama widget'ını kullanı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ır ve görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.
Daha fazla bilgi için ilişkilendirmeler hakkındaki dokümanlara bakın.
Otomatik Yer Tamamlama optimizasyonu
Bu bölümde, Otomatik Yer Tamamlama hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.
Aşağıda bazı genel yönergeler verilmiştir:
- Ç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ü kullanmaktır.
- Otomatik Yer Tamamlama veri alanlarıyla ilgili temel bilgileri en baştan geliştirin.
- Konuma ağırlık verme ve konum kısıtlama alanları isteğe bağlı olsa da otomatik tamamlama performansı üzerinde önemli etkileri olabilir.
- API hata döndürürse uygulamanızın sorunsuz bir şekilde eskimesini sağlamak için hata işlemeyi kullanın.
- Uygulamanızın seçim olmadığında işlemleri karşıladığından 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 yalnızca ihtiyacınız olan yer verisi alanlarını döndürmek için Yer Ayrıntıları ve Yer Otomatik Tamamlama widget'larında alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına fiyatlandırma'ya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'sı sonuçlarını istemek için Yer Otomatik Tamamlama özelliğinin programatik uygulamasını kullanmayı düşünün. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen İstek Başına fiyatlandırması, Oturum Başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
- Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntısı çağrısından daha düşük bir tutar için sağlar.
- Kullanıcılar ortalama dört veya daha az Otomatik Tamamlama tahmin isteği dahilinde bir otomatik tamamlama tahmini seçerse İstek Başına fiyatlandırma, Oturum Başına fiyatlandırmadan daha uygun maliyetli olabilir.
Başvurunuzda, seçilen tahminin adresi ve enlemi/boylamı dışında bir bilgi gerekiyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Uygulamanız; yer adı, işletmenin durumu veya çalışma saatleri gibi Yer Ayrıntıları gibi yer ayrıntıları gerektirdiğinden, Otomatik Yer Tamamlama uygulamanızda, hangi yer verisi alanlarına bağlı olarak 0, 017 ABD doları tutarında oturum başına ve geçerli Yer Veri SKU'ları'nın toplam maliyetine sahip olmak üzere bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik olarak bulunur) kullanılmalıdır33}{/14
Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca ihtiyacınız olan yer verisi alanlarını istediğinizden emin olmak için fields parametresini belirtmeyi unutmayın.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Tamamlama isteğinde kullanılan oturum jetonu
- İhtiyacınız olan yer verisi alanlarını belirten
fieldsparametresi
Hayır, yalnızca adres ve konum gerekir
Otomatik Yer Tamamlama kullanımınızın performansına bağlı olarak, Coğrafi Kodlama API'si, uygulamanız için Yer Ayrıntıları'ndan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Otomatik Tamamlama verimliliği, kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonu en iyi uygulamalarını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 bir Otomatik Yer Tamamlama tahmini seçmeden önce ortalama kaç karakter girdiğini analiz edin.
Kullanıcılarınız ortalama dört veya daha az istekte Otomatik Yer 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, istek başına 0,005 ABD doları karşılığında adresler ve enlem/boylam koordinatları sağlar. Dört Yer Otomatik Tamamlama - İstek Başına isteğinin maliyeti 0,01132 ABD dolarıdır. Dolayısıyla, dört isteğin ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısının toplam maliyeti 0,01632 ABD doları olur. Bu, oturum başına 0,017 ABD doları tutarındaki Oturum Başına Otomatik Tamamlama fiyatından daha düşüktür.1
Kullanıcılarınızın aradıkları tahmini daha da az karakterle bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.
Hayır
Yer Ayrıntıları ile oturuma dayalı Yer Otomatik Tamamlama özelliğini kullanın.
Kullanıcılar bir Otomatik Yer Tamamlama tahmini seçmeden önce yapılmasını beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama istekleriniz hem Otomatik Yer Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanmalıdır.Bu durumda, oturum başına toplam 0,017 ABD doları maliyet elde edilir.1
Widget uygulaması
Oturum yönetimi, JavaScript, Android veya iOS widget'larında otomatik olarak yerleşiktir. Bu, seçilen tahminle ilgili hem Otomatik Yer Tamamlama isteklerini hem de Yer Ayrıntısı isteğini içerir. Yalnızca Temel Veriler alanlarını istediğinizden emin olmak için fields parametresini belirtmeyi unutmayın.
Programatik uygulama
Yer Otomatik Tamamlama isteklerinizle bir oturum jetonu kullanın. Seçilen tahmin hakkında Yer Ayrıntıları isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Yer Otomatik Tamamlama yanıtındaki yer kimliği
- Otomatik Tamamlama isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veriler alanlarını belirten
fieldsparametresi
Otomatik Yer Tamamlama isteklerini ertelemeyi düşünün
Uygulamanızın daha az istek yapması için Otomatik Yer Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejilerden yararlanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Yer Tamamlama isteklerinde bulunmak, kullanıcı yedi karakter yazıp bir Coğrafi Kodlama API'si isteğinde bulunduğunuz bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 Otomatik Tamamlama + 0,005 Coğrafi Kodlama ABD doları).1
Geciken istekler, ortalama programatik isteğinizi dörde düşmesine neden oluyorsa Coğrafi Kodlama API'si ile performans gösteren Yer Otomatik Tamamlama uygulaması için yönergeleri uygulayabilirsiniz. Geciken isteklerin, her yeni tuş vuruşunda tahmin görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.
Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına 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ırması sayfasına bakın.
Performansla ilgili en iyi uygulamalar
Aşağıdaki yönergelerde Otomatik Yer Tamamlama performansını optimize etme yöntemleri 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 cihazından seçtiğinden, dil tercihi gerekli değildir.
- Otomatik Yer Tamamlama'yı bir harita içeriyorsa, konumu harita görüntü alanına göre taşıyabilirsiniz.
- 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 çağrısında orijinal kullanıcı girişini yeniden kullanın.
- Kullanıcının belirli bir yer için ad veya adrese göre sorgu girmesini bekliyorsanız Yer Bulma isteği kullanın. Yalnızca belirli bir bölgede sonuç bekleniyorsa konuma ağırlık vermeyi kullanın.
- Alt tesis adresleri için Otomatik Yer Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt tesis adresleri giren kullanıcılar. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Yer Tamamlama'da kısmi bir tahmin sağlar.
- New York'ta "23-30 29
Sorun giderme
Çeşitli hatalar oluşsa da uygulamanızda karşılaşabileceğiniz hataların büyük çoğunluğu genellikle yapılandırma hatalarından (örneğin, yanlış API anahtarı kullanılmış veya API anahtarı yanlış yapılandırılmıştır) veya kota hatalarından (uygulamanız kotasını aştı) 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 oluşan hatalar onActivityResult() geri çağırmasında döndürülür. Sonucun durum mesajını almak için
Autocomplete.getStatus() numaralı telefonu arayın.