shortcuts.xml 만들기

구현할 인앱 기능과 그에 상응하는 내장 인텐트(BII)를 식별한 후 shortcuts.xml 리소스 파일에서 capability 요소를 정의하여 기능에 지원되는 BII를 선언합니다. BII를 capability로 선언하면 앱에 관련 시맨틱 인텐트 지원이 등록되고 Google 어시스턴트를 사용한 인텐트의 음성 쿼리 처리가 가능합니다.

어시스턴트는 자연어 처리를 사용하여 사용자 쿼리에서 매개변수를 추출합니다. 내장 인텐트 참조에는 연결된 사용자 쿼리에서 각 BII가 추출할 수 있는 필드가 나열되어 있습니다. 예를 들어 사용자가 "Hey Google, ExampleApp에 지난 금요일 점심에 뭐 먹었는지 물어봐 줘"라고 말하여 앱에서 [actions.intent.GET_FOOD_OBSERVATION][] 기능을 호출하면 어시스턴트는 사용자 요청에서 다음 BII 매개변수를 추출합니다.

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

어시스턴트는 capability에 정의된 처리 intent에 BII 매개변수를 전달합니다. 사용자의 다양한 BII 호출 방법을 수용하기 위해 기능에 하나 이상의 intent 요소를 정의할 수 있습니다. 예를 들어 위의 예에서는 두 BII 매개변수가 모두 필요한 처리 intent를 정의할 수 있습니다. 그런 다음 단일 BII 매개변수 foodObservation.forMeal을 요구하는 두 번째 인텐트를 정의하여 특정 날짜의 모든 식사를 보고하도록 할 수 있습니다(예: "Hey Google, ExampleApp에 점심에 뭐 먹었는지 물어봐 줘.").

개요

앱 프로젝트의 res/xml 디렉터리에 있는 shortcuts.xml 파일을 사용하여 앱 작업을 구성한 후 앱 매니페스트에서 shortcuts.xml에 대한 참조를 만들 수 있습니다. 다음 단계에 따라 앱 매니페스트에 shortcuts.xml에 대한 참조를 추가합니다.

1. 앱의 매니페스트 파일(AndroidManifest.xml)에서 인텐트 필터가 android.intent.action.MAIN 작업과 android.intent.category.LAUNCHER 카테고리로 설정된 활동을 찾습니다.

2. 다음과 같이 MAIN 및 LAUNCHER의 인텐트 필터가 모두 있는 Activity에서 <meta-data> 태그를 사용하여 AndroidManifest.xml에 shortcuts.xml에 대한 참조를 추가합니다.

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

위의 예에서는 APK에 xml/shortcuts.xml 파일의 XML 리소스를 선언합니다. 바로가기 구성에 관한 자세한 내용은 Android 개발자 문서의 정적 바로가기 만들기를 참고하세요.

shortcuts.xml에서 앱 작업 기능을 정의할 때 컴파일 오류를 방지하려면 Android 프로젝트에 Jetpack 라이브러리 androidx.core:core:1.6.0 이상이 필요합니다. 자세한 내용은 Android Jetpack 시작하기를 참고하세요.

정적 바로가기

capability를 정의할 때 shortcuts.xml에 정적 shortcut 요소를 선언하여 기능의 기능성을 확장할 수 있습니다. 정적 바로가기는 Google Play Console에 버전을 업로드할 때 어시스턴트를 통해 수집됩니다. 정적 바로가기는 새 버전을 만들어야 생성 및 업데이트가 가능하므로 앱의 일반적인 활동과 콘텐츠를 강조표시하는 데 가장 유용합니다.

정적 바로가기로 다음 앱 작업 기능을 사용 설정할 수 있습니다.

• 기능 바로가기. 사전 정의된 intent 매개변수 값이 포함된 capability의 인스턴스를 실행하는 바로가기를 만듭니다. 예를 들어, 피트니스 앱에서 START_EXERCISE BII 기능을 호출하는 '달리기 시작'이라는 앱 바로가기를 선언할 수 있습니다.

  이러한 바로가기에는 intent, shortLabel, longLabel 속성이 포함됩니다. 이를 통해 어시스턴트와 같은 능동적 표시 영역에서, 또는 Android 런처에서 앱 아이콘을 길게 누를 때 바로가기가 칩 형태로 추천 및 처리될 수 있습니다. <capability-binding> 태그로 작업 바로가기를 capability에 연결하여 아래에 설명된 항목 바로가기로 사용할 수도 있습니다.

