맞춤 검색 추천 추가

Android 검색 대화상자나 검색 위젯을 사용할 때 앱의 데이터에서 생성된 맞춤 추천 검색어를 제공할 수 있습니다. 예를 들어 앱이 사전인 경우 사용자가 검색어 입력을 완료하기 전에 검색창에 입력한 텍스트와 일치하는 단어를 사전에서 추천할 수 있습니다. 이러한 추천은 사용자가 원하는 것을 효과적으로 예측하고 즉각적인 액세스를 제공할 수 있기 때문에 중요합니다. 그림 1은 맞춤 추천이 표시된 검색 대화상자의 예를 보여줍니다.

맞춤 추천을 제공하면 시스템 전체의 빠른 검색창에서 사용할 수 있게 하여 앱 외부에서 콘텐츠에 액세스할 수도 있습니다.

맞춤 추천을 추가하기 전에 앱에서 검색을 위한 Android 검색 대화상자나 검색 위젯을 구현합니다. 검색 인터페이스 만들기콘텐츠 제공자를 참고하세요.

기본사항

그림 1. 맞춤 추천 검색어가 표시된 검색 대화상자의 스크린샷

사용자가 맞춤 추천 검색어를 선택하면 시스템은 검색 가능한 활동에 Intent를 전송합니다. ACTION_SEARCH 작업이 있는 인텐트를 전송하는 일반 검색어와 달리 ACTION_VIEW 또는 다른 인텐트 작업을 사용하고 선택된 추천 검색어와 관련된 데이터도 포함하도록 맞춤 추천 검색어를 정의할 수 있습니다. 사전 예에서 사용자가 추천 단어를 선택하면 앱이 일치 항목을 사전에서 검색하는 대신 즉시 해당 단어의 정의를 열 수 있습니다.

맞춤 추천을 제공하려면 다음 단계를 따르세요.

  • 검색 인터페이스 만들기에 설명된 대로 기본 검색 활동을 구현합니다.
  • 맞춤 추천 검색어를 제공하는 콘텐츠 제공자에 관한 정보로 검색 가능한 구성을 수정합니다.
  • SQLiteDatabase와 같은 추천에 사용할 표를 만들고 필수 열로 표의 형식을 지정합니다.
  • 추천 검색어 표에 액세스할 수 있는 콘텐츠 제공자를 만들고 매니페스트에서 제공자를 선언합니다.
  • 사용자가 추천 작업(맞춤 작업 및 맞춤 데이터 포함)을 선택할 때 전송할 Intent 유형을 선언합니다.

Android 시스템은 검색 대화상자를 표시하는 것처럼 추천 검색어도 표시합니다. 시스템이 추천을 검색할 수 있는 콘텐츠 제공자가 필요합니다. 콘텐츠 제공자를 만드는 방법은 콘텐츠 제공자를 참고하세요.

시스템에서 활동이 검색 가능한 것으로 식별하고 추천 검색어를 제공하면 사용자가 쿼리를 입력할 때 다음 절차가 진행됩니다.

  1. 시스템은 검색어 텍스트(지금까지 입력된 내용)를 가져와 추천 검색어를 관리하는 콘텐츠 제공자에 쿼리를 실행합니다.
  2. 콘텐츠 제공자가 검색어 텍스트와 관련된 모든 추천 검색어를 가리키는 Cursor를 반환합니다.
  3. 시스템은 Cursor에서 제공하는 추천 목록을 표시합니다.

맞춤 추천 검색어가 표시되면 다음과 같은 결과가 발생할 수 있습니다.

  • 사용자가 다른 문자를 입력하거나 어떤 식으로든 쿼리를 변경하면 이전 단계가 반복되고 그에 따라 추천 검색어 목록이 업데이트됩니다.
  • 사용자가 검색을 실행하면 추천 검색어가 무시되고 검색이 일반 ACTION_SEARCH 인텐트를 사용하여 검색 가능 활동에 전달됩니다.
  • 사용자가 추천 검색어를 선택하면 앱에서 추천 콘텐츠를 열 수 있도록 맞춤 작업과 맞춤 데이터를 포함하는 인텐트가 검색 활동에 전송됩니다.

