Google은 흑인 공동체를 위한 인종 간 평등을 진전시키기 위해 노력하고 있습니다. Google에서 어떤 노력을 하고 있는지 확인하세요.

맞춤 제안 추가

Android 검색 대화상자나 검색 위젯을 사용할 때 애플리케이션의 데이터에서 생성된 맞춤 추천 검색어를 제공할 수 있습니다. 예를 들어 애플리케이션이 단어 사전인 경우 사전에서 지금까지 입력된 텍스트와 일치하는 단어를 추천할 수 있습니다. 사용자가 원하는 것을 효과적으로 예측하고 즉시 액세스를 제공할 수 있기 때문에 가장 가치있는 추천 검색어입니다. 그림 1은 맞춤 추천 검색어가 있는 검색 대화상자의 예입니다.

맞춤 추천 검색어를 제공하면 시스템 전체의 빠른 검색창에도 이 검색어를 표시할 수 있으며 이를 통해 애플리케이션 외부에서 콘텐츠에 액세스할 수 있습니다.

이 가이드 내용에 따라 맞춤 추천 검색어를 추가하기 전에 먼저 애플리케이션의 검색을 위해 Android 검색 대화상자나 검색 위젯을 구현해야 합니다. 아직 확인하지 않은 경우 검색 인터페이스 만들기를 참고하세요. 콘텐츠 제공자 문서도 참고해야 합니다.

기본 사항

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

사용자가 맞춤 추천 검색어를 선택하면 Android 시스템은 검색 활동에 Intent를 전송합니다. 일반 검색은 ACTION_SEARCH 작업이 있는 인텐트를 전송하지만, 대신 ACTION_VIEW(또는 다른 인텐트 작업)를 사용하도록 맞춤 추천 검색어를 정의할 수 있으며 선택한 추천 검색어와 관련 있는 데이터도 포함할 수 있습니다. 앞에서 말한 사전 예에서 사용자가 추천 검색어를 선택하면 애플리케이션은 일치하는 단어를 사전에서 검색하는 대신 즉시 단어의 정의를 열 수 있습니다.

맞춤 추천 검색어를 제공하려면 다음을 따르세요.

  • 검색 인터페이스 만들기에 설명된 대로 기본 검색 활동을 구현합니다.
  • 맞춤 추천 검색어를 제공하는 콘텐츠 제공자에 관한 정보로 검색 가능한 구성을 수정합니다.
  • 추천 검색어 표(예: SQLiteDatabase의 표)를 작성하고 필수 열로 표의 형식을 지정합니다.
  • 추천 검색어 표에 액세스할 수 있는 콘텐츠 제공자를 만들고 이 제공자를 manifest에서 선언합니다.
  • 사용자가 추천 검색어(맞춤 작업 및 맞춤 데이터 포함)를 선택하면 전송할 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() 메서드에 전달하는 매개변수를 요약했습니다(순서대로 나열됨).

uri
항상 콘텐츠 Uri이며 다음과 같은 형식으로 지정합니다.
    content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY
    

기본 동작은 시스템이 이 URI를 전달하고 URI에 쿼리 텍스트를 추가하는 것입니다. 예를 들어 다음과 같습니다.

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

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

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

참고: SUGGEST_URI_PATH_QUERY는 URI에 제공되는 리터럴 문자열이 아니라 이 경로를 참조해야 하는 경우 사용해야 하는 상수입니다.

projection
항상 null입니다.
selection
검색 가능한 구성 파일의 android:searchSuggestSelection 속성에 제공된 값 또는 android:searchSuggestSelection 속성을 선언하지 않은 경우 null입니다. 아래에서 이 매개변수를 사용하여 쿼리를 가져오는 방법을 자세히 알아보세요.
selectionArgs
검색 가능한 구성에서 android:searchSuggestSelection 속성을 선언한 경우 검색어를 배열의 첫 번째(유일한) 요소로 포함합니다. android:searchSuggestSelection을 선언하지 않았다면 이 매개변수는 null입니다. 아래에서 이 매개변수를 사용하여 쿼리를 가져오는 방법을 자세히 알아보세요.
sortOrder
항상 null입니다.

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

URI에서 쿼리 가져오기

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

Kotlin

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

자바

    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() 메서드는 "word MATCH ?"selection 매개변수로, 검색어를 selectionArgs 매개변수로 전달합니다. 이러한 매개변수를 SQLite query() 메서드에 개별 인수로 전달하면 매개변수가 합성되며 물음표가 쿼리 텍스트로 대체됩니다. 이런 방식으로 추천 쿼리를 수신하려는 경우 쿼리 텍스트에 와일드 카드를 추가해야 한다면 selectionArgs 매개변수에 추가(또는 매개변수 앞에 추가)합니다. 이 값은 따옴표로 싸여 물음표 대신 삽입되기 때문입니다.

