Integrate Android search features into your app
Stay organized with collections
Save and categorize content based on your preferences.
Search is a core user feature on Android. Users must be able
to search any data that is available to them, whether the content is located on the device or
the internet. To help create a consistent search experience for users, Android provides a
search framework that helps you implement search for your application.
Figure 1. A search dialog with custom
search suggestions.
The search framework offers two modes of search input: a search dialog at the top of the
screen or a search widget (SearchView
) that you can embed in your activity
layout. In either case, the Android system assists your search implementation by
delivering search queries to a specific activity that performs searches. You can also enable
the search dialog or widget to provide search suggestions as the user types. Figure 1 shows an
example of the search dialog with optional search suggestions.
Once you set up either the search dialog or the search widget, you can do the following:
- Enable voice search.
- Provide search suggestions based on recent user queries.
- Provide custom search suggestions that match actual results in your application data.
- Offer your application's search suggestions in the system-wide Quick Search Box.
Note: The search framework does not provide APIs to
search your data. To perform a search, you need to use APIs appropriate for your data. For example,
if your data is stored in an SQLite database, use the android.database.sqlite
APIs to perform searches.
Also, there is no guarantee that a device provides a dedicated SEARCH button that invokes the
search interface in your application. When using the search dialog or a custom interface, you
must provide a search button in your UI that activates the search interface. For more
information, see Invoke the search
dialog.
The following pages show you how to use Android's framework to implement search:
- Create a search interface
- How to set up your application to use the search dialog or search widget.
- Add recent query
suggestions
- How to provide suggestions based on queries previously used.
- Add custom suggestions
- How to provide suggestions based on custom data from your application and offer them
in the system-wide Quick Search Box.
- Searchable configuration
- A reference document for the searchable configuration file. The other
documents also discuss the configuration file in terms of specific behaviors.
Protect user privacy
When you implement search in your application, take steps to protect the user's
privacy. Many users consider their activities on their phone—including searches—to
be private information. To protect users' privacy, abide by the following
principles:
- Don't send personal information to servers‐and if you must, don't log it.
Personal information is any information that can personally identify your users, such as their
names, email addresses, billing information, or other data that can be reasonably linked to such
information. If your application implements search with the assistance of a server, avoid sending
personal information along with the search queries. For example, if you are searching for businesses
near a ZIP code,
you don't need to send the user ID as well; send only the ZIP code to the server. If you must
send personal information, avoid logging it. If you must log it, protect that data
very carefully and erase it as soon as possible.
- Provide users with a way to clear their search history.
The search framework helps your application provide context-specific suggestions while the user
types. Sometimes these
suggestions are based on previous searches or other actions taken by the user in an earlier
session. A user might not want previous searches to be revealed to other device users. If your
application provides suggestions that
can reveal previous search activities, implement a way for the user to clear their
search history. If you are using SearchRecentSuggestions
,
you can call the
clearHistory()
method. If you are implementing custom suggestions, you need to provide a similar "clear history"
method in your content provider that the user can execute.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-05-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-05-20 UTC."],[],[],null,["# Integrate Android search features into your app\n\nSearch is a core user feature on Android. Users must be able\nto search any data that is available to them, whether the content is located on the device or\nthe internet. To help create a consistent search experience for users, Android provides a\nsearch framework that helps you implement search for your application. \n\n**Figure 1.** A search dialog with custom\nsearch suggestions.\n\nThe search framework offers two modes of search input: a search dialog at the top of the\nscreen or a search widget ([SearchView](/reference/android/widget/SearchView)) that you can embed in your activity\nlayout. In either case, the Android system assists your search implementation by\ndelivering search queries to a specific activity that performs searches. You can also enable\nthe search dialog or widget to provide search suggestions as the user types. Figure 1 shows an\nexample of the search dialog with optional search suggestions.\n\nOnce you set up either the search dialog or the search widget, you can do the following:\n\n- Enable voice search.\n- Provide search suggestions based on recent user queries.\n- Provide custom search suggestions that match actual results in your application data.\n- Offer your application's search suggestions in the system-wide Quick Search Box.\n\n**Note** : The search framework does *not* provide APIs to\nsearch your data. To perform a search, you need to use APIs appropriate for your data. For example,\nif your data is stored in an SQLite database, use the [android.database.sqlite](/reference/android/database/sqlite/package-summary)\nAPIs to perform searches.\n\n\u003cbr /\u003e\n\n\nAlso, there is no guarantee that a device provides a dedicated SEARCH button that invokes the\nsearch interface in your application. When using the search dialog or a custom interface, you\nmust provide a search button in your UI that activates the search interface. For more\ninformation, see [Invoke the search\ndialog](/develop/ui/views/search/search-dialog#InvokingTheSearchDialog).\n\nThe following pages show you how to use Android's framework to implement search:\n\n**[Create a search interface](/develop/ui/views/search/search-dialog)**\n: How to set up your application to use the search dialog or search widget.\n\n**[Add recent query\nsuggestions](/develop/ui/views/search/adding-recent-query-suggestions)**\n: How to provide suggestions based on queries previously used.\n\n**[Add custom suggestions](/develop/ui/views/search/adding-custom-suggestions)**\n: How to provide suggestions based on custom data from your application and offer them\n in the system-wide Quick Search Box.\n\n**[Searchable configuration](/develop/ui/views/search/searchable-config)**\n: A reference document for the searchable configuration file. The other\n documents also discuss the configuration file in terms of specific behaviors.\n\nProtect user privacy\n--------------------\n\nWhen you implement search in your application, take steps to protect the user's\nprivacy. Many users consider their activities on their phone---including searches---to\nbe private information. To protect users' privacy, abide by the following\nprinciples:\n\n- **Don't send personal information to servers‐and if you must, don't log it.**\n\n Personal information is any information that can personally identify your users, such as their\n names, email addresses, billing information, or other data that can be reasonably linked to such\n information. If your application implements search with the assistance of a server, avoid sending\n personal information along with the search queries. For example, if you are searching for businesses\n near a ZIP code,\n you don't need to send the user ID as well; send only the ZIP code to the server. If you must\n send personal information, avoid logging it. If you must log it, protect that data\n very carefully and erase it as soon as possible.\n- **Provide users with a way to clear their search history.**\n\n The search framework helps your application provide context-specific suggestions while the user\n types. Sometimes these\n suggestions are based on previous searches or other actions taken by the user in an earlier\n session. A user might not want previous searches to be revealed to other device users. If your\n application provides suggestions that\n can reveal previous search activities, implement a way for the user to clear their\n search history. If you are using [SearchRecentSuggestions](/reference/android/provider/SearchRecentSuggestions),\n you can call the\n [clearHistory()](/reference/android/provider/SearchRecentSuggestions#clearHistory())\n method. If you are implementing custom suggestions, you need to provide a similar \"clear history\"\n method in your content provider that the user can execute."]]