검색 가능한 구성 수정하기

맞춤 추천 검색어 지원을 추가하려면 다음 예와 같이 검색 가능한 구성 파일의 <searchable> 요소에 android:searchSuggestAuthority 속성을 추가합니다.

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

각 추천 검색어에 첨부하는 인텐트 유형 및 콘텐츠 제공업체에 쿼리 형식을 지정하는 방법에 따라 추가 속성이 필요할 수 있습니다. 다른 선택적 속성은 다음 섹션에서 설명합니다.

콘텐츠 제공자 만들기

맞춤 추천 검색어를 위한 콘텐츠 제공자를 만들려면 먼저 콘텐츠 제공자를 참고하여 콘텐츠 제공자를 만드는 방법을 알아보세요. 맞춤 추천의 콘텐츠 제공자는 다른 콘텐츠 제공자와 유사합니다. 하지만 개발자가 제공하는 각 추천의 경우 Cursor의 각 행에는 시스템에서 파악하고 추천의 형식을 지정하는 데 사용하는 특정 열이 포함되어야 합니다.

사용자가 검색 대화상자나 검색 위젯에 텍스트를 입력하면 시스템은 문자가 입력될 때마다 query()를 호출하여 콘텐츠 제공자에 추천 검색어를 쿼리합니다. query() 구현에서 콘텐츠 제공자는 추천 데이터를 검색하고 적절한 추천이라고 판단되는 행을 가리키는 Cursor를 반환해야 합니다.

맞춤 추천 검색어를 위한 콘텐츠 제공자 만들기에 관한 자세한 내용은 다음 두 섹션에서 설명합니다.

추천 쿼리 처리
시스템이 콘텐츠 제공자에게 요청을 보내는 방법 및 요청을 처리하는 방법입니다.
추천 검색어 표 작성하기
각 쿼리로 반환되는 Cursor에서 시스템이 기대하는 열을 정의하는 방법

추천 쿼리 처리

시스템이 콘텐츠 제공자에 추천을 요청하면 콘텐츠 제공자의 query() 메서드를 호출합니다. 이 메서드를 구현하여 추천 데이터를 검색하고 관련성이 있다고 생각되는 추천을 가리키는 Cursor를 반환합니다.

다음은 시스템이 query() 메서드에 전달하는 매개변수를 순서대로 요약한 것입니다.

  1. uri

    항상 콘텐츠 Uri이며 다음과 같은 형식으로 지정됩니다.

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

    기본 동작은 시스템에서 이 URI를 전달하고 여기에 쿼리 텍스트를 추가하는 것입니다.

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

    끝의 쿼리 텍스트는 URI 인코딩 규칙을 사용하여 인코딩되므로 검색을 실행하기 전에 디코딩해야 할 수도 있습니다.

    optional.suggest.path 부분은 검색 가능한 구성 파일에서 android:searchSuggestPath 속성을 사용하여 그러한 경로를 설정한 경우에만 URI에 포함됩니다. 여러 검색 활동에 동일한 콘텐츠 제공자를 사용하는 경우에만 필요합니다. 이 경우 추천 쿼리의 소스를 명확하게 구분하세요.

  2. projection
    항상 null입니다.
  3. selection
    검색 가능한 구성 파일의 android:searchSuggestSelection 속성에 제공된 값 또는 android:searchSuggestSelection 속성을 선언하지 않은 경우 null입니다. 다음 섹션에서 이에 관해 자세히 설명합니다.
  4. selectionArgs
    검색 가능한 구성에서 android:searchSuggestSelection 속성을 선언하는 경우 검색어를 배열의 첫 번째이자 유일한 요소로 포함합니다. android:searchSuggestSelection를 선언하지 않으면 이 매개변수는 null입니다. 다음 섹션에서 이에 관해 자세히 설명합니다.
  5. sortOrder
    항상 null입니다.

