Özel arama önerileri ekleyin

Android arama iletişim kutusunu veya arama widget'ını kullanırken, uygulamanızdaki verilerden oluşturulan özel arama önerileri sağlayabilirsiniz. Örneğin, uygulamanız bir sözlükse kullanıcı sorgusunu girmeyi tamamlamadan önce sözlükten, arama alanına girilen metinle eşleşen kelimeleri önerebilirsiniz. Bu öneriler, kullanıcının ne istediğini etkili bir şekilde tahmin edebildiği ve buna anında erişim sağlayabildiği için değerlidir. Şekil 1'de, özel öneriler içeren bir arama iletişim kutusu örneği gösterilmektedir.

Özel öneriler sağladığınızda, bu önerileri sistem genelinde Hızlı Arama Kutusu'nda da kullanıma sunabilirsiniz. Böylece içeriğinize uygulamanızın dışından erişim sağlanır.

Özel öneriler eklemeden önce, uygulamanızdaki aramalar için Android arama iletişim kutusunu veya bir arama widget'ını uygulayın. Arama arayüzü oluşturma ve İçerik sağlayıcılar konularına bakın.

Temel bilgiler

Şekil 1. Özel arama önerileri içeren bir arama iletişim kutusunun ekran görüntüsü.

Kullanıcı özel bir öneri seçtiğinde sistem aranabilir etkinliğinize bir Intent gönderir. ACTION_SEARCH işlemiyle bir amaç gönderen normal arama sorgusunun aksine, ACTION_VIEW veya başka bir amaç işlemi kullanmak için özel önerilerinizi tanımlayabilir ve seçilen öneriyle alakalı verileri dahil edebilirsiniz. Sözlük örneğinde, kullanıcı bir öneriyi seçtiğinde uygulama, eşleşmeler için sözlükte arama yapmak yerine, kelimenin tanımını anında açabilir.

Özel öneriler sağlamak için aşağıdaki adımları uygulayın:

• Arama arayüzü oluşturma bölümünde açıklandığı gibi, temel bir aranabilir etkinlik uygulayın.
• Aranabilir yapılandırmayı özel öneriler sağlayan içerik sağlayıcı hakkındaki bilgilerle değiştirin.
• Önerileriniz için bir tablo oluşturun (ör. SQLiteDatabase) ve tabloyu gerekli sütunlarla biçimlendirin.
• Öneriler tablonuza erişimi olan bir içerik sağlayıcı oluşturun ve manifest dosyanızda sağlayıcıyı beyan edin.
• Kullanıcı bir öneriyi seçtiğinde gönderilecek Intent türünü (özel işlem ve özel veriler dahil) tanımlayın.

Android sistemi, arama iletişim kutusunu görüntülediği gibi arama önerilerinizi de görüntüler. Sistemin önerilerinizi alabileceği bir içerik sağlayıcıya ihtiyacınız var. İçerik sağlayıcının nasıl oluşturulacağını öğrenmek için İçerik sağlayıcılar bölümünü okuyun.

Sistem, etkinliğinizin aranabilir olduğunu belirlediğinde ve arama önerileri sağladığında, kullanıcı bir sorgu girdiğinde aşağıdaki prosedür gerçekleşir:

1. Sistem, arama sorgusu metnini (yani şimdiye kadar girilenleri) alır ve önerilerinizi yöneten içerik sağlayıcınıza bir sorgu gerçekleştirir.
2. İçerik sağlayıcınız, arama sorgusu metniyle alakalı tüm önerilere işaret eden bir Cursor döndürür.
3. Sistem, Cursor tarafından sağlanan önerilerin listesini görüntüler.

Özel öneriler gösterildikten sonra aşağıdakiler gerçekleşebilir:

• Kullanıcı başka bir harf girer veya sorguyu herhangi bir şekilde değiştirirse önceki adımlar tekrarlanır ve öneri listesi buna göre güncellenir.
• Kullanıcı aramayı yaparsa öneriler yoksayılır ve arama, normal ACTION_SEARCH amacı kullanılarak aranabilir etkinliğinize iletilir.
• Kullanıcı bir öneriyi seçerse aranabilir etkinliğinize niyet gönderilir. Niyet, uygulamanızın önerilen içeriği açabilmesi için özel bir işlem ve özel veriler içerir.

