Aggiungi suggerimenti di ricerca personalizzati

Quando utilizzi il widget Ricerca o la finestra di dialogo di ricerca di Android, puoi fornire suggerimenti di ricerca personalizzati creati a partire dai dati della tua app. Ad esempio, se la tua app è un dizionario, puoi suggerire parole del dizionario che corrispondono al testo inserito nel campo di ricerca prima che l'utente finisca di inserire la query. Questi suggerimenti sono preziosi perché possono prevedere in modo efficace ciò che vuole l'utente e fornirgli accesso immediato. La Figura 1 mostra un esempio di finestra di ricerca con suggerimenti personalizzati.

Una volta forniti suggerimenti personalizzati, puoi anche renderli disponibili alla Casella di ricerca rapida a livello di sistema, fornendo l'accesso ai tuoi contenuti dall'esterno della tua app.

Prima di aggiungere suggerimenti personalizzati, implementa la finestra di dialogo di ricerca di Android o un widget di ricerca per le ricerche nella tua app. Consulta gli articoli Creare un'interfaccia di ricerca e Fornitori di contenuti.

Nozioni di base

Figura 1. Screenshot di una finestra di dialogo di ricerca con suggerimenti di ricerca personalizzati.

Quando l'utente seleziona un suggerimento personalizzato, il sistema invia un Intent alla tua attività disponibile per la ricerca. A differenza di una normale query di ricerca che invia un intent con l'azione ACTION_SEARCH, puoi invece definire i suggerimenti personalizzati da utilizzare ACTION_VIEW o qualsiasi altra azione intent e includere anche i dati pertinenti al suggerimento selezionato. Nell'esempio del dizionario, quando l'utente seleziona un suggerimento, l'app può aprire immediatamente la definizione di quella parola, anziché cercare corrispondenze nel dizionario.

Per fornire suggerimenti personalizzati, procedi nel seguente modo:

  • Implementa un'attività di ricerca di base, come descritto nella sezione Creare un'interfaccia di ricerca.
  • Modifica la configurazione disponibile per la ricerca con informazioni sul fornitore di contenuti che fornisce suggerimenti personalizzati.
  • Crea una tabella, ad esempio in un SQLiteDatabase, per i tuoi suggerimenti e formatta la tabella con le colonne obbligatorie.
  • Crea un provider di contenuti che abbia accesso alla tabella dei suggerimenti e dichiara il provider nel tuo manifest.
  • Dichiara il tipo di Intent da inviare quando l'utente seleziona un suggerimento, inclusi un'azione personalizzata e dati personalizzati.

Il sistema Android mostra la finestra di dialogo di ricerca, così come mostra i suggerimenti di ricerca. Hai bisogno di un fornitore di contenuti dal quale il sistema può recuperare i tuoi suggerimenti. Consulta Fornitori di contenuti per scoprire come creare un fornitore di contenuti.

Quando il sistema identifica che la tua attività è disponibile per la ricerca e fornisce suggerimenti per le ricerche, quando l'utente inserisce una query viene eseguita la seguente procedura:

  1. Il sistema acquisisce il testo della query di ricerca, ovvero ciò che è stato inserito fino a quel momento, ed esegue una query al fornitore di contenuti, che gestisce i tuoi suggerimenti.
  2. Il tuo fornitore di contenuti restituisce un Cursor che indirizza a tutti i suggerimenti pertinenti al testo della query di ricerca.
  3. Il sistema mostra l'elenco di suggerimenti forniti da Cursor.

Una volta visualizzati i suggerimenti personalizzati, potrebbe verificarsi quanto segue:

  • Se l'utente inserisce un'altra lettera o modifica in qualsiasi modo la query, i passaggi precedenti si ripetono e l'elenco dei suggerimenti si aggiorna di conseguenza.
  • Se l'utente esegue la ricerca, i suggerimenti vengono ignorati e la ricerca viene inviata all'attività disponibile per la ricerca utilizzando il normale intent ACTION_SEARCH.
  • Se l'utente seleziona un suggerimento, viene inviato un intent alla tua attività disponibile per la ricerca, con un'azione personalizzata e dati personalizzati in modo che la tua app possa aprire i contenuti suggeriti.

Modifica la configurazione disponibile per la ricerca

