Watch voice assistants enable quick and efficient on-the-go scenarios. Voice interactions on wearables are dynamic, meaning that the user may speak to their wrist without necessarily looking at the device while waiting for a response.

With Assistant App Actions, Android developers can extend[Wear OS apps](https://developer.android.com/wear)to Google Assistant, fast forwarding users into their apps with voice commands like*"Hey Google, start my run on ExampleApp."*

#### Limitations

Assistant on Wear supports media and workout tracking activity interactions. For guidance on integrating media apps with Assistant, see[Google Assistant and media apps](https://developer.android.com/media/implement/assistant). The following Health and Fitness BIIs are supported for Wear OS apps:

- [`START_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/start-exercise)
- [`STOP_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/stop-exercise)
- [`PAUSE_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/pause-exercise)
- [`RESUME_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/resume-exercise)

## How it works

App Actions extend app functionality to Assistant, enabling users to access app features quickly, using their voice. When a user indicates to Assistant that they want to use your app, Assistant looks for App Actions registered to your app in the app's`shortcuts.xml`resource.

App Actions are described in`shortcuts.xml`with Android[capability](https://developer.android.com/develop/ui/views/launch/shortcuts/adding-capabilities#define_capabilities_in_shortcutsxml)elements. Capability elements pair[built-in intents](https://developer.android.com/guide/app-actions/intents)(BII), which are semantic descriptions of an app capability, with fulfillment instructions, such as a deep link template. When you upload your app using the Google Play console, Google registers the capabilities declared in`shortcuts.xml`, making them available for users to trigger from Assistant.

![App Actions flow](https://developer.android.com/static/develop/devices/assistant/images/app-actions-wear-flow.png)

The preceding diagram demonstrates a user pausing their exercise in a standalone app. The following steps occur:

1. The user makes a voice request to Assistant for the specific wearable app.
2. Assistant matches the request to a pre-trained model (BII), and extracts any parameters found in the query that are supported by the BII.
3. In the example, Assistant matches the query to the[`PAUSE_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/pause-exercise)BII, and extracts the exercise name parameter, "hike."
4. The app is triggered via its`shortcuts.xml`capability fulfillment definition for this BII.
5. The app processes the fulfillment, pausing the exercise.

#### Connectivity

App Actions development varies depending on the functionality of your app within the Android-powered device ecosystem.

- **Tethered**: When a wearable app is dependent on the mobile app for full functionality, user queries made to Assistant through the watch are fulfilled on the mobile device. App Actions fulfillment logic must be built into the mobile app for this scenario to function properly.

- **Untethered**: When a wearable app is independent from a mobile app for functionality, Assistant fulfills user queries locally on the watch. App Actions capabilities must be built into the wearable app for these requests to fulfill properly.

| **Note:** This only applies to App Actions functionality on wearables.[General queries to the Assistant](https://assistant.google.com/platforms/wearables/)such as getting things done, home control, and helpful info for the day are handled automatically through the Google Assistant app.

## Add voice capabilities to Wear

Integrate App Actions with your Wear OS app by following these steps:

1. Match the in-app functionality you want to voice enable to a[corresponding BII](https://developer.android.com/guide/app-actions/get-started#identify_app_functionality).
2. Declare support for Android shortcuts in your main activity`AndroidManifest.xml`resource.

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

3. Add an[`<intent-filter>`](https://developer.android.com/guide/topics/manifest/intent-filter-element)element to AndroidManifest.xml. This enables Assistant to use deep links to connect to your app's content.

4. [Create shortcuts.xml](https://developer.android.com/guide/app-actions/action-schema#overview)to provide fulfillment details for your BIIs. You use`capability`shortcut elements to declare to Assistant the BIIs your app supports. For more information, see[Add capabilities](https://developer.android.com/develop/ui/views/launch/shortcuts/adding-capabilities).

5. In`shortcuts.xml`, implement a[capability](https://developer.android.com/develop/ui/views/launch/shortcuts/adding-capabilities#define_capabilities_in_shortcutsxml)for your chosen BII. The following sample demonstrates a capability for the[`START_EXERCISE`](https://developer.android.com/reference/app-actions/built-in-intents/health-and-fitness/start-exercise)BII:

       <?xml version="1.0" encoding="utf-8"?>
       <!-- This is a sample 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="YOUR_UNIQUE_APPLICATION_ID"
             android:targetClass="YOUR_TARGET_CLASS">
             <!-- Eg. name = "Running" -->
             <parameter
               android:name="exercise.name"
               android:key="name"/>
             <!-- Eg. duration = "PT1H" -->
             <parameter
               android:name="exercise.duration"
               android:key="duration"/>
           </intent>
         </capability>
       </shortcuts>

6. If applicable, expand support for user speech variations using an[inline inventory](https://developer.android.com/guide/app-actions/inline-inventory), which represents features and content in your app.

       <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>

       <shortcut android:shortcutId="CARDIO_RUN">
         <capability-binding android:key="actions.intent.START_EXERCISE">
           <parameter-binding
             android:key="exercise.name"
             android:value="@array/run_names" />
           </capability-bindig>
       </shortcut>

7. Update your app's logic to handle the incoming App Actions fulfillment.

       //FitMainActivity.kt

       private fun handleIntent(data: Uri?) {
           var actionHandled = true
           val startExercise = intent?.extras?.getString(START_EXERCISE)

           if (startExercise != null){
               val type = FitActivity.Type.find(startExercise)
               val arguments = Bundle().apply {
                   putSerializable(FitTrackingFragment.PARAM_TYPE, type)
               }
               updateView(FitTrackingFragment::class.java, arguments)
           }
           else{
               showDefaultView()
               actionHandled = false
           }
           notifyActionSuccess(actionHandled)
       }

## Preview, test, and publish your app

App Actions provide tools to review and test your app. For more detailed information, see[Google Assistant plugin for Android Studio](https://developer.android.com/guide/app-actions/test-tool). Once you have tested your app and created a test release, you can request an[App Actions review](https://developer.android.com/guide/app-actions/get-started#request-review)and deploy. Review the following best practices for guidance on handling common errors.
| **Note:** The App Actions review is separate from the[Google Play review](https://play.google.com/console/about/guides/releasewithconfidence/#review-guidance-for-your-first-app-launch)and does not affect your status in Google Play. While your app may pass the Google Play review and be published, App Actions will not function for your app's users until the App Actions review is completed.

**Best practices**

Create a positive user experience when integrating your app with Assistant by following these recommended best practices.

Show a corresponding or relevant confirmation screen, along with haptics and audio feedback, to respond to a user request - either when successfully fulfilling a request, or to alert to an error.

|                           Basic quality                            |                                                          Better quality                                                          |                                                                Best quality                                                                 |
|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| - Create an intent to start`ConfirmationActivity`from an activity. | - Create an intent to start`ConfirmationActivity`from an activity. - Play a chime AND haptic feedback to indicate current state. | - Create an intent to start`ConfirmationActivity`from an activity. - Text-To-Speech (TTS) and haptic feedback to indicate error or success. |

| **Note:** Custom TTS prompts are not available through App Actions.

**Common errors and resolutions**

For the following error cases, use the following recommended app[`ConfirmationActivity`](https://developer.android.com/reference/androidx/wear/activity/ConfirmationActivity)messaging.

|         Error case         |                                   Example user interaction                                   |                                                                                                   App response                                                                                                    |
|----------------------------|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Activity already ongoing   | "Start my*ExerciseName* " "Resume my*ExerciseName*"                                          | Display error: Already ongoing activity."                                                                                                                                                                         |
| No Activity started        | "Pause/Stop my*ExerciseName*"                                                                | Display error: "No activity started."                                                                                                                                                                             |
| Mismatch of Activity types | "Pause/Stop my*ExerciseName*," which is a different exercise type from the ongoing activity. | Display error: "Activity type mismatch."                                                                                                                                                                          |
| Login error                | "Start my*ExerciseName*," when the user is not logged into the app.                          | Play haptic to alert user and redirect to login screen.                                                                                                                                                           |
| Permissions error          | The user does not have permission to start their requested activity.                         | Play haptic to alert user and redirect to permission request screen.                                                                                                                                              |
| Sensor issue               | The user has location services turned off in their device settings.                          | Play haptic to alert users and show sensor error screen. Optional next steps: - Start activity without sensor tracking and notify user. - Request user acknowledgement to start activity without sensor tracking. |

*** ** * ** ***