시스템은 두 가지 방법으로 검색어 텍스트를 전송할 수 있습니다. 기본 방법은 쿼리 텍스트를 uri 매개변수에 전달된 콘텐츠 URI의 마지막 경로로 포함하는 것입니다. 그러나 검색 가능한 구성의 android:searchSuggestSelection 속성에 선택 값을 포함하면 쿼리 텍스트가 selectionArgs 문자열 배열의 첫 번째 요소로 전달됩니다. 이 두 옵션은 다음에 설명되어 있습니다.

URI에서 쿼리 가져오기

기본적으로 쿼리는 uri 매개변수의 마지막 세그먼트(Uri 객체)로 추가됩니다. 이 경우 쿼리 텍스트를 검색하려면 다음 예와 같이 getLastPathSegment()를 사용합니다.

Kotlin

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

Java

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

이렇게 하면 사용자가 입력하는 쿼리 텍스트인 Uri의 마지막 세그먼트가 반환됩니다.

선택 인수에서 쿼리 가져오기

URI를 사용하는 대신 query() 메서드가 조회를 실행하는 데 필요한 모든 항목을 수신하는 것이 더 합리적일 수 있으며 selectionselectionArgs 매개변수가 적절한 값을 포함하도록 할 수 있습니다. 이 경우 SQLite 선택 문자열을 사용하여 검색 가능한 구성에 android:searchSuggestSelection 속성을 추가합니다. 선택 문자열에 실제 검색어의 자리표시자로 물음표 (?)를 포함합니다. 시스템은 선택 문자열을 selection 매개변수로, 검색어를 selectionArgs 배열의 첫 번째 요소로 사용하여 query()를 호출합니다.

예를 들어 android:searchSuggestSelection 속성을 만들어 전체 텍스트 검색 구문을 만드는 방법은 다음과 같습니다.

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

이 구성을 사용하면 query() 메서드가 selection 매개변수를 "word MATCH ?"로, selectionArgs 매개변수를 검색어로 전달합니다. 이를 SQLite query() 메서드에 각각의 인수로 전달하면 이러한 항목은 함께 합성됩니다. 즉, 물음표가 쿼리 텍스트로 대체됩니다. 이런 방식으로 추천 쿼리를 수신하고 쿼리 텍스트에 와일드 카드를 추가해야 하는 경우 selectionArgs 매개변수에 와일드 카드를 추가하거나 접두사로 추가합니다. 이 값은 따옴표로 묶여 물음표 대신 삽입되기 때문입니다.

앞의 예에서 또 다른 속성은 android:searchSuggestIntentAction로, 사용자가 추천 검색어를 선택할 때 각 인텐트와 함께 전송되는 인텐트 작업을 정의합니다. 자세한 내용은 추천 인텐트 선언 섹션에서 자세히 설명합니다.

추천 검색어 표 만들기

Cursor를 사용하여 시스템에 추천을 반환하면 시스템은 각 행에 특정 열을 기대합니다. 추천 데이터를 기기의 SQLite 데이터베이스에 저장하든, 웹 서버의 데이터베이스에 저장하든, 기기 또는 웹에 다른 형식을 저장하든 관계없이 추천 항목을 테이블의 행 형식으로 지정하고 Cursor와 함께 표시합니다.

시스템은 여러 열을 인식할 수 있지만 그중 두 개만 필수입니다.

_ID
각 추천 검색어의 고유한 정수 행 ID입니다. 시스템에서는 이를 통해 ListView에 추천을 표시하도록 요구합니다.
SUGGEST_COLUMN_TEXT_1
추천 검색어로 표시되는 문자열입니다.

다음 열은 모두 선택사항입니다. 대부분은 다음 섹션에서 자세히 설명합니다.

