구현할 인앱 기능과 그에 상응하는 내장 인텐트(BII)를 식별한 후 shortcuts.xml
리소스 파일에서 capability
요소를 정의하여 기능에 지원되는 BII를 선언합니다. BII를 capability
로 선언하면 앱에 관련 시맨틱 인텐트 지원이 등록되고 Google 어시스턴트를 사용한 인텐트의 음성 쿼리 처리가 가능합니다.
어시스턴트는 자연어 처리를 사용하여 사용자 쿼리에서 매개변수를 추출합니다. 내장 인텐트 참조에는 연결된 사용자 쿼리에서 각 BII가 추출할 수 있는 필드가 나열되어 있습니다. 예를 들어 사용자가 "Hey Google, Ask 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
에 대한 참조를 추가합니다.
앱의 매니페스트 파일(
AndroidManifest.xml
)에서 인텐트 필터가android.intent.action.MAIN
작업과android.intent.category.LAUNCHER
카테고리로 설정된 활동을 찾습니다.다음과 같이
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
요소에 관한 앱 작업 스키마를 설명합니다. 태그를 포함할 때 '선택사항'으로 표시하지 않는 한 태그의 모든 속성은 필수 속성입니다.
Shortcuts.xml 태그 | 포함된 요소 | 속성 |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
포그라운드 앱 호출에만 해당됩니다. |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
인라인 인벤토리에만 해당됩니다. |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Android Slice에만 해당됩니다. |
기능 스키마 설명
이 섹션에서는 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 템플릿 값의 몇 가지 예입니다.
템플릿 | 값 | 확장 값 |
---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} |
"foo": "123" |
https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} |
"foo": "123" |
myapp://example/123 |
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
요소의 속성을 설명합니다. 태그를 포함할 때 '선택사항'으로 표시되지 않는 한 태그의 모든 속성은 필수 속성입니다.
Shortcuts.xml 태그 | 포함된 요소 | 속성 |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
Enum 매개변수 일치에만 해당됩니다. |
바로가기 스키마 설명
이 섹션에서는 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, ExampleApp에서 라떼 주문해 줘."와 같은 사용자 쿼리가 있는 경우 앱은 구성요소 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, ExampleApp에서 라떼 주문해 줘."와 같은 사용자 쿼리가 있는 경우 앱은 생성된 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에는 이 필드가 필요하지 않습니다. 맞춤 인텐트 매개변수의 경우 지원되는 시맨틱 유형을 선언해야 합니다.
자세한 내용은 맞춤 인텐트를 참고하세요.