Per aggiungere il supporto dei suggerimenti personalizzati, aggiungi l'attributo android:searchSuggestAuthority all'elemento <searchable> nel file di configurazione disponibile per la ricerca, come mostrato nell'esempio seguente:

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

Potresti aver bisogno di attributi aggiuntivi, a seconda del tipo di intent allegato a ciascun suggerimento e di come vuoi formattare le query al tuo fornitore di contenuti. Gli altri attributi facoltativi sono illustrati nelle sezioni seguenti.

Crea un fornitore di contenuti

Per creare un fornitore di contenuti per i suggerimenti personalizzati, consulta innanzitutto Fornitori di contenuti per informazioni su come creare un fornitore di contenuti. Un fornitore di contenuti per suggerimenti personalizzati è simile a qualsiasi altro fornitore di contenuti. Tuttavia, per ogni suggerimento fornito, la rispettiva riga in Cursor deve includere colonne specifiche che il sistema comprende e utilizza per formattare i suggerimenti.

Quando l'utente inserisce del testo nella finestra di dialogo di ricerca o nel widget Ricerca, il sistema chiede suggerimenti al fornitore di contenuti chiamando query() ogni volta che viene inserita una lettera. Nell'implementazione di query(), il fornitore di contenuti deve cercare i dati relativi ai suggerimenti e restituire un Cursor che indirizzi alle righe che ritiene siano buoni suggerimenti.

I dettagli sulla creazione di un fornitore di contenuti per suggerimenti personalizzati sono discussi nelle seguenti due sezioni:

Gestire la query di suggerimento
Il modo in cui il sistema invia richieste al tuo fornitore di contenuti e come gestirle.
Creare una tabella di suggerimenti
Come definire le colonne che il sistema prevede nel Cursor restituito con ogni query.

Gestire la query di suggerimento

Quando il sistema richiede suggerimenti al tuo fornitore di contenuti, richiama il metodo query() del fornitore. Implementa questo metodo per cercare nei dati relativi ai suggerimenti e restituire un Cursor che rimandi ai suggerimenti che ritieni pertinenti.

Ecco un riepilogo dei parametri che il sistema passa al tuo metodo query(), elencati in ordine:

  1. uri

    Sempre un contenuto Uri, formattato come segue: 

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

    Il comportamento predefinito è che il sistema passi questo URI e vi aggiunga il testo della query:

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

    Il testo della query alla fine è codificato utilizzando le regole di codifica dell'URI, quindi potrebbe essere necessario decodificarlo prima di eseguire una ricerca.

    La parte optional.suggest.path è inclusa nell'URI solo se imposti un percorso di questo tipo nel file di configurazione disponibile per la ricerca con l'attributo android:searchSuggestPath. È necessario solo se utilizzi lo stesso fornitore di contenuti per più attività disponibili per la ricerca. In questo caso, chiarisci l'origine della query di suggerimento.

  2. projection
    Sempre null.
  3. selection
    Valore specificato nell'attributo android:searchSuggestSelection del file di configurazione disponibile per la ricerca oppure nullo se non dichiari l'attributo android:searchSuggestSelection. La seguente sezione tratta questo aspetto in modo più approfondito.
  4. selectionArgs
    Contiene la query di ricerca come primo e unico elemento dell'array se dichiari l'attributo android:searchSuggestSelection nella configurazione disponibile per la ricerca. Se non dichiari android:searchSuggestSelection, questo parametro è nullo. La seguente sezione tratta questo argomento in modo più approfondito.
  5. sortOrder
    Sempre null.

Il sistema può inviarti il testo della query di ricerca in due modi. Il metodo predefinito consente di includere il testo della query come ultimo percorso dell'URI dei contenuti trasmesso nel parametro uri. Tuttavia, se includi un valore di selezione nell'attributo android:searchSuggestSelection della configurazione ricercabile, il testo della query viene passato come primo elemento dell'array di stringhe selectionArgs. Queste due opzioni sono descritte di seguito.

Ottieni la query nell'URI

Per impostazione predefinita, la query viene aggiunta come ultimo segmento del parametro uri, un oggetto Uri. Per recuperare il testo della query in questo caso, utilizza getLastPathSegment(), come mostrato nell'esempio seguente:

Kotlin

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