Aranabilir yapılandırmayı değiştirme

Özel önerilere destek eklemek için aşağıdaki örnekte gösterildiği gibi, aranabilir yapılandırma dosyanızdaki <searchable> öğesine android:searchSuggestAuthority özelliğini ekleyin:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Her bir öneriye eklediğiniz amacın türüne ve içerik sağlayıcınıza yönelik sorguları nasıl biçimlendirmek istediğinize bağlı olarak ek özelliklere ihtiyacınız olabilir. Diğer isteğe bağlı özellikler aşağıdaki bölümlerde ele alınmıştır.

İçerik sağlayıcı oluşturma

Özel önerilere yönelik bir içerik sağlayıcı oluşturmak için önce İçerik sağlayıcılar bölümüne bakın. İçerik sağlayıcı oluşturma hakkında bilgi edinin. Özel öneriler için içerik sağlayıcısı, diğer içerik sağlayıcılara benzer. Bununla birlikte, sağladığınız her öneri için Cursor içindeki ilgili satırda sistemin anladığı ve önerileri biçimlendirmek için kullandığı belirli sütunlar olmalıdır.

Kullanıcı, arama iletişim kutusuna veya arama widget'ına metin girdiğinde sistem, her harf girildiğinde query() numarasını arayarak içerik sağlayıcınızdan öneri ister. query() uygulamanızda, içerik sağlayıcınız öneri verilerinizi aramalı ve iyi öneri olduğunu belirlediği satırlara işaret eden bir Cursor döndürmelidir.

Özel öneriler için içerik sağlayıcı oluşturmayla ilgili ayrıntılar aşağıdaki iki bölümde açıklanmıştır:

Öneri sorgusunu işleme

Sistemin içerik sağlayıcınıza nasıl istek gönderdiği ve bunların nasıl ele alınacağı.

Öneri tablosu oluşturma

Sistemin her sorguyla birlikte döndürülen Cursor içinde beklediği sütunları tanımlama.

Öneri sorgusunu ele alın

Sistem, içerik sağlayıcınızdan öneri istediğinde içerik sağlayıcınızın query() yöntemini çağırır. Öneri verilerinizde arama yapmak ve alakalı olduğunu düşündüğünüz önerilere işaret eden bir Cursor döndürmek için bu yöntemi uygulayın.

Sistemin query() yönteminize aktardığı parametrelerin özetini aşağıda bulabilirsiniz:

uri

Her zaman aşağıdaki gibi biçimlendirilmiş bir içerik Uri:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Varsayılan davranış, sistemin bu URI'yı geçirmesi ve sorgu metnini buna eklemesidir:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Sondaki sorgu metni, URI kodlama kuralları kullanılarak kodlandığından, arama yapmadan önce metnin kodunu çözmeniz gerekebilir.

optional.suggest.path bölümü, yalnızca android:searchSuggestPath özelliğiyle aranabilir yapılandırma dosyanızda böyle bir yol belirlerseniz URI'ye dahil edilir. Yalnızca birden fazla aranabilir etkinlik için aynı içerik sağlayıcıyı kullanıyorsanız gereklidir. Bu durumda, öneri sorgusunun kaynağını netleştirin.

projection

Her zaman boş.

selection

Aranabilir yapılandırma dosyanızın android:searchSuggestSelection özelliğinde sağlanan değer. android:searchSuggestSelection özelliğini bildirmediyseniz null değerini girin. Aşağıdaki bölümde bu konu daha ayrıntılı şekilde ele alınmaktadır.

selectionArgs

Aranabilir yapılandırmanızda android:searchSuggestSelection özelliğini belirtirseniz arama sorgusunu dizinin ilk ve tek öğesi olarak içerir. android:searchSuggestSelection belirtmezseniz bu parametre null olur. Aşağıdaki bölümde bu konu daha ayrıntılı şekilde ele alınmaktadır.

sortOrder

Her zaman boş.