위 예에서 또 다른 새로운 속성은 android:searchSuggestIntentAction이며 이 속성은 사용자가 추천 검색어를 선택할 때 각 인텐트와 함께 전송되는 인텐트 작업을 정의합니다. 이 속성에 관해서는 추천 검색어용 인텐트 선언하기 섹션에서 더 자세히 설명합니다.

도움말: android:searchSuggestSelection 속성에서 선택 절을 정의하지 않지만 selectionArgs 매개변수에서 쿼리 텍스트를 검색하려는 경우에는 android:searchSuggestSelection 속성에 null이 아닌 값을 제공하면 됩니다. 그러면 쿼리가 selectionArgs에 전달되고 selection 매개변수를 무시해도 됩니다. 이런 방식을 사용하면 콘텐츠 제공자가 처리할 필요가 없도록 대신 하위 수준에서 실제 선택 절을 정의할 수 있습니다.

추천 검색어 표 작성하기

Cursor를 통해 추천 검색어를 시스템에 반환하면 시스템은 행별로 특정 열을 기대합니다. 따라서 추천 데이터를 기기의 SQLite 데이터베이스에 저장하든, 데이터베이스를 웹 서버에 저장하든, 다른 형식을 기기나 웹에 저장하든 관계없이 추천 검색어를 표의 행 형식으로 지정하고 Cursor를 사용해 추천 검색어를 표시해야 합니다.

참고: 추천 검색어가 시스템에 필요한 열을 사용하는 표 형식(예: SQLite 표)으로 저장되지 않은 경우 추천 데이터를 검색해 일치하는 항목을 찾아 각 요청에서 필요한 표 형식으로 지정합니다. 이렇게 하려면 필수 열 이름을 사용해 MatrixCursor를 만든 후에 addRow(Object[])를 사용해 추천 검색어별로 행을 추가합니다. 콘텐츠 제공자의 query() 메서드에서 최종 결과를 반환합니다.

시스템에서 여러 열이 인식되며 그중 필수 열은 2개입니다.

_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이며 단어의 정의, 사용자의 연락처 정보, 웹페이지와 같은 항목을 열 때 적합합니다. 그러나 인텐트 작업은 이와 다른 작업일 수 있으며 추천 검색어별로 다를 수도 있습니다.

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

  1. 검색 가능한 구성 파일의 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>
        
  2. SUGGEST_COLUMN_INTENT_ACTION 열을 사용하여 개별 추천 검색어의 작업을 정의합니다.

    SUGGEST_COLUMN_INTENT_ACTION 열을 추천 검색어 표에 추가하고 추천 검색어별로 사용할 작업(예: "android.intent.action.VIEW")을 입력합니다.

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

참고: 검색 가능한 구성에 android:searchSuggestIntentAction 속성을 포함하지 않는 경우 모든 추천 검색어에 관해 SUGGEST_COLUMN_INTENT_ACTION 열에 값을 포함해야 합니다. 그러지 않으면 인텐트가 실패합니다.

인텐트 데이터 선언하기

사용자가 추천 검색어를 선택하면 개발자가 정의한 작업(이전 섹션의 설명)이 있는 인텐트가 검색 활동에 수신되지만, 활동이 어느 추천 검색어가 선택되었는지 식별하려면 인텐트에 데이터도 있어야 합니다. 특히 이 데이터는 추천 검색어별로 고유해야 합니다(예: SQLite 표에서 추천 검색어의 행 ID). 인텐트가 수신되면 getData() 또는 getDataString()을 사용해 추가된 데이터를 검색할 수 있습니다.

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

  1. 추천 검색어 표의 SUGGEST_COLUMN_INTENT_DATA 열 안에서 추천 검색어별로 데이터를 정의합니다.

    추천 검색어 표에 SUGGEST_COLUMN_INTENT_DATA 행을 포함한 후 각 열의 고유 데이터를 행에 채우는 방법으로 각 인텐트의 모든 필수 데이터 정보를 제공합니다. 이 열의 데이터는 이 열에서 정의한 그대로 인텐트에 추가됩니다. 그런 다음 getData() 또는 getDataString()을 사용해 이 데이터를 검색할 수 있습니다.

    도움말: 표의 행 ID는 항상 고유하므로 일반적으로 이 ID를 인텐트 데이터로 사용하는 것이 가장 간편합니다. 가장 쉬운 방법은 SUGGEST_COLUMN_INTENT_DATA 열 이름을 행 ID 열의 별칭으로 사용하는 것입니다. 검색 가능한 사전 샘플 앱을 참고하여 SQLiteQueryBuilder를 통해 열 이름에서 별칭으로 projection map을 만드는 예를 확인하세요.

  2. 데이터 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)
        }
    }
    

자바

    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이고 데이터는 추천된 항목을 가리키는 전체 URI(android:searchSuggestIntentData 문자열과 SUGGEST_COLUMN_INTENT_DATA_ID 열의 합성)를 포함합니다. URI는 콘텐츠 제공자에서 URI에 지정된 항목을 쿼리하는 로컬 showResult() 메서드에 전달됩니다.