SUGGEST_COLUMN_TEXT_2
문자열입니다. Cursor에 이 열이 포함된 경우 모든 추천 검색어가 두 줄 형식으로 제공됩니다. 이 열의 문자열은 기본 추천 텍스트 아래에 두 번째 텍스트 줄로 더 짧게 표시됩니다. null이거나 비어 있을 수 있으며 이 경우 보조 텍스트가 없음을 나타냅니다.
SUGGEST_COLUMN_ICON_1
드로어블 리소스, 콘텐츠, 파일 URI 문자열입니다. Cursor에 이 열이 포함된 경우 모든 추천 검색어는 아이콘 + 텍스트 형식으로 제공되고 왼쪽에 드로어블 아이콘이 있습니다. null이거나 0일 수 있으며 이 값은 이 행에 아이콘이 없음을 나타냅니다.
SUGGEST_COLUMN_ICON_2
드로어블 리소스, 콘텐츠, 파일 URI 문자열입니다. Cursor에 이 열이 포함된 경우 모든 추천은 아이콘 + 텍스트 형식으로 제공되며 오른쪽에 아이콘이 있습니다. null이거나 0일 수 있으며 이 값은 이 행에 아이콘이 없음을 나타냅니다.
SUGGEST_COLUMN_INTENT_ACTION
인텐트 작업 문자열입니다. 이 열이 존재하고 지정된 행에 값이 있으면 추천 검색어의 인텐트를 구성할 때 여기에 정의된 작업이 사용됩니다. 이 요소가 제공되지 않으면 검색 가능한 구성의 android:searchSuggestIntentAction 필드에서 작업이 수행됩니다. 작업이 모든 추천 검색어에서 동일한 경우 android:searchSuggestIntentAction를 사용하여 작업을 지정하고 이 열을 생략하는 것이 더 효율적입니다.
SUGGEST_COLUMN_INTENT_DATA
데이터 URI 문자열입니다. 이 열이 존재하고 지정된 행에 값이 있으면 추천 검색어의 인텐트를 구성할 때 이 데이터가 사용됩니다. 이 요소가 제공되지 않으면 검색 가능한 구성의 android:searchSuggestIntentData 필드에서 데이터를 가져옵니다. 두 소스 모두 제공되지 않으면 인텐트의 데이터 필드는 null입니다. 모든 추천 검색어의 데이터가 동일하거나 상수 부분과 특정 ID를 사용하여 데이터를 설명할 수 있는 경우에는 android:searchSuggestIntentData를 사용하여 데이터를 지정하고 이 열을 생략하는 것이 더 효율적입니다.
SUGGEST_COLUMN_INTENT_DATA_ID
URI 경로 문자열입니다. 이 열이 존재하고 지정된 행에 값이 있으면 '/'와 이 값이 인텐트의 데이터 필드에 추가됩니다. 검색 가능한 구성의 android:searchSuggestIntentData 속성으로 지정된 데이터 필드가 이미 적절한 기본 문자열로 설정된 경우에만 사용합니다.
SUGGEST_COLUMN_INTENT_EXTRA_DATA
임의의 데이터입니다. 이 열이 존재하고 지정된 행에 값이 포함된 경우 추천 검색어의 인텐트를 구성할 때 사용되는 추가 데이터입니다. 제공되지 않은 경우 인텐트의 추가 데이터 필드는 null입니다. 이 열을 사용하면 추천에서 인텐트의 EXTRA_DATA_KEY 키에 추가 항목으로 포함된 추가 데이터를 제공할 수 있습니다.
SUGGEST_COLUMN_QUERY
이 열이 있고 이 요소가 지정된 행에 있으면 추천 검색어의 쿼리를 구성할 때 사용되는 데이터로, 인텐트의 QUERY 키에 추가 항목으로 포함됩니다. 추천의 작업이 ACTION_SEARCH인 경우 필수이지만 그렇지 않은 경우에는 선택사항입니다.
SUGGEST_COLUMN_SHORTCUT_ID
빠른 검색창에 추천 검색어를 제공할 때만 사용됩니다. 이 열은 추천 검색어를 바로가기로 저장해야 하는지 여부와 유효성을 검사해야 하는지를 나타냅니다. 바로가기는 일반적으로 사용자가 빠른 검색창에서 추천 검색어를 탭하면 생성됩니다. 누락된 경우 결과는 바로가기로 저장되고 새로고침되지 않습니다. SUGGEST_NEVER_MAKE_SHORTCUT로 설정하면 결과가 바로가기로 저장되지 않습니다. 그 외의 경우에는 바로가기 ID가 SUGGEST_URI_PATH_SHORTCUT를 사용한 최신 추천을 다시 확인하는 데 사용됩니다.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
빠른 검색창에 추천 검색어를 제공할 때만 사용됩니다. 이 열은 빠른 검색창에서 이 추천 검색어의 바로가기가 새로고침되는 동안 SUGGEST_COLUMN_ICON_2의 아이콘 대신 스피너를 표시해야 한다고 지정합니다.

