Android için Yerler SDK'sındaki otomatik tamamlama hizmeti, kullanıcı arama sorgularına yanıt olarak tahminler döndürür. Kullanıcı yazdıkça otomatik tamamlama hizmeti işletmeler, adresler, artı kodları ve önemli yerler gibi yerlerle ilgili öneriler döndürür.
Otomatik tamamlamayı aşağıdaki yollarla uygulamanıza 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 terimleri girerken, widget'ta aralarından seçim yapabileceği
tahmin edilen yerlerin listesi sunulur. Kullanıcı 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.
Uygulamanıza otomatik tamamlama widget'ını eklemek için iki seçeneğiniz vardır:
- 1. Seçenek: Bir
AutocompleteSupportFragmentyerleştirin. - 2. Seçenek: Otomatik tamamlama etkinliğini başlatmak için bir amaç kullanın.
1. Seçenek: Otomatik Tamamlama Destek Parçası 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"
/>
- Varsayılan olarak parçada kenarlık 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.
Etkinliğe PlaceSelectionListener ekleme
PlaceSelectionListener, kullanıcının seçimine yanıt olarak bir yer döndürmeyi işler. Aşağıdaki kod, parçaya bir referans oluşturmayı ve AutocompleteSupportFragment öğenize işleyici eklemeyi göstermektedir:
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);
}
});
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")
}
})
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.
Intent kullanarak otomatik tamamlama widget'ını başlatmak için aşağıdaki adımları uygulayın:
- İstenen
Autocompletemodunu kullanarak amaç oluşturmak içinAutocomplete.IntentBuilderaracını 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ı
registerForActivityResulttanımlayın.
Otomatik tamamlama amacı oluşturma
Aşağıdaki örnekte, otomatik tamamlama widget'ını intent olarak başlatmak üzere bir intent oluşturmak için Autocomplete.IntentBuilder kullanılmıştır:
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);
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)
Otomatik tamamlama widget'ını başlatmak için bir intent kullanırken yer paylaşımlı veya tam ekran görüntü 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 kaydet
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 tahmin, sonuç nesnesinde bulunan amaçta sunulur. Amaç Autocomplete.IntentBuilder tarafından oluşturulduğundan Autocomplete.getPlaceFromIntent() yöntemi, Place nesnesini bundan çıkarabilir.
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");
}
});
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")
}
}
Programlı bir şekilde yer tahminlerini alma
Otomatik tamamlama widget'ı tarafından sağlanan kullanıcı arayüzüne alternatif olarak özel 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 tahmin edilen yer adları ve/veya adreslerin 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ını 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 Alpha-2) içerir.
İsteğe bağlı: Sonuçları belirtilen yer türüyle kısıtlamak 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 adres içeren otomatik tamamlama sonuçlarını döndürür. Kullanıcının tam olarak belirtilen 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 bir
LatLng.setOrigin()yöntemini çağırdığı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 rehberine bakın.
Aşağıdaki örnekte PlacesClient.findAutocompletePredictions() için yapılan tam bir çağrı gösterilmektedir.
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());
}
});
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}")
}
}
API,
Task içinde 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 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, Avenue Anatole France, Paris, Fransa". Ayrıca bu yöntem,CharacterStylekullanarak açıklamanın aramayla eşleşen bölümlerini istediğiniz bir stille vurgulamanıza olanak tanır.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 satır olarak yararlıdır. Örnekler: "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 metinsel bir tanımlayıcıdır. Bu tanımlayıcıyı daha sonraPlacenesnesini almak için kullanabilirsiniz. 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ış konusuna bakın.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ı, bir 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 olabilir. 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çayı yerleştirdiğinizde veya amaç kullanarak otomatik tamamlamayı başlattığınızda API bunu otomatik olarak halleder).
Android için Yerler SDK'sı her 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 yer için Yer Ayrıntılarını almak üzere bir sonraki fetchPlace() çağrısında yer kimliğiyle birlikte aynı jetonu iletmelidir.
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 ya da daha fazla yer türüne veya beş ülkeye göre filtreleyebilirsiniz. Bu kısıtlamaları otomatik tamamlama etkinliğine, AutocompleteSupportFragment ve programatik otomatik tamamlama API'lerine uygulayabilirsiniz.
Sonuçları kısıtlamak için aşağıdakileri yapın:
- Tanımlı bölge içindeki sonuçları tercih etmek için
setLocationBias()çağrısı yapı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()numaralı telefonu arayın (örneğin,TypeFilter.ADDRESSbelirtilmesi yalnızca tam adrese sahip sonuçları döndürür). - Yalnızca belirtilen en fazla beş ülkedeki sonuçları döndürmek için
setCountries()numaralı telefonu arayın. Ülkeler iki karakterden oluşan bir ISO 3166-1 Alfa-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 ayarlamak için RectangularBounds ileterek setLocationBias() yöntemini çağırın.
Aşağıdaki kod örneğinde, otomatik tamamlama önerilerini Avustralya'nın Sidney bölgesine ağırlık vermek için parça örneğinde setLocationBias() çağrısı gösterilmektedir.
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationBias(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Sonuçları belirli bir bölgeyle sınırlandırma
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 ağırlık vermek için parça örneğinde setLocationRestriction() çağrısının yapılması gösterilmektedir.
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
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 filtreleyin
Otomatik tamamlama isteğindeki sonuçları, yalnızca belirli bir yer türünü döndürmeleri için kısıtlayabilirsiniz. Yer Türleri sayfasındaki 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 filtreyi ayarlamak üzere setTypesFilter() çağrısı yapın.
Tür belirtmek veya koleksiyon filtresi türü için:
setTypesFilter()öğesini çağırın ve Yer Türleri üzerinde gösterilen Tablo 1 ve Tablo 2'den en fazla beş type değeri belirtin. Tür değerleri, PlaceTypes'taki sabit değerlerle tanımlanır.setTypesFilter()işlevini ç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'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 üzerinde setTypesFilter() işlevini çağırır ve birden çok tür değeri belirtir.
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
Kotlin
autocompleteFragment.setTypesFilter(listOf("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ının gösterilmektedir.
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
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ı gösterilmektedir.
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.build(this);
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(PlaceTypes.ADDRESS))
.build(this)
Sonuçları ülkeye göre filtrele
Otomatik tamamlama sonuçlarını beş ülkeye kadar filtrelemek için ülke kodunu ayarlamak üzere setCountries() numarasını arayın.
Ardından, filtreyi bir parçaya veya amaca iletin. Ülkeler iki karakterli, ISO 3166-1 Alfa-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() işlevinin çağrılması gösterilmektedir.
Java
autocompleteFragment.setCountries("AU", "NZ");
Kotlin
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 (QPD) sayısıyla 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ı). Bu değer, aynı projenin kimlik bilgilerini kullanan tüm uygulamalar için istemci taraflı ve sunucu tarafı isteklerin toplamı olarak hesaplanır.
Uygulamanızda ilişkilendirmeleri gösterin
- 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 (gerekli ilişkilendirme varsayılan olarak gösterilir).
- Kimliğe göre yer aldıktan sonra ek yer bilgilerini alır ve görüntülerseniz üçüncü taraf ilişkilendirmelerini de göstermeniz gerekir.
Daha fazla bilgi için atıflar ile ilgili belgeleri inceleyin.
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 Yerleştirme özelliğinin temel veri alanlarını daha baştan anlayın.
- Konuma ağırlık verme ve konum kısıtlama 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 bir şekilde bozulması için hata işlemeyi kullanın.
- Uygulamanızın hiçbir seçim olmadığında işlem yaptığından ve kullanıcılara devam etmek 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ındaki alan maskelerini kullanın.
Gelişmiş maliyet optimizasyonu
İstek Başına fiyatlandırmaya erişmek ve Yer Ayrıntıları yerine seçilen yerle ilgili Coğrafi Kodlama API'si sonuçlarını istemek için Otomatik Yer Tamamlama özelliğinin programatik olarak uygulanmasını deneyin. Aşağıdaki koşulların her ikisi de karşılandığında, Coğrafi Kodlama API'si ile eşleştirilen istek başına fiyatlandırma, oturum başına (oturuma dayalı) fiyatlandırmadan daha uygun maliyetlidir:
- Yalnızca kullanıcının seçtiği yerin enlem/boylam veya adresine ihtiyacınız varsa Coğrafi Kodlama API'si bu bilgileri Yer Ayrıntıları çağrısından daha az için sunar.
- 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.
Uygulamanızda, seçilen tahminin adresi ve enlemi/boylamı dışında herhangi bir bilgi gerekiyor mu?
Evet, daha fazla ayrıntı gerekiyor
Yer Ayrıntılarıyla otomatik yer tamamlama özelliğini oturuma dayalı olarak kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları gibi yer ayrıntıları gerektirdiğinden Otomatik Yer Tamamlama özelliğinin uygulamanızda, istekte bulunduğunuz yer verisi alanlarına bağlı olarak toplam 0, 017 ABD doları tutarında oturum başına 0, 017 ABD doları tutarında bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larında yerleşik) ile birlikte geçerli Yer Verileri SKU'ları kullanılmalıdır}{/14
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Seçilen tahminle ilgili hem Otomatik Yer Tamamlama istekleri hem de Yer Ayrıntısı isteği buna 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ı isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtındaki yer kimliği
- Otomatik Yerleştirme isteğinde kullanılan oturum jetonu
- İhtiyacınız olan yer verisi alanlarını belirten
fieldsparametresi
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'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 girdiği girişlere, uygulamanın kullanıldığı yere ve performans optimizasyonu en iyi uygulamalarının uygulanıp uygulanmadığına bağlı olarak değişir.
Aşağıdaki soruyu yanıtlamak için bir kullanıcının, uygulamanızda 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 Tamamlama özelliğini oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmininde Coğrafi Kodlama API'sini çağırın.
GeoCode API, istek başına 0,005 ABD doları karşılığında adresleri ve enlem/boylam koordinatlarını sağlar. Dört Otomatik Tamamlama - İstek Başına isteği yapmanın maliyeti 0,01132 ABD dolarıdır. Bu nedenle, dört isteğin ve seçilen yer tahminiyle ilgili bir GeoCode 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 düşük olur.1
Kullanıcılarınızın aradıkları tahmini daha da az karakterle elde etmelerine yardımcı olmak için performans en iyi uygulamalarından yararlanabilirsiniz.
Hayır
Yer Ayrıntılarıyla otomatik yer tamamlama özelliğini oturuma dayalı olarak kullanın.
Bir kullanıcı Otomatik Yer Tamamlama tahminini seçmeden önce yapmasını beklediğiniz ortalama istek sayısı, Oturum Başına fiyatlandırmanın maliyetini aştığından, Otomatik Yer Tamamlama istekleriniz hem Yer Otomatik Tamamlama istekleri hem de ilişkili Yer Ayrıntıları isteği için bir oturum jetonu kullanmalıdır.Bu durumda toplam maliyet oturum başına 0,017 ABD dolarıdır.1
Widget uygulaması
Oturum yönetimi JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Seçilen tahminle ilgili hem Otomatik Yer Tamamlama istekleri hem de Yer Ayrıntısı isteği buna 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ı isteğinde bulunurken aşağıdaki parametreleri ekleyin:
- Otomatik Yer Tamamlama yanıtındaki yer kimliği
- Otomatik Yerleştirme isteğinde kullanılan oturum jetonu
- Adres ve geometri gibi Temel Veriler alanlarını belirten
fieldsparametresi
Otomatik Yer Tamamlama isteklerini ertelemeyi değerlendirin
Otomatik Yer Tamamlama isteğini kullanıcı ilk üç veya dört karakteri yazana kadar erteleme gibi stratejiler benimseyerek uygulamanızın daha az istek yapmasını sağlayabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Otomatik Yer Tamamlama isteğinde bulunmak, kullanıcı yedi karakter girdikten sonra bir Coğrafi Kodlama API isteği yaptığınız bir tahmin seçerse toplam maliyet 0,01632 ABD doları olur (4 * İstek Başına 0,00283 ABD Doları Otomatik Tamamlama + 0,005 ABD Doları Coğrafi Kodlama).1
Geciken istekler, ortalama programatik isteğinizi dörde dörde düşürebilirse Coğrafi Kodlama API'siyle yüksek performans gösteren Otomatik Yer Tamamlama uygulaması için yönergeleri izleyebilirsiniz. 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 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ı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ı, yere 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 widget'larda dil tercihi gerekmez.
- Otomatik Yer Tamamlama bir haritayla birlikte veriliyorsa, konumu harita görünümüne göre yönlendirebilirsiniz.
- Kullanıcının otomatik tamamlama tahminlerinden birini seçmediği durumlarda, genellikle bu tahminlerin 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 GeoKodlama API'sine yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
- Kullanıcının belirli bir yerle ilgili sorguları ada veya adrese göre 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 kuruluş adresleri için Otomatik Tamamlama desteğinin eksik olduğu ülkelerde (ör. Çekya, Estonya ve Litvanya) alt kuruluş adresleri giren kullanıcılar. Örneğin, Çekçe adres olan "Stroupežnického 3191/17, Praha", Otomatik Yer Tamamlama'da kısmi bir tahmin verir.
- New York City'de "23-30 29th St, Queens" gibi yol segmenti ön ekleriyle veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti önekleriyle adres giren kullanıcılar.
Sorun giderme
Çok çeşitli hatalar meydana gelse de uygulamanızın karşılaşabileceği hataların çoğu genellikle yapılandırma hatalarından (örneğin, yanlış API anahtarı kullanılmış veya API anahtarı yanlış yapılandırılmıştır) ya da 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 kontrolleri 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.