Java

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

Questo restituisce l'ultimo segmento di Uri, ovvero il testo della query inserito dall'utente.

Ottieni la query negli argomenti di selezione

Invece di utilizzare l'URI, potrebbe essere più opportuno che il tuo metodo query() riceva tutto ciò di cui ha bisogno per eseguire la ricerca e potresti volere che i parametri selection e selectionArgs abbiano i valori appropriati. In questo caso, aggiungi l'attributo android:searchSuggestSelection alla configurazione disponibile per la ricerca con la stringa di selezione SQLite. Nella stringa di selezione, includi un punto interrogativo (?) come segnaposto per la query di ricerca effettiva. Il sistema chiama query() con la stringa di selezione come parametro selection e la query di ricerca come primo elemento nell'array selectionArgs.

Ad esempio, ecco come potresti formare l'attributo android:searchSuggestSelection per creare una dichiarazione di ricerca di testo completo:

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

Con questa configurazione, il metodo query() pubblica il parametro selection come "word MATCH ?" e il parametro selectionArgs come query di ricerca. Quando passi questi elementi a un metodo query() SQLite, i rispettivi argomenti vengono sintetizzati insieme, il che significa che il punto interrogativo viene sostituito con il testo della query. Se ricevi query di suggerimento in questo modo e devi aggiungere caratteri jolly al testo della query, aggiungili o anteponili al parametro selectionArgs, perché questo valore è racchiuso tra virgolette e inserito al posto del punto interrogativo.

Un altro attributo nell'esempio precedente è android:searchSuggestIntentAction, che definisce l'azione intent inviata con ciascun intent quando l'utente seleziona un suggerimento. Questo argomento verrà discusso ulteriormente nella sezione Dichiarare un intento di suggerimenti.

Crea una tabella di suggerimenti

Quando restituisci suggerimenti al sistema con un valore Cursor, il sistema prevede colonne specifiche in ogni riga. Indipendentemente dal fatto che memorizzi i dati dei suggerimenti in un database SQLite sul dispositivo, in un database su un server web o in un altro formato sul dispositivo o sul web, formatta i suggerimenti come righe di una tabella e presentali con un Cursor.

Il sistema riconosce diverse colonne, ma ne sono obbligatorie solo due:

_ID
Un ID riga di un numero intero univoco per ogni suggerimento. Il sistema richiede questa operazione per presentare suggerimenti in un ListView.
SUGGEST_COLUMN_TEXT_1
La stringa presentata come suggerimento.

Le seguenti colonne sono tutte facoltative. La maggior parte viene discussa in dettaglio nelle sezioni seguenti.