이러한 열의 대부분은 다음 섹션에서 자세히 설명합니다.

추천 인텐트 선언

사용자가 검색 대화상자 또는 위젯 아래에 표시되는 목록에서 추천 검색어를 선택하면 시스템은 맞춤 Intent를 검색 가능한 활동에 전송합니다. 인텐트의 작업과 데이터를 정의해야 합니다.

인텐트 작업 선언

맞춤 추천의 가장 일반적인 인텐트 작업은 ACTION_VIEW로, 단어의 정의, 사람의 연락처 정보 또는 웹페이지와 같은 항목을 열려고 할 때 적합합니다. 그러나 인텐트 작업은 다른 작업일 수 있으며 추천마다 다를 수 있습니다.

모든 추천에서 동일한 인텐트 작업을 사용할지에 따라 다음 두 가지 방법으로 작업을 정의할 수 있습니다.

  • 다음 예와 같이 검색 가능한 구성 파일의 android:searchSuggestIntentAction 속성을 사용하여 모든 추천 검색어의 작업을 정의합니다.
    <?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>
    
  • SUGGEST_COLUMN_INTENT_ACTION 열을 사용하여 개별 추천 검색어의 작업을 정의합니다. 이렇게 하려면 추천 검색어 표에 SUGGEST_COLUMN_INTENT_ACTION 열을 추가하고 각 추천에 관해 사용할 작업(예: "android.intent.action.VIEW")에 배치합니다.

위의 두 기법을 결합할 수도 있습니다. 예를 들어 기본적으로 모든 추천에 사용할 작업과 함께 android:searchSuggestIntentAction 속성을 포함한 후 SUGGEST_COLUMN_INTENT_ACTION 열에서 다른 작업을 선언하여 일부 추천에 이 작업을 재정의할 수 있습니다. SUGGEST_COLUMN_INTENT_ACTION 열에 값을 포함하지 않으면 android:searchSuggestIntentAction 속성에 제공된 인텐트가 사용됩니다.

인텐트 데이터 선언

사용자가 추천 검색어를 선택하면 이전 섹션에서 설명한 것처럼 검색 가능 활동은 개발자가 정의한 작업이 포함된 인텐트를 수신하지만 어떤 추천 검색어가 선택되었는지 식별할 수 있도록 인텐트에는 활동 관련 데이터도 포함되어 있어야 합니다. 특히 데이터는 추천 검색어별로 고유해야 합니다(예: SQLite 테이블에 있는 추천의 행 ID). 인텐트가 수신되면 getData() 또는 getDataString()를 사용하여 연결된 데이터를 검색할 수 있습니다.

