바로가기에 기능 추가
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
shortcuts.xml의 기능을 사용하면 사용자가 앱을 실행하고 특정 작업을 직접 수행하기 위해 실행할 수 있는 작업 유형을 선언할 수 있습니다.
예를 들어 Google 어시스턴트 앱 작업은 기능을 사용하여 개발자가 앱 내 기능을 내장 인텐트 (BII)로 확장하도록 지원함으로써 사용자가 음성 명령으로 이러한 기능을 활성화하고 제어할 수 있도록 합니다. 기능은 작업의 이름과, 앱에서 사용자 인텐트를 결정하는 대상을 타겟팅하는 intent로 구성됩니다.
shortcuts.xml에서 기능 정의하기
Android 앱 개발 프로젝트의 shortcuts.xml 리소스 파일에서 capability 요소를 정의할 수 있습니다. capability 요소를 정의하려면 다음을 실행합니다.
- 정적 바로가기 만들기의 안내에 따라
shortcuts.xml 리소스를 만듭니다.
기능에 다음과 같은 필수 정보를 포함합니다.
기능 이름: 앱에서 지원할 작업입니다. 기능 정의가 필요한 기능은 구성요소 문서를 참고하세요. 앱 작업 음성 지원 명령어는 BII 참조에서 확인할 수 있는 기능 이름으로 BII Action ID를 사용합니다. 예를 들어 GET_THING BII는 Action ID를 actions.intent.GET_THING으로 나열합니다.
앱 대상: 앱에서 사용자 요청을 처리하기 위해 작업이 실행되는 대상입니다. capability 내에 중첩된 intent 요소를 사용하여 앱 대상을 정의합니다.
매개변수 매핑: 각 intent에는 인텐트의 extra 데이터로 전달해야 할 매개변수가 포함될 수 있습니다. 예를 들어 각 앱 작업 BII에는 사용자가 BII를 트리거하는 쿼리에 제공하는 정보를 나타내는 필드가 포함되어 있습니다.
다음 예는 사용자가 음성 명령으로 어시스턴트를 사용하여 피트니스 앱에서 운동을 시작하도록 지원하는 BII인 actions.intent.START_EXERCISE에 관한 shortcuts.xml의 기능 정의를 보여줍니다.
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.sampleApp"
android:targetClass="com.example.sampleApp.ExerciseActivity">
<parameter
android:name="exercise.name"
android:key="exerciseType"/>
</intent>
</capability>
</shortcuts>
앞에 나온 예에서 <capability> android:name 속성은 START_EXERCISE BII를 가리킵니다. 사용자가 어시스턴트에게 "Hey Google, ExampleApp에서 달리기 시작해 줘"라고 요청하여 이 BII를 호출하면 어시스턴트는 중첩된 intent 요소에 제공된 정보를 사용하여 사용자 요청을 처리합니다. 이 샘플의 intent는 다음 세부정보를 정의합니다.
android:targetPackage는 이 인텐트의 타겟 애플리케이션 패키지를 설정합니다.android:targetClass 필드는 대상 활동 com.example.sampleApp.ExerciseActivity를 지정합니다.- 인텐트
parameter는 BII 매개변수 exercise.name에 관한 지원을 선언하고, intent의 추가 데이터로 사용자에게서 수집한 매개변수 값을 전달할 방법을 선언합니다.
바로가기에 기능 연결하기
기능을 정의한 후에는 정적 또는 동적 바로가기를 연결하여 기능을 확장할 수 있습니다. 바로가기가 capability에 연결되는 방식은 구현하려는 기능과 사용자 요청에 포함된 단어에 따라 달라집니다. 예를 들어 사용자가 어시스턴트에게 "Hey Google, ExampleApp에서 달리기 시작해 줘"라고 요청하여 피트니스 추적 앱에서 달리기를 시작하는 경우를 생각해 보겠습니다. 어시스턴트는 바로가기를 사용하여 exercise.name 매개변수에 유효한 'run' 운동 항목을 정의하는 capability의 인스턴스를 실행할 수 있습니다.
앱 작업에 바로가기를 연결하는 방법에 관한 자세한 내용은 앱 작업 개요를 참고하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-08-27(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-27(UTC)"],[],[],null,["Capabilities in `shortcuts.xml` let you declare the types of actions users can\ntake to launch your app and directly perform a specific task.\n\nFor example, Google Assistant App Actions use capabilities to let developers\nextend in-app features to [built-in intents](//developers.google.com/assistant/app/intents) (BIIs), letting users activate\nand control those features using spoken commands. A capability consists of the\nname of the action and an `intent` targeting the destination in your app that\nresolves the user intent.\n\nDefine capabilities in shortcuts.xml\n\nYou define `capability` elements in a `shortcuts.xml` resource file in your\nAndroid app development project. To define a `capability` element, do the\nfollowing:\n\n1. Create a `shortcuts.xml` resource by following the instructions in [Create\n static shortcuts](//develop/ui/views/launch/shortcuts/creating-shortcuts#static).\n2. Include the following required information in your capability:\n\n - **Capability name:** the action you want your app to support. Refer to\n the component documentation for the feature that requires capability\n definitions. App Actions voice-enabled commands use the BII `Action ID`\n for capability names, which you can find in [BII reference](//developers.google.com/assistant/app/reference/built-in-intents). For example,\n the [`GET_THING`](//developers.google.com/assistant/app/reference/built-in-intents/common/get-thing) BII lists its `Action ID` as `actions.intent.GET_THING`.\n\n - **App destination:** the destination in your app the action launches to\n fulfill the user request. Define app destinations using `intent` elements\n nested within the `capability`.\n\n - **Parameter mappings:** each `intent` might contain parameters to be\n passed as `extra` data of the intent. For example, each App Actions BII\n includes fields representing information users often provide in queries that\n trigger the BII.\n\nThe following example demonstrates a capability definition in `shortcuts.xml`\nfor [`actions.intent.START_EXERCISE`](//developers.google.com/assistant/app/reference/built-in-intents/health-and-fitness/start-exercise), a BII that lets users use spoken\ncommands with Assistant to begin a workout in a fitness app: \n\n \u003cshortcuts xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n \u003ccapability android:name=\"actions.intent.START_EXERCISE\"\u003e\n \u003cintent\n android:action=\"android.intent.action.VIEW\"\n android:targetPackage=\"com.example.sampleApp\"\n android:targetClass=\"com.example.sampleApp.ExerciseActivity\"\u003e\n \u003cparameter\n android:name=\"exercise.name\"\n android:key=\"exerciseType\"/\u003e\n \u003c/intent\u003e\n \u003c/capability\u003e\n \u003c/shortcuts\u003e\n\nIn the preceding example, the `\u003ccapability\u003e` `android:name` attribute refers to\nthe `START_EXERCISE` BII. If a user invokes this BII by asking Assistant, *\"Hey\nGoogle, start a run in ExampleApp,\"* Assistant fulfills the user request using\ninformation provided in the nested `intent` element. The `intent` in this sample\ndefines the following details:\n\n- The `android:targetPackage` sets the target application package for this intent.\n- The `android:targetClass` field specifies the destination activity: `com.example.sampleApp.ExerciseActivity`.\n- The intent `parameter` declares support for a BII parameter [`exercise.name`](//developers.google.com/assistant/app/reference/built-in-intents/health-and-fitness/start-exercise#recommended-fields) and how to pass the parameter value---collected from the user---as extra data in the `intent`.\n\nAssociate shortcuts with a capability\n\nOnce you define a capability, you can extend its functionality by associating\nstatic or dynamic shortcuts with it. How shortcuts are linked to a `capability`\ndepends on the feature being implemented and the actual words included in a\nuser's request. For example, when a user begins a run in your fitness tracking\napp by asking Assistant, *\"Hey Google, start a run in ExampleApp.\"* Assistant\ncan use a shortcut to launch an instance of a `capability` that defines a valid\nexercise entity of \"run\" for the `exercise.name` parameter.\n\nFor more information about associating shortcuts to App Actions, see [App\nActions overview](//developers.google.com/assistant/app)."]]