참고: android:searchSuggestIntentAction 속성이나 SUGGEST_COLUMN_INTENT_ACTION 열을 사용해 정의한 인텐트 작업용 인텐트 필터를 Android manifest 파일에 추가할 필요가 없습니다. 이름을 기준으로 검색 활동이 열려 추천 검색어의 인텐트가 제공되므로 활동에서 허용 작업을 선언할 필요가 없습니다.

쿼리 텍스트 다시 쓰기

사용자가 트랙볼이나 D패드와 같은 방향 컨트롤을 사용하여 추천 검색어 목록을 탐색하는 경우 기본적으로 쿼리 텍스트가 업데이트되지 않습니다. 그러나 현재 포커스가 맞춰진 추천 검색어와 일치하는 쿼리를 사용하여 사용자의 쿼리 텍스트를 텍스트 상자에 표시된 대로 일시적으로 다시 쓸 수 있습니다. 이렇게 하면 사용자는 추천된 쿼리(적합한 경우)를 확인한 다음 검색창을 선택하고 쿼리를 수정한 후에 이 수정 항목을 검색어로 보낼 수 있습니다.

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

  1. 'queryRewriteFromText' 값을 사용하여 검색 가능한 구성에 android:searchMode 속성을 추가합니다. 이 경우 추천 검색어의 SUGGEST_COLUMN_TEXT_1 열에 있는 콘텐츠가 쿼리 텍스트를 다시 쓰는 데 사용됩니다.
  2. 'queryRewriteFromData' 값을 사용하여 검색 가능한 구성에 android:searchMode 속성을 추가합니다. 이 경우 추천 검색어의 SUGGEST_COLUMN_INTENT_DATA 열에 있는 콘텐츠가 쿼리 텍스트를 다시 쓰는 데 사용됩니다. 이 방법은 URI 형식이나 사용자가 볼 수 있는 다른 데이터 형식(예: HTTP URL)에만 사용해야 합니다. 이러한 방식으로 쿼리를 다시 쓰는 데 내부 URI 스키마를 사용해서는 안 됩니다.
  3. 추천 검색어 표의 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>
    

이 예에서 제공자는 콘텐츠에 관한 읽기 및 쓰기 액세스를 제한합니다. "android.permission.GLOBAL_SEARCH" 권한이 존재하는 경우 <path-permission> 요소는 "/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를 포함합니다. 이 열을 사용하여 다음 중 한 가지 방법으로 각 추천 검색어의 바로가기 동작을 구성할 수 있습니다.

  1. 빠른 검색창에서 콘텐츠 제공자에게 새 버전의 추천 검색어 바로가기를 다시 쿼리하게 만듭니다.

    SUGGEST_COLUMN_SHORTCUT_ID 열에 값을 입력하면 바로가기가 표시될 때마다 추천 검색어가 다시 쿼리되어 새 버전의 바로가기를 얻게 됩니다. 바로가기는 새로고침 쿼리가 반환될 때까지 가장 최근에 사용 가능한 데이터로 빠르게 표시되었다가 새로고침 쿼리가 반환되면 추천 검색어가 새 정보로 새로고침됩니다. 새로고침 쿼리는 SUGGEST_URI_PATH_SHORTCUT의 URI 경로(SUGGEST_URI_PATH_QUERY 대신)를 사용해 콘텐츠 제공자에 전송됩니다.

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

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

  2. 추천 검색어가 바로가기에 복사되는 것을 방지합니다.

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

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

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

추천 검색어가 변경되지 않는다면 SUGGEST_COLUMN_SHORTCUT_ID 열이 전혀 필요하지 않습니다.

참고: 빠른 검색창은 궁극적으로 추천 검색어 값을 애플리케이션의 강력한 요청으로 간주하여 추천 검색어의 바로가기를 만들지 여부를 결정합니다. 추천 검색어 바로가기에 사용되도록 요청한 동작이 실제로 적용된다는 보장은 없습니다.

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

애플리케이션의 추천 검색어를 빠른 검색창에서 사용할 수 있게 되면 빠른 검색창 순위에 따라 특정 검색어에 관해 어떻게 추천 검색어가 사용자에게 표시되는지 결정됩니다. 특정 쿼리의 결과를 얻은 다른 앱의 수 및 사용자가 다른 앱보다는 내 앱에서 제공된 결과를 선택한 빈도에 따라 달라질 수 있습니다. 추천 검색어의 순위 또는 특정 쿼리에 관해 앱의 추천 검색어가 표시되는지 여부는 보장되지 않습니다. 일반적으로 양질의 결과를 제공하면 앱의 추천 검색어가 눈에 띄는 위치에 게재되고 품질이 낮은 추천 검색어를 제공하는 앱은 표시되지 않거나 앱의 순위가 낮을 가능성이 높아진다고 예상할 수 있습니다.

맞춤 추천 검색어에 관한 전체 데모는 검색 가능한 사전 샘플 앱을 참고하세요.