SUGGEST_COLUMN_TEXT_2
Una stringa. Se Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato a due righe. La stringa in questa colonna viene visualizzata come seconda riga di testo più piccola sotto il testo del suggerimento principale. Può essere nullo o vuoto per indicare l'assenza di testo secondario.
SUGGEST_COLUMN_ICON_1
Una stringa di risorse, contenuti o URI di file disegnabili. Se Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona disegnabile a sinistra. Può essere null o zero per indicare che non ci sono icone in questa riga.
SUGGEST_COLUMN_ICON_2
Una stringa di risorse, contenuti o URI di file disegnabili. Se Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona a destra. Può essere null o zero per indicare che non ci sono icone in questa riga.
SUGGEST_COLUMN_INTENT_ACTION
Una stringa di azione intent. Se questa colonna esiste e contiene un valore nella riga specificata, l'azione definita qui viene utilizzata per formare l'intent del suggerimento. Se l'elemento non viene fornito, l'azione viene eseguita dal campo android:searchSuggestIntentAction nella configurazione disponibile per la ricerca. Se l'azione è la stessa per tutti i suggerimenti, è più efficiente specificarla utilizzando android:searchSuggestIntentAction e omettere questa colonna.
SUGGEST_COLUMN_INTENT_DATA
Una stringa URI di dati. Se questa colonna esiste e contiene un valore nella riga specificata, questi dati vengono utilizzati per formare l'intent del suggerimento. Se l'elemento non viene fornito, i dati vengono recuperati dal campo android:searchSuggestIntentData nella configurazione disponibile per la ricerca. Se non viene fornita nessuna delle due origini, il campo dei dati dell'intent è nullo. Se i dati sono gli stessi per tutti i suggerimenti o se possono essere descritti utilizzando una parte costante e un ID specifico, è più efficiente specificarli utilizzando android:searchSuggestIntentData e omettere questa colonna.
SUGGEST_COLUMN_INTENT_DATA_ID
Una stringa di percorso URI. Se questa colonna esiste e contiene un valore nella riga specificata, "/" e questo valore vengono aggiunti al campo dati nell'intent. Da utilizzare solo se il campo dei dati specificato dall'attributo android:searchSuggestIntentData nella configurazione disponibile per la ricerca è già impostato su una stringa di base appropriata.
SUGGEST_COLUMN_INTENT_EXTRA_DATA
Dati arbitrari. Se questa colonna esiste e contiene un valore in una determinata riga, questi sono i dati aggiuntivi utilizzati per formare l'intent del suggerimento. Se non viene specificato, il campo dei dati in eccesso dell'intent è nullo. Questa colonna consente ai suggerimenti di fornire dati aggiuntivi che sono inclusi come extra nella chiave EXTRA_DATA_KEY dell'intent.
SUGGEST_COLUMN_QUERY
Se la colonna esiste e questo elemento esiste nella riga specificata, questi sono i dati utilizzati per creare la query del suggerimento, inclusi come extra nella chiave QUERY dell'intent. È obbligatoria se l'azione del suggerimento è ACTION_SEARCH, altrimenti facoltativa.
SUGGEST_COLUMN_SHORTCUT_ID
Utilizzato solo quando fornisci suggerimenti per la Casella di ricerca rapida. Questa colonna indica se un suggerimento di ricerca deve essere archiviato come scorciatoia e se deve essere convalidato. In genere le scorciatoie vengono create quando l'utente tocca un suggerimento dalla Casella di ricerca rapida. Se mancante, il risultato viene memorizzato come scorciatoia e non viene mai aggiornato. Se viene impostato su SUGGEST_NEVER_MAKE_SHORTCUT, il risultato non viene archiviato come scorciatoia. In caso contrario, l'ID scorciatoia viene utilizzato per verificare la presenza di un suggerimento aggiornato utilizzando SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
Utilizzato solo quando fornisci suggerimenti per la Casella di ricerca rapida. Questa colonna specifica che è necessario mostrare una rotellina anziché un'icona di SUGGEST_COLUMN_ICON_2 mentre la scorciatoia di questo suggerimento viene aggiornata nella Casella di ricerca rapida.

La maggior parte di queste colonne è trattata in modo più approfondito nelle sezioni seguenti.

Dichiarare un intento di ricevere suggerimenti

Quando l'utente seleziona un suggerimento dall'elenco visualizzato nella finestra di dialogo o nel widget di ricerca, il sistema invia un Intent personalizzato alla tua attività disponibile per la ricerca. Devi definire l'azione e i dati relativi all'intent.

Dichiara l'azione intent

L'azione più comune per intenzione relativa a un suggerimento personalizzato è ACTION_VIEW, che è appropriata quando vuoi aprire qualcosa, come la definizione di una parola, i dati di contatto di una persona o una pagina web. Tuttavia, l'azione intent può essere qualsiasi altra azione e può essere diversa per ogni suggerimento.

A seconda che tu voglia che tutti i suggerimenti utilizzino la stessa azione intent, puoi definire l'azione in due modi:

  • Utilizza l'attributo android:searchSuggestIntentAction del file di configurazione disponibile per la ricerca per definire l'azione per tutti i suggerimenti, come mostrato nell'esempio seguente: 
    <?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>
  • Utilizza la colonna SUGGEST_COLUMN_INTENT_ACTION per definire l'azione per i singoli suggerimenti. Per farlo, aggiungi la colonna SUGGEST_COLUMN_INTENT_ACTION alla tabella dei suggerimenti e, per ogni suggerimento, inserisci al suo interno l'azione da utilizzare, ad esempio "android.intent.action.VIEW".

Puoi anche combinare queste due tecniche. Ad esempio, puoi includere l'attributo android:searchSuggestIntentAction con un'azione da utilizzare per tutti i suggerimenti per impostazione predefinita e poi ignorare questa azione per alcuni suggerimenti dichiarando un'azione diversa nella colonna SUGGEST_COLUMN_INTENT_ACTION. Se non includi un valore nella colonna SUGGEST_COLUMN_INTENT_ACTION, viene utilizzato l'intent fornito nell'attributo android:searchSuggestIntentAction.