Sistem, arama sorgusu metnini size iki şekilde gönderebilir. Varsayılan yöntem, sorgu metninin uri parametresinde iletilen içerik URI'sının son yolu olarak eklenmesidir. Ancak, aranabilir yapılandırmanızın android:searchSuggestSelection özelliğine bir seçim değeri eklerseniz sorgu metni, selectionArgs dize dizisinin ilk öğesi olarak geçer. Bu iki seçenek aşağıda açıklanmıştır.

Sorguyu URI'da alma

Sorgu, varsayılan olarak uri parametresinin son segmenti olan Uri nesnesi olarak eklenir. Bu durumda sorgu metnini almak için aşağıdaki örnekte gösterildiği gibi getLastPathSegment() kullanın:

val query: String = uri.lastPathSegment.toLowerCase()

String query = uri.getLastPathSegment().toLowerCase();

Bu, kullanıcının girdiği sorgu metni olan Uri öğesinin son segmentini döndürür.

Sorguyu seçim bağımsız değişkenlerinde alma

URI kullanmak yerine, query() yönteminizin aramayı gerçekleştirmek için ihtiyaç duyduğu her şeyi alması daha mantıklı olabilir ve selection ve selectionArgs parametrelerinin uygun değerleri taşımasını isteyebilirsiniz. Bu durumda, android:searchSuggestSelection özelliğini SQLite seçim dizenizle aranabilir yapılandırmanıza ekleyin. Seçim dizesine, gerçek arama sorgusu için yer tutucu olarak bir soru işareti (?) ekleyin. Sistem, selection parametresi ve arama sorgusunu selectionArgs dizisindeki ilk öğe olarak seçim dizesiyle query() çağırır.

Örneğin, tam metin arama ifadesi oluşturmak için android:searchSuggestSelection özelliğini şu şekilde oluşturabilirsiniz:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Bu yapılandırmada, query() yönteminiz selection parametresini "word MATCH ?" olarak, selectionArgs parametresini de arama sorgusu olarak yayınlar. Bunları bir SQLite query() yöntemine ilettiğinizde ilgili bağımsız değişkenleri olarak sentezlenirler. Diğer bir deyişle, soru işareti sorgu metniyle değiştirilir. Öneri sorgularını bu şekilde alırsanız ve sorgu metnine joker karakterler eklemeniz gerekirse bunları selectionArgs parametresine ekleyin veya öne çıkarın. Çünkü bu değer tırnak içine alınır ve soru işaretinin yerine eklenir.

Önceki örnekte verilen başka bir özellik de android:searchSuggestIntentAction özelliğidir. Bu özellik, kullanıcı bir öneriyi seçtiğinde her niyetle gönderilen intent işlemini tanımlar. Bu konu, Öneriler için amaç belirtme bölümünde daha ayrıntılı olarak ele alınmaktadır.

Öneri tablosu oluşturma

Sisteme bir Cursor ile öneri döndürdüğünüzde, sistem her satırda belirli sütunların bulunmasını bekler. Öneri verilerinizi cihazdaki bir SQLite veritabanında, bir web sunucusundaki veritabanında veya cihaz ya da web'deki başka bir biçimde depolamanız fark etmeksizin, önerileri tabloda satır olarak biçimlendirin ve Cursor ile sunun.

Sistem birkaç sütunu anlar, ancak bunlardan yalnızca ikisi gereklidir:

_ID

Her öneri için benzersiz bir tam sayı satırı kimliği. Sistem, önerilerin ListView içinde sunulmasını gerektirir.

SUGGEST_COLUMN_TEXT_1

Öneri olarak sunulan dize.

Aşağıdaki sütunların tümü isteğe bağlıdır. Bunların çoğu, sonraki bölümlerde daha ayrıntılı şekilde ele alınmaktadır.

SUGGEST_COLUMN_TEXT_2

Bir dize. Cursor bu sütunu içeriyorsa tüm öneriler iki satırlı biçimde sağlanır. Bu sütundaki dize, birincil öneri metninin altında, ikinci ve daha küçük bir metin satırı olarak görüntülenir. İkincil metin olmadığını belirtmek için boş veya değer atanmamış olabilir.

