맞춤 제안 추가

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

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

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

기본 사항

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

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

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

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

Android 시스템은 검색 대화상자를 표시하는 것처럼 추천 검색어도 표시합니다. 시스템에서 추천 검색어를 가져올 수 있는 콘텐츠 제공자만 있으면 됩니다. 콘텐츠 제공자 만들기에 익숙하지 않은 경우 콘텐츠 제공자 개발자 가이드를 읽어본 후에 계속하세요.

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

시스템이 검색어 텍스트(지금까지 입력된 모든 텍스트)를 가져와서 추천 검색어를 관리하는 콘텐츠 제공자에 쿼리를 실행합니다.
콘텐츠 제공자가 검색어 텍스트와 관련된 모든 추천 검색어를 가리키는 Cursor를 반환합니다.
시스템에서 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에서 시스템이 기대하는 열을 정의하는 방법

Kotlin

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

자바

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

그러면 Uri의 마지막 세그먼트(사용자가 입력한 쿼리 텍스트)가 반환됩니다.

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

URI를 사용하는 대신 query() 메서드가 조회를 실행하는 데 필요한 모든 항목을 검색하고 selection 및 selectionArgs 매개변수에 적절한 값을 적용하는 것이 더 적합할 수도 있습니다. 이 경우 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 매개변수를 무시해도 됩니다. 이런 방식을 사용하면 콘텐츠 제공자가 처리할 필요가 없도록 대신 하위 수준에서 실제 선택 절을 정의할 수 있습니다.

인텐트 처리하기

맞춤 인텐트를 사용한 맞춤 추천 검색어를 제공했으며 이제 사용자가 추천 검색어를 선택할 때 이 인텐트를 처리할 검색 활동이 필요합니다. 검색 활동이 이미 하고 있는 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패드와 같은 방향 컨트롤을 사용하여 추천 검색어 목록을 탐색하는 경우 기본적으로 쿼리 텍스트가 업데이트되지 않습니다. 그러나 현재 포커스가 맞춰진 추천 검색어와 일치하는 쿼리를 사용하여 사용자의 쿼리 텍스트를 텍스트 상자에 표시된 대로 일시적으로 다시 쓸 수 있습니다. 이렇게 하면 사용자는 추천된 쿼리(적합한 경우)를 확인한 다음 검색창을 선택하고 쿼리를 수정한 후에 이 수정 항목을 검색어로 보낼 수 있습니다.

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

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

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

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

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

추천 검색어가 새로고침에 오래 걸릴 수 있는(예: 네트워크 기반 새로고침) 데이터를 참조하는 경우에는 새로고침이 완료될 때까지 오른쪽 아이콘에 진행률 스피너를 표시하기 위해 'true' 값을 사용해 추천 검색어 표에 SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING 열을 추가할 수도 있습니다. 'true' 이외의 값을 사용하면 진행률 스피너가 표시되지 않습니다.
추천 검색어가 바로가기에 복사되는 것을 방지합니다.
SUGGEST_COLUMN_SHORTCUT_ID 열에 SUGGEST_NEVER_MAKE_SHORTCUT 값을 제공합니다. 이 경우 추천 검색어가 바로가기에 복사되지 않습니다. 이전에 복사한 추천 검색어를 절대로 표시하지 않으려는 경우에만 이 방법이 필요합니다. 이 열에 일반적인 값을 제공하면 새로고침 쿼리가 반환될 때까지만 추천 검색어 바로가기가 표시됩니다.
기본 바로가기 동작이 적용되도록 합니다.
변경되지 않으며 바로가기로 저장할 수 있는 각 추천 검색어에 관해 SUGGEST_COLUMN_SHORTCUT_ID를 비워 둡니다.

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

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

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

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

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

맞춤 제안 추가

기본 사항

검색 가능한 구성 수정하기

콘텐츠 제공자 만들기

추천 쿼리 처리하기

URI에서 쿼리 가져오기

Kotlin

자바

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

추천 검색어 표 작성하기

추천 검색어용 인텐트 선언하기

인텐트 작업 선언하기

인텐트 데이터 선언하기

데이터 추가하기

인텐트 처리하기

Kotlin

자바

쿼리 텍스트 다시 쓰기

빠른 검색창에 추천 검색어 표시하기

기기에서 추천 검색어 사용 설정하기

빠른 검색창 추천 검색어 바로가기 관리하기

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