Dichiarare i dati sull'intenzione

Quando l'utente seleziona un suggerimento, la tua attività disponibile per la ricerca riceve l'intent con l'azione che definisci, come descritto nella sezione precedente, ma l'intent deve anche includere i dati della tua attività per identificare il suggerimento selezionato. In particolare, i dati devono essere univoci per ogni suggerimento, ad esempio l'ID riga del suggerimento nella tabella SQLite. Quando l'intent viene ricevuto, puoi recuperare i dati allegati con getData() o getDataString().

Puoi definire i dati inclusi con l'intent in due modi:

  • Definisci i dati per ogni suggerimento all'interno della colonna SUGGEST_COLUMN_INTENT_DATA della tabella dei suggerimenti.

    Fornisci tutte le informazioni necessarie per ciascun intent nella tabella dei suggerimenti includendo la colonna SUGGEST_COLUMN_INTENT_DATA e compilandola con i dati univoci per ogni riga. I dati di questa colonna sono associati all'intent esattamente come lo definisci in questa colonna. Puoi quindi recuperarlo con getData() o getDataString().

  • Frammenta un URI dati in due parti: la parte comune a tutti i suggerimenti e la parte univoca per ogni suggerimento. Inserisci queste parti nell'attributo android:searchSuggestintentData della configurazione disponibile per la ricerca e nella colonna SUGGEST_COLUMN_INTENT_DATA_ID della tabella dei suggerimenti, rispettivamente.

    L'esempio seguente mostra come dichiarare la parte dell'URI comune a tutti i suggerimenti nell'attributo android:searchSuggestIntentData della configurazione disponibile per la ricerca:

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

    Includi il percorso finale di ogni suggerimento (la parte univoca) nella colonna SUGGEST_COLUMN_INTENT_DATA_ID della tabella dei suggerimenti. Quando l'utente seleziona un suggerimento, il sistema prende la stringa da android:searchSuggestIntentData, aggiunge una barra (/) e poi aggiunge il rispettivo valore dalla colonna SUGGEST_COLUMN_INTENT_DATA_ID per formare un URI di contenuti completo. Puoi quindi recuperare Uri con getData().

Aggiungi altri dati

Se vuoi fornire ulteriori informazioni, puoi aggiungere un'altra colonna della tabella, come SUGGEST_COLUMN_INTENT_EXTRA_DATA, che può memorizzare ulteriori informazioni sul suggerimento. I dati salvati in questa colonna vengono inseriti nel EXTRA_DATA_KEY del bundle aggiuntivo dell'intent.

Gestire l'intent

Dopo aver fornito suggerimenti di ricerca personalizzati con intent personalizzati, avrai bisogno della tua attività disponibile per la ricerca per gestire questi intent quando l'utente seleziona un suggerimento. Questa operazione si aggiunge alla gestione dell'intent ACTION_SEARCH, che avviene già nelle tue attività di ricerca. Ecco un esempio di come puoi gestire gli intent durante il callback onCreate() dell'attività:

Kotlin

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)
    }
}

Java

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);
}

In questo esempio, l'azione intent è ACTION_VIEW e i dati portano un URI completo che punta all'elemento suggerito, come sintetizzato dalla stringa android:searchSuggestIntentData e dalla colonna SUGGEST_COLUMN_INTENT_DATA_ID. L'URI passa quindi al metodo showResult() locale che invia una query al fornitore di contenuti per l'elemento specificato dall'URI.

Riscrivi il testo della query

Per impostazione predefinita, se l'utente naviga nell'elenco dei suggerimenti utilizzando controlli direzionali, ad esempio con una trackball o un D-pad, il testo della query non viene aggiornato. Tuttavia, puoi riscrivere temporaneamente il testo della query dell'utente così come appare nella casella di testo con una query che corrisponde al suggerimento in primo piano. In questo modo l'utente può vedere la query suggerita e selezionare la casella di ricerca e modificarla prima di inviarla come ricerca.