SUGGEST_COLUMN_ICON_1

Çekilebilir bir kaynak, içerik veya dosya URI'si dizesi. Cursor bu sütunu içeriyorsa tüm öneriler, sol tarafında çekilebilir simgeyle birlikte simge artı metin biçiminde sağlanır. Bu değer, bu satırda simge olmadığını göstermek için boş veya sıfır olabilir.

SUGGEST_COLUMN_ICON_2

Çekilebilir bir kaynak, içerik veya dosya URI'si dizesi. Cursor bu sütunu içeriyorsa tüm öneriler, sağ tarafta simge olacak şekilde simge artı metin biçiminde sağlanır. Bu değer, bu satırda simge olmadığını göstermek için boş veya sıfır olabilir.

SUGGEST_COLUMN_INTENT_ACTION

Amaç işlemi dizesi. Bu sütun varsa ve verilen satırda bir değer içeriyorsa önerinin amacı oluşturulurken burada tanımlanan işlem kullanılır. Öğe sağlanmazsa işlem, aranabilir yapılandırmanızdaki android:searchSuggestIntentAction alanından gerçekleştirilir. İşleminiz tüm öneriler için aynıysa işlemi android:searchSuggestIntentAction ile belirtmek ve bu sütunu atlamak daha iyi olur.

SUGGEST_COLUMN_INTENT_DATA

Veri URI'si dizesi. Bu sütun varsa ve belirtilen satırda bir değer içeriyorsa bu veriler önerinin amacı oluşturulurken kullanılır. Öğe sağlanmamışsa veriler, aranabilir yapılandırmanızdaki android:searchSuggestIntentData alanından alınır. İki kaynak da sağlanmazsa amacın veri alanı null olur. Verileriniz tüm öneriler için aynıysa veya sabit bir parça ve belirli bir kimlik kullanılarak açıklanabiliyorsa bu sütunu android:searchSuggestIntentData kullanarak belirtmek ve bu sütunu hariç tutmak daha verimli olur.

SUGGEST_COLUMN_INTENT_DATA_ID

URI yolu dizesi. Bu sütun varsa ve belirtilen satırda bir değer içeriyorsa amaçtaki veri alanına "/" işaretiyle birlikte bu değer eklenir. Bunu yalnızca aranabilir yapılandırmadaki android:searchSuggestIntentData özelliği tarafından belirtilen veri alanı zaten uygun bir temel dizeye ayarlanmışsa kullanın.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

Rastgele veriler. Bu sütun varsa ve belirli bir satırda bir değer içeriyorsa bu, önerinin amacı oluşturulurken kullanılan ek verilerdir. Sağlanmazsa amacın ekstra veri alanı null olur. Bu sütun, önerilerin amacın EXTRA_DATA_KEY anahtarına ekstra olarak dahil edilen ek veriler sağlamasına olanak tanır.

SUGGEST_COLUMN_QUERY

Bu sütun varsa ve söz konusu öğe belirtilen satırda bulunuyorsa bu veriler önerinin sorgusu oluşturulurken kullanılan verilerdir ve amacın QUERY anahtarına ekstra olarak dahil edilir. Önerinin işlemi ACTION_SEARCH ise bu gereklidir, aksi takdirde isteğe bağlıdır.

SUGGEST_COLUMN_SHORTCUT_ID

Yalnızca Hızlı Arama Kutusu için öneriler sağlarken kullanılır. Bu sütun, bir arama önerisinin kısayol olarak depolanmasının gerekip gerekmediğini ve doğrulanması gerekip gerekmediğini belirtir. Kısayollar genellikle kullanıcı Hızlı Arama Kutusu'ndaki bir öneriye dokunduğunda oluşturulur. Eksikse sonuç kısayol olarak depolanır ve hiçbir zaman yenilenmez. SUGGEST_NEVER_MAKE_SHORTCUT olarak ayarlanırsa sonuç kısayol olarak depolanmaz. Aksi takdirde, SUGGEST_URI_PATH_SHORTCUT ile güncel bir öneri olup olmadığını tekrar kontrol etmek için kısayol kimliği kullanılır.

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