인텐트에 포함되는 데이터는 다음 두 가지 방법으로 정의할 수 있습니다.

  • 추천 검색어 표의 SUGGEST_COLUMN_INTENT_DATA 열 내에서 각 추천 검색어의 데이터를 정의합니다.

    추천 검색어 표에 SUGGEST_COLUMN_INTENT_DATA 열을 포함한 다음 각 행의 고유 데이터를 입력하여 각 인텐트에 필요한 모든 데이터 정보를 제공합니다. 이 열의 데이터는 이 열에서 정의한 그대로 인텐트에 연결됩니다. 그런 다음 getData() 또는 getDataString()를 사용하여 검색할 수 있습니다.

  • 데이터 URI를 모든 추천에 공통된 부분과 각 추천에 고유한 부분, 이렇게 두 부분으로 프래그먼트화합니다. 이 부분을 검색 가능한 구성의 android:searchSuggestintentData 속성과 추천 검색어 표의 SUGGEST_COLUMN_INTENT_DATA_ID 열에 각각 배치합니다.

    다음 예에서는 검색 가능한 구성의 android:searchSuggestIntentData 속성에 있는 모든 추천 검색어에 공통된 URI 부분을 선언하는 방법을 보여줍니다.

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

    추천 검색어 표의 SUGGEST_COLUMN_INTENT_DATA_ID 열에 각 추천 검색어의 최종 경로(고유한 부분)를 포함합니다. 사용자가 추천 검색어를 선택하면 시스템은 android:searchSuggestIntentData에서 문자열을 가져와 슬래시 (/)를 추가한 다음 SUGGEST_COLUMN_INTENT_DATA_ID 열에서 각 값을 추가하여 전체 콘텐츠 URI를 구성합니다. 그런 다음 getData()를 사용하여 Uri를 가져올 수 있습니다.

데이터 추가하기

인텐트로 더 많은 정보를 표현해야 하는 경우 추천 항목에 관한 추가 정보를 저장할 수 있는 SUGGEST_COLUMN_INTENT_EXTRA_DATA와 같은 다른 테이블 열을 추가할 수 있습니다. 이 열에 저장된 데이터는 인텐트 추가 번들의 EXTRA_DATA_KEY에 배치됩니다.

인텐트 처리

맞춤 인텐트가 포함된 맞춤 추천 검색어를 제공한 후에는 사용자가 추천을 선택할 때 이러한 인텐트를 처리할 검색 활동이 필요합니다. 이는 검색 활동이 이미 수행하고 있는 ACTION_SEARCH 인텐트 처리에 추가되는 것입니다. 다음은 활동의 onCreate() 콜백 중에 인텐트를 처리할 수 있는 방법의 예입니다.

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

이 예에서 인텐트 작업은 ACTION_VIEW이고 데이터는 android:searchSuggestIntentData 문자열과 SUGGEST_COLUMN_INTENT_DATA_ID 열에 의해 합성된 추천 항목을 가리키는 전체 URI를 포함합니다. 그러면 URI가 로컬 showResult() 메서드로 전달되며, 이 메서드는 URI로 지정된 항목을 콘텐츠 제공업체에 쿼리합니다.

쿼리 텍스트 다시 작성

기본적으로 사용자가 트랙볼이나 D패드와 같은 방향 컨트롤을 사용하여 추천 검색어 목록을 탐색하면 쿼리 텍스트가 업데이트되지 않습니다. 그러나 텍스트 상자에 표시되는 사용자의 쿼리 텍스트를 포커스가 있는 추천과 일치하는 쿼리로 임시로 다시 작성할 수 있습니다. 이렇게 하면 사용자가 추천되는 쿼리를 볼 수 있으며, 검색창을 선택하고 쿼리를 수정한 후에 검색으로 전달할 수 있습니다.

쿼리 텍스트를 다시 쓸 수 있는 방법은 다음과 같습니다.

  • "queryRewriteFromText" 값을 사용하여 검색 가능한 구성에 android:searchMode 속성을 추가합니다. 이 경우 추천 검색어의 SUGGEST_COLUMN_TEXT_1 열에 있는 콘텐츠가 쿼리 텍스트를 다시 쓰는 데 사용됩니다.
  • "queryRewriteFromData" 값을 사용하여 검색 가능한 구성에 android:searchMode 속성을 추가합니다. 이 경우 추천 검색어의 SUGGEST_COLUMN_INTENT_DATA 열에 있는 콘텐츠가 쿼리 텍스트를 다시 쓰는 데 사용됩니다. HTTP URL과 같이 사용자에게 표시되는 URI 또는 기타 데이터 형식에만 사용하세요. 이 방식으로 쿼리를 다시 작성하는 데 내부 URI 스키마를 사용하지 마세요.
  • 추천 검색어 표의 SUGGEST_COLUMN_QUERY 열에 고유한 쿼리 텍스트 문자열을 제공합니다. 이 열이 있고 현재 추천 항목의 값을 포함하는 경우 쿼리 텍스트를 다시 쓰고 이전 구현 중 하나를 재정의하는 데 사용됩니다.