Puoi riscrivere il testo della query nei seguenti modi:

  • Aggiungi l'attributo android:searchMode alla configurazione disponibile per la ricerca con il valore "queryRewriteFromText". In questo caso, i contenuti della colonna SUGGEST_COLUMN_TEXT_1 del suggerimento vengono utilizzati per riscrivere il testo della query.
  • Aggiungi l'attributo android:searchMode alla configurazione\ disponibile per la ricerca con il valore "queryRewriteFromData". In questo caso, i contenuti della colonna SUGGEST_COLUMN_INTENT_DATA del suggerimento vengono utilizzati per riscrivere il testo della query. Utilizzalo solo con URI o altri formati di dati visibili all'utente, come gli URL HTTP. Non utilizzare schemi URI interni per riscrivere la query in questo modo.
  • Fornisci una stringa di testo della query univoca nella colonna SUGGEST_COLUMN_QUERY della tabella dei suggerimenti. Se questa colonna è presente e contiene un valore per il suggerimento corrente, viene utilizzata per riscrivere il testo della query e sostituire una delle implementazioni precedenti.

Mostra i suggerimenti di ricerca alla Casella di ricerca rapida

Dopo aver configurato la tua app in modo da fornire suggerimenti di ricerca personalizzati, per renderli disponibili nella Casella di ricerca rapida accessibile a livello globale è sufficiente modificare la tua configurazione disponibile per la ricerca per includere android:includeInGlobalSearch con il valore "true".

L'unico scenario in cui è necessario un lavoro aggiuntivo è quando il tuo fornitore di contenuti richiede un'autorizzazione di lettura. In questo caso, devi aggiungere un elemento <path-permission> per consentire al provider di concedere alla Casella di ricerca rapida l'accesso in lettura al tuo fornitore di contenuti, come illustrato nell'esempio seguente:

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

In questo esempio, il provider limita l'accesso in lettura e scrittura ai contenuti. L'elemento <path-permission> modifica la limitazione concedendo l'accesso in lettura ai contenuti all'interno del prefisso del percorso "/search_suggest_query" quando esiste l'autorizzazione "android.permission.GLOBAL_SEARCH". Questo consente l'accesso alla Casella di ricerca rapida in modo che possa chiedere suggerimenti al fornitore di contenuti.

Se il tuo fornitore di contenuti non applica le autorizzazioni di lettura, la Casella di ricerca rapida le legge per impostazione predefinita.

Attivare i suggerimenti su un dispositivo

Per impostazione predefinita, le app non sono in grado di fornire suggerimenti nella Casella di ricerca rapida, anche se sono configurate in tal modo. L'utente sceglie se includere suggerimenti della tua app nella Casella di ricerca rapida aprendo gli Elementi ricercabili, che si trovano in Impostazioni > Ricerca, e attivando la tua app come elemento disponibile per la ricerca.

Ogni app disponibile per la Casella di ricerca rapida è associata a una voce nella pagina di impostazioni Elementi ricercabili. La voce include il nome dell'app e una breve descrizione dei contenuti che possono essere cercati dall'app e resi disponibili per i suggerimenti nella Casella di ricerca rapida. Per definire il testo descrittivo per la tua app disponibile per la ricerca, aggiungi l'attributo android:searchSettingsDescription alla configurazione disponibile per la ricerca, come illustrato nell'esempio seguente:

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

Fai in modo che la stringa per android:searchSettingsDescription sia il più concisa possibile e indica i contenuti disponibili per la ricerca. Ad esempio, "Artisti, album e tracce" per un'app di musica o "Note salvate" per un'app per blocchi note. Questa descrizione è importante per consentire all'utente di sapere che tipo di suggerimenti viene fornito. Includi sempre questo attributo quando android:includeInGlobalSearch è true.

Poiché l'utente deve visitare il menu delle impostazioni per attivare i suggerimenti di ricerca per la tua app, se la ricerca è un aspetto importante della tua app, considera come comunicarlo agli utenti. Ad esempio, puoi fornire una nota la prima volta che un utente avvia l'app che spiega come attivare i suggerimenti di ricerca per la Casella di ricerca rapida.

Gestire le scorciatoie dei suggerimenti della Casella di ricerca rapida