Yalnızca Hızlı Arama Kutusu için öneriler sağlarken kullanılır. Bu sütunda, bu önerinin kısayolu Hızlı Arama Kutusu'nda yenilenirken SUGGEST_COLUMN_ICON_2 simgesi yerine bir değer değiştiricinin gösterilmesi gerektiğini belirtir.

Bu sütunların çoğu, sonraki bölümlerde daha ayrıntılı olarak ele alınmaktadır.

Öneriler için amaç beyan etme

Kullanıcı, arama iletişim kutusunun veya widget'ın altında görüntülenen listeden bir öneri seçtiğinde, sistem aranabilir etkinliğinize özel bir Intent gönderir. Amaç için işlemi ve verileri tanımlamanız gerekir.

Amaç işlemini bildirin

Özel öneriler için en yaygın intent işlemi ACTION_VIEW'dir. Bu işlem; bir kelimenin tanımı, kişinin iletişim bilgileri veya web sayfası gibi bir öğeyi açmak istediğinizde uygundur. Ancak intent işlemi başka herhangi bir işlem olabilir ve her öneride farklı olabilir.

Tüm önerilerin aynı intent işlemini kullanmasını isteyip istemediğinize bağlı olarak işlemi iki şekilde tanımlayabilirsiniz:

• Tüm öneriler için işlemi tanımlamak üzere aşağıdaki örnekte gösterildiği gibi, aranabilir yapılandırma dosyanızın android:searchSuggestIntentAction özelliğini kullanın:

  <?xml version="1.0" encoding="utf-8"?>
  <searchable xmlns:android="http://schemas.android.com/apk/res/android"
      android:label="@string/app_label"
      android:hint="@string/search_hint"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>
  

• Ayrı ayrı öneriler için işlemi tanımlamak üzere SUGGEST_COLUMN_INTENT_ACTION sütununu kullanın. Bunu yapmak için SUGGEST_COLUMN_INTENT_ACTION sütununu öneriler tablonuza ekleyin ve her öneri için kullanılacak işleme (ör. "android.intent.action.VIEW") yerleştirin.

Bu iki tekniği de birleştirebilirsiniz. Örneğin, varsayılan olarak tüm önerilerle kullanılacak bir işleme android:searchSuggestIntentAction özelliğini ekleyebilir, ardından SUGGEST_COLUMN_INTENT_ACTION sütununda farklı bir işlem tanımlayarak bu işlemi bazı öneriler için geçersiz kılabilirsiniz. SUGGEST_COLUMN_INTENT_ACTION sütununa bir değer eklemezseniz android:searchSuggestIntentAction özelliğinde sağlanan amaç kullanılır.

Amaç verilerini bildirme

Kullanıcı bir öneriyi seçtiğinde, aranabilir etkinliğiniz, tanımladığınız işlemle (önceki bölümde açıklandığı gibi) amacı alır, ancak amacın hangi önerinin seçildiğini belirlemek için etkinliğinize ait verileri de taşıması gerekir. Özellikle, veriler her öneri için benzersiz olmalıdır (örneğin, SQLite tablonuzdaki önerinin satır kimliği). Niyet alındığında ekli verileri getData() veya getDataString() ile alabilirsiniz.

Amaca dahil edilen verileri iki şekilde tanımlayabilirsiniz:

• Öneriler tablonuzun SUGGEST_COLUMN_INTENT_DATA sütununda her önerinin verilerini tanımlayın.

  Öneriler tablosundaki her amaca yönelik tüm gerekli veri bilgilerini sağlamak için SUGGEST_COLUMN_INTENT_DATA sütununu dahil edin ve ardından her satır için benzersiz verilerle doldurun. Bu sütundaki veriler, tam olarak bu sütunda tanımladığınız şekilde amaca eklenir. Daha sonra getData() veya getDataString() ile alabilirsiniz.