추천 검색어를 빠른 검색창에 노출

맞춤 추천 검색어를 제공하도록 앱을 구성한 후에는 전역적으로 액세스할 수 있는 빠른 검색창에서 추천 검색어를 제공하기만 하면 됩니다. 이렇게 하면 android:includeInGlobalSearch"true" 값과 함께 포함하도록 검색 가능한 구성을 쉽게 수정할 수 있습니다.

추가 작업이 필요한 유일한 시나리오는 콘텐츠 제공자가 읽기 권한을 요구하는 경우입니다. 이 경우 다음 예와 같이 콘텐츠 제공자에 빠른 검색창 읽기 액세스 권한을 부여하려면 제공자의 <path-permission> 요소를 추가해야 합니다.

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

이 예에서 제공자는 콘텐츠에 관한 읽기 및 쓰기 액세스를 제한합니다. <path-permission> 요소는 "android.permission.GLOBAL_SEARCH" 권한이 있는 경우 "/search_suggest_query" 경로 접두사 내부의 콘텐츠에 대한 읽기 액세스 권한을 부여하여 제한을 수정합니다. 이렇게 하면 콘텐츠 제공자에 추천 검색어를 쿼리할 수 있도록 빠른 검색창에 대한 액세스 권한이 부여됩니다.

콘텐츠 제공자가 읽기 권한을 적용하지 않으면 빠른 검색창이 기본적으로 읽기 권한을 읽습니다.

기기에서 추천 기능 사용 설정하기

기본적으로 앱은 빠른 검색창에 추천 검색어를 제공하도록 구성되어 있지만 빠른 검색창에 추천을 제공하도록 설정되어 있지 않습니다. 사용자는 설정 > 검색에 있는 검색 가능한 항목을 열고 앱을 검색 가능한 항목으로 사용 설정하여 빠른 검색창에 앱의 추천을 포함할지 여부를 선택합니다.

빠른 검색창에서 사용할 수 있는 각 앱은 검색 가능한 항목 설정 페이지에 항목이 있습니다. 항목에는 앱 이름과 앱에서 검색할 수 있고 빠른 검색창에서 추천 검색어로 사용할 수 있는 콘텐츠에 관한 간단한 설명이 포함됩니다. 검색 가능한 앱의 설명 텍스트를 정의하려면 다음 예와 같이 검색 가능한 구성에 android:searchSettingsDescription 속성을 추가합니다.

<?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의 문자열은 최대한 간결하고 검색 가능한 콘텐츠를 명시해야 합니다. 예를 들어 음악 앱의 경우 '아티스트, 앨범 및 트랙'이, 메모장 앱의 경우 '저장된 메모'가 있습니다. 이 설명을 제공하는 것은 사용자가 어떤 종류의 추천이 제공되는지 알 수 있도록 중요합니다. android:includeInGlobalSearch가 true인 경우 항상 이 속성을 포함합니다.

사용자가 설정 메뉴를 방문하여 앱의 추천 검색어를 사용 설정해야 하므로 검색이 앱에서 중요한 부분이라면 이를 사용자에게 전달하는 방법을 고려하세요. 예를 들어 사용자가 앱을 처음 실행할 때 빠른 검색창에 추천 검색어를 사용 설정하는 방법을 설명하는 메모를 제공할 수 있습니다.

빠른 검색창 추천 검색어 관리

사용자가 빠른 검색창에서 선택하는 추천 검색어를 바로가기로 자동 만들 수 있습니다. 이는 시스템이 콘텐츠 제공자에서 다시 쿼리하지 않고도 추천 항목에 빠르게 액세스할 수 있도록 콘텐츠 제공자에서 복사하는 추천입니다.