I suggerimenti che l'utente seleziona dalla Casella di ricerca rapida possono essere convertiti automaticamente in scorciatoie. Si tratta di suggerimenti che il sistema copia dal tuo fornitore di contenuti in modo che possa accedere rapidamente al suggerimento senza dover eseguire una nuova query.

Per impostazione predefinita, questa opzione è abilitata per tutti i suggerimenti recuperati dalla casella di ricerca rapida, ma se i dati dei suggerimenti cambiano nel tempo, puoi richiedere l'aggiornamento delle scorciatoie. Ad esempio, se i suggerimenti fanno riferimento a dati dinamici, come lo stato di presenza di un contatto, richiedi l'aggiornamento delle scorciatoie dei suggerimenti quando vengono mostrate all'utente. A questo scopo, includi SUGGEST_COLUMN_SHORTCUT_ID nella tabella dei suggerimenti. Puoi utilizzare questa colonna per configurare il comportamento della scorciatoia per ogni suggerimento in uno dei seguenti modi:

  • Fai in modo che la Casella di ricerca rapida effettui una nuova query al tuo fornitore di contenuti per ottenere una versione aggiornata della scorciatoia del suggerimento.

    Fornisci un valore nella colonna SUGGEST_COLUMN_SHORTCUT_ID per il suggerimento da ripetere per una versione nuova ogni volta che viene visualizzata la scorciatoia. La scorciatoia viene visualizzata rapidamente con i dati disponibili più di recente fino alla restituzione della query di aggiornamento, dopodiché il suggerimento viene aggiornato con le nuove informazioni. La query di aggiornamento viene inviata al fornitore di contenuti con un percorso URI pari a SUGGEST_URI_PATH_SHORTCUT anziché a SUGGEST_URI_PATH_QUERY.

    Imposta il criterio Cursor che restituisci per contenere un suggerimento utilizzando le stesse colonne del suggerimento originale oppure lascia vuoto il suggerimento, che indica che la scorciatoia non è più valida, nel qual caso il suggerimento scompare e la scorciatoia viene rimossa.

    Se un suggerimento si riferisce a dati il cui aggiornamento può richiedere più tempo, ad esempio un aggiornamento basato sulla rete, puoi anche aggiungere la colonna SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING alla tabella dei suggerimenti con il valore true per mostrare una rotellina di avanzamento per l'icona a destra fino al completamento dell'aggiornamento. Qualsiasi valore diverso da true non mostra la rotellina di avanzamento.

  • Impedisce del tutto che il suggerimento venga copiato in una scorciatoia.

    Specifica un valore di SUGGEST_NEVER_MAKE_SHORTCUT nella colonna SUGGEST_COLUMN_SHORTCUT_ID. In questo caso, il suggerimento non viene mai copiato in una scorciatoia. Questa operazione è necessaria solo se non vuoi assolutamente che venga visualizzato il suggerimento copiato in precedenza. Se fornisci un valore normale per la colonna, la scorciatoia del suggerimento viene visualizzata solo fino a quando non viene restituita la query di aggiornamento.

  • Consenti l'applicazione del comportamento predefinito della scorciatoia.

    Lascia vuoto il campo SUGGEST_COLUMN_SHORTCUT_ID per ogni suggerimento che non viene modificato e che può essere salvato come scorciatoia.

Se nessuno dei tuoi suggerimenti cambia, non hai bisogno della colonna SUGGEST_COLUMN_SHORTCUT_ID.

Informazioni sul ranking dei suggerimenti della Casella di ricerca rapida

Dopo aver reso disponibili i suggerimenti di ricerca della tua app alla Casella di ricerca rapida, il ranking della Casella di ricerca rapida determina il modo in cui i suggerimenti vengono mostrati all'utente per una determinata query. Ciò potrebbe dipendere da quante altre app hanno risultati per quella query e dalla frequenza con cui l'utente seleziona i tuoi risultati rispetto a quelli di altre app. Non vi è alcuna garanzia riguardo al ranking dei tuoi suggerimenti o alla loro visualizzazione o meno per una determinata query. In generale, fornire risultati di qualità aumenta la probabilità che i suggerimenti della tua app vengano forniti in una posizione in evidenza e le app che forniscono suggerimenti di bassa qualità hanno maggiori probabilità di avere un ranking più basso o non essere visualizzate.