• Veri URI'sini iki parçaya bölün: tüm önerilerde ortak olan kısım ve her öneriye özel olan kısım. Bu bölümleri, sırasıyla aranabilir yapılandırmanın android:searchSuggestintentData özelliğine ve öneriler tablonuzun SUGGEST_COLUMN_INTENT_DATA_ID sütununa yerleştirin.

  Aşağıdaki örnekte, aranabilir yapılandırmanızın android:searchSuggestIntentData özelliğindeki tüm önerilerde ortak olan URI parçasının nasıl tanımlanacağı gösterilmektedir:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    

  Her önerinin son yolunu (benzersiz bölümü), öneriler tablonuzun SUGGEST_COLUMN_INTENT_DATA_ID sütununa ekleyin. Kullanıcı bir öneriyi seçtiğinde, sistem android:searchSuggestIntentData kaynağından dizeyi alır, eğik çizgi (/) ekler ve ardından SUGGEST_COLUMN_INTENT_DATA_ID sütunundaki ilgili değeri ekleyerek tam bir içerik URI'si oluşturur. Daha sonra Uri öğesini getData() ile alabilirsiniz.

Daha fazla veri ekleyin

Niyetinizle ilgili daha fazla bilgi ifade etmeniz gerekiyorsa öneri hakkında ek bilgiler depolayabilecek SUGGEST_COLUMN_INTENT_EXTRA_DATA gibi başka bir tablo sütunu ekleyebilirsiniz. Bu sütuna kaydedilen veriler, amacın ek paketinin EXTRA_DATA_KEY içine yerleştirilir.

Amacı yönetin

Özel amaçlara sahip özel arama önerileri sağladıktan sonra, kullanıcı bir öneri seçtiğinde bu amaçların ele alınması için aranabilir etkinliğinizin olması gerekir. Bu, aranabilir etkinliğinizin zaten yaptığı ACTION_SEARCH amacını ele almaya ek olarak yapılır. Etkinliğinizin onCreate() geri çağırması sırasında amaçları nasıl yönetebileceğinize dair bir örneği burada bulabilirsiniz:

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

Bu örnekte, amaç işlemi ACTION_VIEW'dir ve veriler, android:searchSuggestIntentData dizesi ve SUGGEST_COLUMN_INTENT_DATA_ID sütunu tarafından sentezlendiği şekilde, önerilen öğeyi işaret eden tam bir URI taşır. URI, daha sonra URI tarafından belirtilen öğe için içerik sağlayıcıyı sorgulayan yerel showResult() yöntemine geçer.

Sorgu metnini yeniden yazın

Varsayılan olarak, kullanıcı, iztopu veya D-pad gibi yön kontrolleri kullanarak öneriler listesinde gezinirse sorgu metni güncellenmez. Ancak kullanıcının sorgu metnini, odaklanılan öneriyle eşleşen bir sorguyla metin kutusunda göründüğü şekilde geçici olarak yeniden yazabilirsiniz. Bu sayede kullanıcı, önerilen sorguyu görebilir ve arama olarak göndermeden önce arama kutusunu seçip düzenleyebilir.

Sorgu metnini aşağıdaki şekillerde yeniden yazabilirsiniz:

• "queryRewriteFromText" değeriyle, aranabilir yapılandırmanıza android:searchMode özelliğini ekleyin. Bu durumda, sorgu metnini yeniden yazmak için önerinin SUGGEST_COLUMN_TEXT_1 sütunundaki içerik kullanılır.
• android:searchMode özelliğini, aranabilir\ yapılandırmanıza "queryRewriteFromData" değeriyle ekleyin. Bu durumda, önerinin SUGGEST_COLUMN_INTENT_DATA sütunundaki içerik sorgu metnini yeniden yazmak için kullanılır. Bunu yalnızca HTTP URL'leri gibi kullanıcı tarafından görülebilmesi amaçlanan URI'ler veya diğer veri biçimleriyle kullanın. Sorguyu bu şekilde yeniden yazmak için dahili URI şemalarını kullanmayın.
• Öneriler tablonuzun SUGGEST_COLUMN_QUERY sütununa benzersiz bir sorgu metin dizesi girin. Bu sütun varsa ve mevcut öneri için bir değer içeriyorsa sorgu metnini yeniden yazmak ve önceki uygulamalardan birini geçersiz kılmak için kullanılır.