• 항목 바로가기. 항목 바로가기는 capability의 음성 쿼리 처리에 지원되는 매개변수 값 목록을 제공합니다. 예를 들어 특정 항목 바로가기에는 START_EXERCISE 기능의 exercise.name BII 매개변수에 바인딩된 운동 유형('하이킹', '달리기' 등) 목록이 있을 수 있습니다. 사용자 발화가 항목과 일치하면 shortcutId ID가 원시 사용자 쿼리 값이 아닌 인텐트에 전달됩니다.

  Entity 바로가기는 intent, shortLabel, longLabel 속성을 정의하지 않으며, 따라서 보통 능동적 표시 영역에는 권장되지 않습니다. 자세한 내용은 앱 작업을 위한 인라인 인벤토리를 참고하세요.

기능 스키마

다음 표에서는 shortcuts.xml의 capability 요소에 관한 앱 작업 스키마를 설명합니다. 태그를 포함할 때 '선택사항'으로 표시하지 않는 한 태그의 모든 속성은 필수 속성입니다.

기능 스키마 설명

이 섹션에서는 capability 스키마 요소를 설명합니다.

<capability>

앱에 지원되는 앱 작업 인텐트를 정의하는 capability. shortcuts.xml 파일의 각 <capability> 요소는 작업 처리를 취급할 하나 이상의 <intent>를 제공해야 합니다.

속성:

• android:name: 내장 인텐트 작업 ID (예: [actions.intent.GET_FOOD_OBSERVATION][]). 지원되는 내장 인텐트 목록은 내장 인텐트 참조를 확인하세요.
• app:queryPatterns: 이 인텐트와 관련해 사용자로부터 예상되는 쿼리의 문자열 배열 리소스. BII에는 사용자가 원하는 작업 또는 정보를 표현하는 일반 방식의 모델이 이미 포함되어 있기 때문에, 이 속성은 맞춤 인텐트에만 해당됩니다.

<intent>

인앱 기능을 사용한 사용자 쿼리 처리 방식을 정의하는 Android intent 요소. 개발자는 capability에 여러 개의 <intent> 태그를 제공할 수 있습니다. 어시스턴트는 모든 필수 매개변수가 제공되는 capability의 첫 번째 <intent>를 사용하여 사용자 쿼리를 처리하려고 시도합니다.

속성:

• android:action: 인텐트 Action 유형. 기본값은 ACTION_VIEW입니다.
• android:targetClass: 타겟 활동 클래스. 예: "com.example.exercise.ExerciseActivity"
• android:targetPackage: 타겟 활동 클래스가 포함된 패키지. 예: "com.example.exercise
• android:data: intent에 태그가 선언된 경우 이 필드는 <url-template>으로 덮어쓰기됩니다.

<url-template>

기기에서 열 딥 링크 URI를 구성하기 위한 템플릿. 템플릿의 모든 필수 매개변수가 사용 가능한 경우 내장 인텐트 매개변수로 템플릿을 확장할 수 있습니다. HTTP URL 템플릿의 예는 URL 템플릿에 관한 위키백과 문서를 참고하세요. 템플릿 형식은 RFC6570 URI 템플릿 사양을 따릅니다.

다음은 URL 템플릿 값의 몇 가지 예입니다.

URL 템플릿 구성 방법에 관한 자세한 내용은 처리 태그에 URL 템플릿 선언을 참고하세요.

<extra>

intent의 추가 데이터를 정의합니다. 앱 작업의 경우 이 필드는 capability의 [포그라운드 앱 호출][] 을 사용 설정하는 데만 사용됩니다.

<parameter>

BII 매개변수를 인텐트 매개변수 값에 매핑합니다. 자세한 내용은 매개변수 데이터 및 일치를 참고하세요.

속성:

• android:name: 이 intent 매개변수와 연결할 BII 매개변수의 이름. 이름은 BII 매개변수의 리프 레벨 필드(예: foodObservation.aboutFood.name)여야 합니다.
• android:key: BII 매개변수 값의 개발자 정의 키. 예를 들어 message.recipient.name BII 매개변수의 contact_name을 정의할 수 있습니다.
• android:mimeType: 매개변수의 mimeType(예: text/*). 이 필드는 맞춤 인텐트의 매개변수에만 필요합니다.
• android:required: 처리에 인텐트를 사용할 때 사용자 쿼리에 매개변수를 포함해야 하는지 선언합니다. 관련 매개변수를 사용할 수 없는 경우 어시스턴트는 capability에 정의된 그다음 intent를 사용하여 사용자 쿼리를 처리하려고 시도합니다.

<shortcut-fulfillment>

처리 시에는 지정된 매개변수와 관련해 인라인 인벤토리 바로가기에 정의된 intent를 사용하도록 명시합니다. 자세한 내용은 바로가기 인텐트를 사용한 처리를 참고하세요.

<parameter>(<shortcut-fulfillment>의 경우)

단일 BII 매개변수를 인라인 인벤토리 바로가기 처리에 매핑하는 선택적 속성입니다. 자세한 내용은 바로가기 인텐트를 사용한 처리를 참고하세요.

속성:

• android:name: 인라인 인벤토리 바로가기 처리와 연결할 BII 매개변수의 이름. 이름은 BII 매개변수의 리프 레벨 필드(예: menuItem.name)여야 합니다.

<slice>

어시스턴트가 capability와 일치하는 쿼리의 결과를 Android Slice로 삽입할 수 있게 됩니다. 자세한 내용은 Android Slice와 앱 작업 통합을 참고하세요.

바로가기 스키마

다음 표에서는 앱 작업 기능을 사용 설정하는 데 사용되는 shortcut 요소의 속성을 설명합니다. 태그를 포함할 때 '선택사항'으로 표시되지 않는 한 태그의 모든 속성은 필수 속성입니다.

바로가기 스키마 설명

이 섹션에서는 shortcut 스키마 요소를 설명합니다.

<shortcut>

앱 작업과 관련된 특정 속성과 함께 shortcuts.xml에 정의된 Android <shortcut>. shortcutShortLabel 및 shortcutLongLabel 필드의 문자열 값은 APK의 문자열 리소스를 통해 참조됩니다.

속성:

• android:shortcutId: 바로가기의 식별자.
• android:shortcutShortLabel: 간단한 단축어 문구를 나타내는 문자열 리소스. 예를 들어 "@string/callDavidShort"는 'David에게 전화' 값을 나타냅니다.
• android:shortcutLongLabel: 긴 단축어 문구를 나타내는 문자열 리소스. 예를 들어 "@string/callDavidLong"은 'David에게 음성 통화 걸기' 값을 나타냅니다.

<intent>

바로가기와 연결된 Android 인텐트. 이 intent는 사용자가 음성이나 터치를 사용하여 바로가기를 시작하면 실행됩니다.

shortcut 인텐트 속성은 capability intent 속성과 동일합니다.

<capability-binding>

shortcut을 앱 작업 capability에 연결합니다. 이 요소를 shortcut에 추가하면 Assistant를 이용한 음성 처리에 바로가기를 사용할 수 있습니다.

속성:

• android:key: shortcut이 바인딩된 capability의 android:name 속성. 예: actions.intent.START_EXERCISE.

<parameter-binding>

shortcut을 앱 작업 capability의 단일 매개변수에 연결하는 선택적 속성. shortcut에 parameter-binding이 정의되어 있으면 바로가기를 사용하여 BII 매개변수에 인라인 인벤토리 항목을 제공할 수 있습니다. 자세한 내용은 앱 작업을 위한 인라인 인벤토리를 참고하세요.

속성:

• android:key: 바로가기를 연결할 capability BII 매개변수의 이름. 예: exercise.name
• android:value: entity 값. 이는 단일 entity 또는 리소스 목록일 수 있습니다.

<extra>

바로가기의 extra 번들 데이터. sameAs는 앱 작업 shortcut 요소와 관련된 유일한 데이터입니다. sameAs URL은 항목을 명확하게 식별하는 참조 웹페이지를 가리킵니다. 인텐트 매개변수 유형이 schema.org/Enumeration의 하위유형인 경우에만 enum 값을 지정하는 데 사용됩니다. schema.org/Enumeration의 하위유형인 매개변수 필드에 필수 항목입니다(예: MealTypeBreakfast).

속성:

• android:key: 앱 작업에 지원되는 값은 sameAs입니다.
• android:value: sameAs URL 값

자세한 내용은 열거된 매개변수 값 일치를 참고하세요.

인텐트 처리 옵션

<capability> 내에 intent 요소를 정의하여, 기능과 일치하는 사용자 음성 명령에 대한 어시스턴트의 응답 방식이나 처리 방식을 선언할 수 있습니다. 앱 탐색이 구조화된 방식에 따라 intent는 앱에서 다양한 방식으로 처리 대상을 실행합니다.

다음과 같은 처리 옵션을 사용할 수 있습니다.

• 명시적 인텐트: intent에 targetClass 및 targetPackage 속성을 정의하여 특정 앱 구성요소를 실행합니다. 이는 권장되는 앱 작업 처리 방법입니다.

• 딥 링크: intent 요소 내에 <url-template> 태그를 정의하여 Android 딥 링크로 앱 대상을 실행합니다. 이 방법은 앱 탐색에 이미 딥 링크를 사용하고 있는 경우에 유용합니다.

• 인텐트 데이터: intent android:data 속성에 처리 URI를 제공할 수 있습니다. 태그가 intent 내에 정의된 경우 이 필드는 <url-template> 데이터로 덮어쓰기됩니다.

매개변수 데이터 및 일치

기본적으로 어시스턴트는 사용자 쿼리에서 추출된 BII 매개변수를 capability에 정의된 Android intent의 extra 데이터로 앱에 전송합니다.

또는 동적 매개변수의 자리표시자를 포함하는 <url-template> 태그를 capability에 선언할 수 있습니다. 이 템플릿은 앱 링크 URL, 맞춤 스키마 또는 인텐트 기반 URL을 사용하여 Android 활동 중 하나에 매핑됩니다.

인텐트 추가 항목 사용

다음 예에서는 capability 처리와 관련해 정의된 명시적 인텐트를 보여줍니다.

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

위 샘플에서는 "Hey Google, 달리기 시작해 줘"와 같은 사용자 쿼리가 있는 경우 앱은 구성요소 targetPackage, targetClass를 호출하는 intent를 수신합니다. 그러면 구성요소는 key = "exercise", value = "Running"가 있는 추가 항목을 수신합니다.

Android 딥 링크에 URL 템플릿 사용

앱에서 이미 동적 매개변수를 사용하여 앱 연결 URL을 처리할 수 있는 경우 intent에 <url-template>을 정의하여 처리에 사용할 Android 딥 링크를 생성할 수 있습니다. 다음 샘플은 <url-template>을 정의합니다.

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

위 샘플에서는 "Hey Google, 달리기 시작해 줘"와 같은 사용자 쿼리가 있는 경우 앱은 생성된 URL 'myapp://start?exercise=Running'을 수신합니다.

BII 매개변수를 URL의 위치에 매핑하려면 <parameter> 태그의 android:name 속성을 사용하면 됩니다. 이 속성은 URL 템플릿에서 사용자의 정보로 대체하려는 android:key 값에 해당합니다. <url-template>에 중괄호({})로 묶인 android:key 값이 있어야 합니다.

열거된 매개변수 값 일치

일부 BII 매개변수는 RECORD_FOOD_OBSERVATION BII의 지원되는 텍스트 값 같은 열거형 값을 처리 인텐트에 제공합니다. 이러한 매개변수의 경우 어시스턴트는 enum 스키마 URL(https://schema.googleapis.com/MealTypeBreakfast)과 일치하는 sameAs 값을 갖는 항목에 사용자 쿼리('아침 식사')를 일치시킵니다. 지원되는 entity의 enum 값을 연결하려면 shortcut에 sameAs 연결을 선언하면 됩니다. 다음 샘플에서는 인라인 항목 바로가기의 sameAs 연결을 보여줍니다.

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

위의 예에서 RECORD_FOOD_OBSERVATION 기능이 식사 유형 '아침 식사'와 일치하는 항목을 찾는 경우 다음 추가 항목이 처리 intent와 함께 전송됩니다.

• key = "for_meal"
• value = "meal_breakfast"

기능

shortcuts.xml에서 다음 앱 작업 기능을 사용할 수 있습니다.

앱 작업을 위한 인라인 인벤토리

일부 BII 매개변수에서는 바로가기를 사용하여, 항목 추출을 shortcuts.xml에 지정된 지원되는 항목 세트(인라인 인벤토리하고 함)로 유도할 수 있습니다. 자세한 내용은 인라인 인벤토리를 참고하세요.

맞춤 인텐트

사용 가능한 BII와 일치하지 않는 앱 기능을 음성으로 활성화하기 위해 shortcuts.xml에서 맞춤 인텐트를 선언할 수 있습니다. 맞춤 인텐트는 기능 면에서 BII 정의와 비슷하지만 shortcuts.xml에 두 가지 추가 속성이 필요합니다.

• app:queryPatterns: 맞춤 인텐트에 다양한 쿼리 패턴을 선언하는 배열 리소스.

• android:mimeType: 맞춤 인텐트의 매개변수 유형. 매개변수 유형이 알려진 경우 BII에는 이 필드가 필요하지 않습니다. 맞춤 인텐트 매개변수의 경우 지원되는 시맨틱 유형을 선언해야 합니다.

자세한 내용은 맞춤 인텐트를 참고하세요.