docs/html/guide/topics/search/index.jd

   1 page.title=Search
   2 @jd:body
   3
   4 <div id="qv-wrapper">
   5 <div id="qv">
   6 <h2>Topics</h2>
   7 <ol>
   8 <li><a href="search-dialog.html">Using the Android Search Dialog</a></li>
   9 <li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>
  10 <li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
  11 </ol>
  12 <h2>Reference</h2>
  13 <ol>
  14 <li><a href="searchable-config.html">Searchable Configuration</a></li>
  15 </ol>
  16 <h2>See also</h2>
  17 <ol>
  18 <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable
  19 Dictionary sample app</a></li>
  20 </ol>
  21 </div>
  22 </div>
  23
  24
  25 <p>The ability to search is considered to be a core user feature on Android. The user should be able
  26 to search any data that is available to them, whether the content is located on the device or the
  27 Internet. This experience should be seamless and consistent across the entire
  28 system, which is why Android provides a simple search framework to help you provide users with
  29 a familiar search dialog and a great search experience.</p>
  30
  31 <img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417"
  32 style="float:right;clear:right;" />
  33
  34 <p>Android's search framework provides a user interface in which the user can perform a search and
  35 an interaction layer that communicates with your application. This way, you don't have to build
  36 a search box that the user must find in order to begin a search. Instead,
  37 a custom search dialog will appear at the top of the screen at the user's command.
  38 The search framework will manage the search dialog and when the user executes their search, the
  39 search framework will pass the query text to your application so that your application can begin a
  40 search. The screenshot to the right shows an example of the search dialog (using
  41 search suggestions).</p>
  42
  43 <p>Once your application is set up to use the search dialog, you can:</p>
  44
  45 <ul>
  46 <li>Customize some of the search dialog characteristics</li>
  47 <li>Enable voice search</li>
  48 <li>Provide search suggestions based on recent user queries</li>
  49 <li>Provide search suggestions that match actual results in your application data</li>
  50 <li>Offer your application's search suggestions in the system-wide Quick Search Box</li>
  51 </ul>
  52
  53 <p>The following documents will teach you how to use the search dialog in
  54 your application:</p>
  55
  56 <dl>
  57   <dt><strong><a href="search-dialog.html">Using the Android Search Dialog</a></strong></dt>
  58   <dd>How to set up your application to use the search dialog for searches. </dd>
  59   <dt><strong><a href="adding-recent-query-suggestions.html">Adding Recent Query
  60 Suggestions</a></strong></dt>
  61   <dd>How to show suggestions based on queries previously used in the search dialog.</dd>
  62   <dt><strong><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></strong></dt>
  63   <dd>How to show suggestions based on custom data from your application and offer your suggestions
  64 in the system-wide Quick Search Box.</dd>
  65 </dl>
  66
  67 <p>Also, the <strong><a href="searchable-config.html">Searchable Configuration</a></strong> document
  68 provides a reference for the searchable configuration file (though the above
  69 documents also discuss the configuration file in terms of specific behaviors).</p>
  70
  71 <p class="note"><strong>Note</strong>: The search framework does <em>not</em> provide APIs to
  72 perform searches on your data. Performing actual searches is a task that you must accomplish
  73 using APIs appropriate for your data, such as those in {@link android.database.sqlite}
  74 if your data is in an SQLite database.</p>
  75
  76
  77 <h2>Protecting User Privacy</h2>
  78
  79 <p>When you implement search in your application, you should take steps to protect the user's
  80 privacy whenever possible. Many users consider their activities on the phone, including searches, to
  81 be private information. To protect the user's privacy, you should abide by the following
  82 principles:</p>
  83
  84 <ul>
  85 <li><strong>Don't send personal information to servers, and if you do, don't log it.</strong>
  86 <p>"Personal information" is information that can personally identify your users, such as their
  87 name, email address, billing information, or other data which can be reasonably linked to such
  88 information. If
  89 your application implements search with the assistance of a server, try to avoid sending personal
  90 information along with the search queries. For example, if you are searching for businesses near a
  91 zip code,
  92 you don't need to send the user ID as well &mdash; send only the zip code to the server. If you must
  93 send the personal information, you should take steps to avoid logging it. If you must log it, you
  94 should protect that data very carefully and erase it as soon as possible.</p>
  95 </li>
  96 <li><strong>Provide the user with a way to clear their search history.</strong>
  97 <p>The search framework helps your application provide context-specific suggestions while they type.
  98 Sometimes these
  99 suggestions are based on previous searches, or other actions taken by the user in an earlier
 100 session. A user may not wish for previous searches to be revealed to other users, for instance if
 101 they share their phone with a friend. If your application provides suggestions that can reveal
 102 previous activities, you should implement a "Clear History" menu item, preference, or button. If you
 103 are
 104 using {@link android.provider.SearchRecentSuggestions}, you can simply call its {@link
 105 android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing custom
 106 suggestions, you'll need to provide a
 107 similar "clear history" method in your provider that can be invoked by the user.</p>
 108 </li>
 109 </ul>
 110
 111