Arama önerilerini Hızlı Arama Kutusu'na göster

Uygulamanızı özel arama önerileri sağlayacak şekilde yapılandırdıktan sonra, bu önerileri tüm dünyada erişilebilir Hızlı Arama Kutusu'nun kullanımına sunmak için aranabilir yapılandırmanızı, android:includeInGlobalSearch ve "true" değerini içerecek şekilde değiştirmek kadar kolaydır.

Ek çalışmanın gereken tek senaryo, içerik sağlayıcınızın bir okuma izni istemesidir. Bu durumda, sağlayıcının aşağıdaki örnekte gösterildiği gibi, İçerik Sağlayıcınıza Hızlı Arama Kutusu okuma erişimi vermesi için bir <path-permission> öğesi eklemeniz gerekir:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

Bu örnekte sağlayıcı, içeriğe okuma ve yazma erişimini kısıtlar. <path-permission> öğesi, "android.permission.GLOBAL_SEARCH" izni mevcut olduğunda "/search_suggest_query" yol ön eki içindeki içeriğe okuma erişimi vererek kısıtlamayı değiştirir. Bu, Çabuk Arama Kutusu'na erişim izni verir ve böylece içerik sağlayıcınızı öneriler için sorgulayabilir.

İçerik sağlayıcınız okuma izinlerini zorunlu tutmuyorsa Hızlı Arama Kutusu, varsayılan olarak bu izinleri okur.

Bir cihazda önerileri etkinleştirme

Varsayılan olarak, uygulamalar Çabuk Arama Kutusu'nda öneri sağlayacak şekilde yapılandırılmış olsalar bile Çabuk Arama Kutusu'nda öneri sunma özelliği etkinleştirilmez. Kullanıcı, Ayarlar > Arama bölümünde bulunan Aranabilir öğeleri açıp uygulamanızı aranabilir öğe olarak etkinleştirerek, uygulamanızın önerilerini Hızlı Arama Kutusu'na dahil edip etmeyeceğini seçer.

Hızlı Arama Kutusu'nda kullanılabilen her uygulamanın, Aranabilir öğeler ayarlar sayfasında bir girişi vardır. Girişte, uygulamanın adı, hangi içeriklerin uygulamada aranabileceği ve Hızlı Arama Kutusu'nda öneriler için kullanıma sunulduğu kısa bir açıklama yer alır. Aranabilir uygulamanızın açıklama metnini tanımlamak için, aranabilir yapılandırmanıza aşağıdaki örnekte gösterildiği gibi android:searchSettingsDescription özelliğini ekleyin:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

android:searchSettingsDescription dizesini mümkün olduğunca kısa yapın ve aranabilir içeriği belirtin. Örneğin, bir müzik uygulaması için "Sanatçılar, albümler ve parçalar" veya bir not defteri uygulaması için "Kayıtlı notlar". Bu açıklamanın sağlanması, kullanıcının ne tür önerilerin sunulduğunu bilmesi için önemlidir. android:includeInGlobalSearch doğru olduğunda bu özelliği her zaman ekleyin.

Kullanıcının, uygulamanız için arama önerilerini etkinleştirmek üzere ayarlar menüsünü ziyaret etmesi gerektiğinden, arama, uygulamanızın önemli bir yönüyse bunu kullanıcılarınıza nasıl ileteceğinizi düşünün. Örneğin, bir kullanıcı uygulamayı ilk kez açtığında, Çabuk Arama Kutusu için arama önerilerinin nasıl etkinleştirileceğini açıklayan bir not verebilirsiniz.

Çabuk Arama Kutusu öneri kısayollarını yönet

Kullanıcının Çabuk Arama Kutusu'ndan seçtiği öneriler otomatik olarak kısayollara dönüştürülebilir. Bunlar, sistemin içerik sağlayıcınızı yeniden sorgulamak zorunda kalmadan öneriye hızlı bir şekilde erişebilmesi için içerik sağlayıcınızdan kopyaladığı önerilerdir.