이 기능은 기본적으로 빠른 검색창에서 가져온 모든 추천 검색어에 사용 설정되어 있지만 시간이 지남에 따라 추천 데이터가 변경되면 바로가기를 새로고침하도록 요청할 수 있습니다. 예를 들어 추천이 연락처의 현재 상태와 같은 동적 데이터를 참조하는 경우 사용자에게 표시될 때 추천 바로가기를 새로고침하도록 요청합니다. 이렇게 하려면 추천사항 표에 SUGGEST_COLUMN_SHORTCUT_ID를 포함하세요. 이 열을 사용하여 다음 방법 중 하나로 각 추천 검색어의 바로가기 동작을 구성할 수 있습니다.

  • 빠른 검색창에서 새로운 버전의 추천 검색어 바로가기를 위해 콘텐츠 제공자를 다시 쿼리합니다.

    바로가기가 표시될 때마다 새로운 버전을 다시 쿼리하도록 SUGGEST_COLUMN_SHORTCUT_ID 열에 값을 제공합니다. 바로가기는 새로고침 쿼리가 반환될 때까지 가장 최근에 사용 가능한 데이터로 빠르게 표시되며, 새로고침 쿼리가 반환되면 추천 검색어가 새로운 정보로 새로고침됩니다. 새로고침 쿼리는 SUGGEST_URI_PATH_QUERY 대신 SUGGEST_URI_PATH_SHORTCUT의 URI 경로를 사용하여 콘텐츠 제공업체에 전송됩니다.

    반환되는 Cursor가 원래 추천 검색어와 동일한 열을 사용하는 추천 검색어 하나를 포함하거나 비어 있도록 합니다. 이는 바로가기가 더 이상 유효하지 않음을 나타냅니다. 이 경우 추천은 사라지고 바로가기가 삭제됩니다.

    추천 검색어가 네트워크 기반 새로고침과 같이 새로고침하는 데 더 오래 걸릴 수 있는 데이터를 참조하는 경우(예: 네트워크 기반 새로고침) 추천 검색어 표에 SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING 열을 추가하여 새로고침이 완료될 때까지 오른쪽 아이콘의 진행률 스피너를 표시할 수도 있습니다. true 이외의 값은 진행률 스피너를 표시하지 않습니다.

  • 추천 항목이 바로가기에 복사되지 않도록 합니다.

    SUGGEST_COLUMN_SHORTCUT_ID 열에 SUGGEST_NEVER_MAKE_SHORTCUT 값을 제공합니다. 이 경우 추천은 바로가기에 복사되지 않습니다. 이 작업은 이전에 복사한 추천 검색어를 절대로 표시하지 않으려는 경우에만 필요합니다. 열에 일반 값을 제공하면 새로고침 쿼리가 반환될 때까지만 추천 검색어 바로가기가 표시됩니다.

  • 기본 바로가기 동작이 적용되도록 합니다.

    변경되지 않으며 바로가기로 저장할 수 있는 각 추천에 관해 SUGGEST_COLUMN_SHORTCUT_ID를 비워 둡니다.

추천이 변경되지 않으면 SUGGEST_COLUMN_SHORTCUT_ID 열이 필요하지 않습니다.

빠른 검색창 추천 검색어 순위 정보

앱의 추천 검색어를 빠른 검색창에서 사용할 수 있게 하면 빠른 검색창 순위에 따라 특정 검색어와 관련하여 사용자에게 추천 검색어가 표시되는 방식이 결정됩니다. 이는 해당 쿼리의 결과가 있는 다른 앱의 수 및 사용자가 다른 앱의 결과와 비교하여 결과를 선택하는 빈도에 따라 다를 수 있습니다. 추천 검색어의 순위 지정 방식이나 특정 쿼리에 관해 앱의 추천 검색어가 표시되는지 여부는 보장되지 않습니다. 일반적으로 양질의 결과를 제공하면 앱의 추천이 눈에 잘 띄는 위치에 제공될 가능성이 높아지며 품질이 낮은 추천을 제공하는 앱은 순위가 낮아지거나 표시되지 않을 가능성이 높습니다.