Bu özellik, Çabuk Arama Kutusu tarafından alınan tüm öneriler için varsayılan olarak etkindir. Ancak öneri verileriniz zaman içinde değişirse kısayolların yenilenmesini isteyebilirsiniz. Örneğin, önerileriniz bir kişinin bulunma durumu gibi dinamik verilere işaret ediyorsa kullanıcıya gösterildiğinde öneri kısayollarının yenilenmesini isteyin. Bunu yapmak için öneriler tablonuza SUGGEST_COLUMN_SHORTCUT_ID özelliğini ekleyin. Aşağıdaki yöntemlerden birini kullanarak her bir önerinin kısayol davranışını yapılandırmak için bu sütunu kullanabilirsiniz:

• Çabuk Arama Kutusu'nun, öneri kısayolunun yeni bir sürümü için içerik sağlayıcınızı yeniden sorgulamasını sağlayın.

  Kısayol her görüntülendiğinde önerinin yeni bir sürüm için yeniden sorgulanması için SUGGEST_COLUMN_SHORTCUT_ID sütununa bir değer girin. Kısayol, yenileme sorgusu döndürülene dek en son kullanılabilir olan verilerle hızlı bir şekilde görüntülenir. Bu noktada öneri, yeni bilgilerle yenilenir. Yenileme sorgusu, içerik sağlayıcınıza SUGGEST_URI_PATH_QUERY yerine SUGGEST_URI_PATH_SHORTCUT URI yoluyla gönderilir.

  Döndürdüğünüz Cursor öğesinin, orijinal öneriyle aynı sütunları kullanan bir öneri içermesini veya boş bırakılmasını sağlayın. Bu, kısayolun artık geçerli olmadığını gösterir. Bu durumda öneri kaybolur ve kısayol kaldırılır.

  Bir öneri, ağa dayalı yenileme gibi yenilenmesi daha uzun sürebilecek verilere işaret ediyorsa yenileme tamamlanana kadar sağ simge için ilerleme durumunu gösteren bir değer göstermek üzere SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING sütununu öneriler tablonuza true değeriyle de ekleyebilirsiniz. True dışındaki değerler ilerleme değer değiştiricisini göstermez.

• Önerinin kısayola kopyalanmasını engelleyebilirsiniz.

  SUGGEST_COLUMN_SHORTCUT_ID sütununa SUGGEST_NEVER_MAKE_SHORTCUT değerini girin. Bu durumda, öneri hiçbir zaman kısayola kopyalanmaz. Bu işlem, yalnızca önceden kopyalanan önerinin görünmesini kesinlikle istemiyorsanız gereklidir. Sütun için normal bir değer sağlarsanız öneri kısayolu, yalnızca yenileme sorgusu döndürülene kadar görünür.

• Varsayılan kısayol davranışının uygulanmasına izin verin.

  Kısayol olarak kaydedilebilecek değişmeyen ve tüm öneriler için SUGGEST_COLUMN_SHORTCUT_ID alanını boş bırakın.

Önerilerinizden hiçbiri değişmezse SUGGEST_COLUMN_SHORTCUT_ID sütununa ihtiyacınız yoktur.

Çabuk Arama Kutusu öneri sıralaması hakkında

Uygulamanızın arama önerilerini Hızlı Arama Kutusu'nda kullanıma sunduktan sonra, Hızlı Arama Kutusu sıralaması, belirli bir sorgu için önerilerin kullanıcıya nasıl gösterileceğini belirler. Bu, söz konusu sorgu için başka kaç uygulamada sonuç bulunduğuna ve kullanıcının sonuçlarınızı, diğer uygulamalardaki sonuçlarla karşılaştırıldığında ne sıklıkta seçtiğine bağlı olabilir. Önerilerinizin nasıl sıralandığı veya belirli bir sorgu için uygulamanızın önerilerinin gösterilip gösterilmeyeceği konusunda herhangi bir garanti verilmez. Genel olarak, kaliteli sonuçlar sağlamak, uygulamanızın önerilerinin belirgin bir konumda sunulma olasılığını artırır. Düşük kaliteli öneriler sunan uygulamaların daha düşük bir sıralamada yer alma veya görüntülenmeme olasılığı daha yüksektir.