UIKit Apprentice, Second Edition – Now Updated!

Learn iOS and Swift from scratch. Build four powerful apps—with support for iPad and Dark Mode. Publish apps to the App Store.

Home Android & Kotlin Tutorials

App Actions: Getting Started

App Actions allow Google Assistant to access your app and launch specific actions within the app. This tutorial teaches you how to implement App Actions for your app so users can interact with your app directly through Google Assistant.

5/5 1 Rating

Version

  • Kotlin 1.4, Android 5.0, Android Studio 4.1

What’s the first thing you do when you have a pizza craving? Do you say, “Hey, Google, order my favorite pizza”? This is just one of the ways Google Assistant has made our lives more efficient. Today, Google Assistant is available on a wide variety of Android devices, ranging from smartphones and tablets to watches — and even cars! As a developer, you can use Google Assistant for your own app using App Actions.

App Actions let you open specific features of your app using Google Assistant. Near the end of 2020, Google introduced 30 new intents to build your App Actions, bringing the total to over 60.

In this tutorial, you’ll learn how to add App Actions to an app named StockTracker. The app fetches the latest stock quotes from the internet with the help of a free and public API. Along the way, you’ll learn about:

  • What App Actions are
  • How App Actions work
  • Adding your own App Actions
  • Testing your App Actions
  • Deploying your App Actions
Note: This tutorial assumes you’re familiar with the basics of Android development in Kotlin. You should also have some familiarity with deep links. If you don’t, check out our Deep Links in Android: Getting Started tutorial. You’ll also need a physical device running API 21 or higher to test App Actions.

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of this tutorial. Open Android Studio and import the starter project.

Take a moment to familiarize yourself with the code. You’ll see the following classes:

  1. MainActivity.kt: Home screen of the app, which allows users to enter their favorite stock symbol. It also handles the deep links triggered by App Actions.
  2. Stock.kt: File containing the data classes used for parsing the API response.
  3. StockApiService.kt: File containing all the networking-related code, including the GET endpoint used to fetch stock quotes. It also exposes a retrofit object used in StockQuoteActivity.kt.
  4. StockQuoteActivity.kt: Second screen of the app, which displays the latest information on the selected stock. In this class, Coroutines fetch data from the network asynchronously.
Note: If you’re not familiar with Coroutines, check out our Kotlin Coroutines tutorial.

Before you build and run the app, you need to add your own API key. Get your API key from Alpha Vantage Support. Once you have the key, open StockQuoteActivity.kt and paste it inside the empty quotes to assign the value to the constant named API_KEY.

Now you’re all set. Run the app, and you’ll see the screen below:

Main Screen of Stock Tracker app

Enter the ticker symbol of your favorite stock (e.g., GOOG) and tap GET QUOTE. A new screen shows your selected stock’s latest quote.

Stock Tracker screen showing results for GOOG stock

Note: Make sure you’re connected to the internet to the view the stock quote.

So, now you’ve got an app that can check stock quotes when you type in a symbol, but wouldn’t it be cool if you could just ask it instead? That’s where App Actions come in! :]

Introducing App Actions

App Actions are shortcuts to your app. They can launch different features of your app with the help of Google Assistant. You can deep link into your app with a simple voice command like, “Hey, Google, tell me the stock quote of GOOGL in Stock Tracker”.

App Actions can also display any information from your app directly in the Google Assistant conversation dialog. You don’t need to open your app explicitly, you can just ask Google Assistant to fetch it for you without switching the current context.

Three gears artistically illustrating that there are parts working together inside the built-in intents.

Understanding the Internal Working of App Actions

App Actions work on the concept of intents. Intents are objects that can request actions from different components of an app. There are two types of intent used for invoking different App Actions:

  • Built-in intents (BIIs): As the name suggests, BIIs are a set of intents provided by Google to support common app functionalities. There are different categories of BIIs. Some examples of built-in intents are actions.intent.GET_NEWS_ARTICLE, actions.intent.CREATE_CALL and actions.intent.ORDER_MENU_ITEM.

    The complete list of built-in intents is available in the official index. You need to specify the built-in intent you want to use for your app in the actions.xml file.

  • Custom intents: Although more than 60 built-in intents are currently available, some features of your app may require a functionality that’s not yet available. To handle this situation, you can use custom intents.

    The main difference between a built-in intent and a custom intent is that for a custom intent you have to specify additional query patterns to include the things that the user might say. You need to specify the different query patterns inside a string array. For each custom intent you implement in your app, there can be a maximum of 100 query patterns.

When you add an intent for your App Action, Google Assistant matches the user query with your built-in (or custom) intent. It extracts the intent parameter, passes it to the defined fulfillment for that intent and then deep links the user into the app.

Note: The app should already handle the deep links that Google Assistant will invoke.

Now that you know how App Actions work, it’s time to upload the app.

Uploading a Draft App to Play Console

Before you start adding App Actions, you need to upload a draft version of your app to Play Console. This allows you to use the App Actions Test Tool, described later in this tutorial.

Note: This tutorial assumes you already have a Google account with access to Play Console.

First, open app/build.gradle and change applicationId to something unique. For example, you can set applicationId to be com.youruniquename.android.stocktracker. This will prevent issues when uploading your app.

Next, build your signed app in Android Studio and upload it to Play Console as an internal release.

Note: If you’re new to publishing an app, check out our App Distribution tutorial. You don’t need to roll out the full internal release. Just upload the signed APK and save it as a draft version once the APK has been uploaded successfully.

Adding Your First App Action

To start adding App Actions, you need to do three things:

  1. Identify the correct built-in intent to use.
  2. Create the actions.xml file.
  3. Make your App Actions visible to the app.

Identifying the Correct BII

Identify the main functionality of your app for which you want to define App Actions. For example, if it’s a food delivery app, then the main functionality will be ordering food (no surprises there!). Then, go to this list of built-in intents and identify the correct intent for your use case.

For this tutorial, StockTracker retrieves the latest stock quotes from the internet. The correct BII for this use case is actions.intent.GET_STOCK_QUOTE. It has one intent parameter named tickerSymbol that uniquely identifies each stock.

Creating actions.xml File

Create a new actions.xml file in app/src/main/res/xml.

Note: If you don’t already have an xml folder, create one by right-clicking the res directory and selecting New ▸ Android Resource Directory. Enter xml as the Directory name and select xml as the Resource type. Then, click OK.

Add the following code in the newly created actions.xml file below the xml tag:

<actions>
// 1:
  <action intentName="actions.intent.GET_STOCK_QUOTE">
// 2:
    <fulfillment urlTemplate="app://stocktracker/query{?symbol}">
// 3:
      <parameter-mapping
          intentParameter="tickerSymbol"
          required="true"
          urlParameter="symbol" />
    </fulfillment>
// 4:
    <!-- Fallback fulfillment when no parameter supplied -->
    <fulfillment urlTemplate="app://stocktracker/home" />
  </action>
</actions>

In the xml code above, you’re:

  1. Creating a new action with actions.intent.GET_STOCK_QUOTE: action is a required tag, which specifies the App Action you want to implement. Every App Action will have a unique action tag. intentName takes in the built-in intent for this action.
  2. Defining a new fulfillment for the corresponding action: fulfillment provides information on how the given intent satisfies the request. urlTemplate constructs deep links as defined in AndroidManifest.xml. For the fulfillment you added, app://stocktracker is the base deep link and /query{?symbol} is the path that takes in a query parameter named symbol.
  3. Creating a new parameter mapping for the above query parameter: parameter-mapping maps the query parameters in the URL template to intent parameters. This mapping is because the intent parameter of actions.intent.GET_STOCK_QUOTE has the name tickerSymbol, but the name of the query parameter is symbol. required makes the symbol value mandatory for the URL to be valid.
  4. Adding a new fallback fulfillment: In this fulfilment, urlTemplate constructs a new deep link app://stocktracker/home where /home is the path. This fulfillment is triggered when the user invokes the intent without specifying any symbol in the query parameter.
Note: It’s a good practice to always define a fallback fulfillment for handling the different edge cases. You don’t want the user to have a poor experience when they don’t provide valid input.

Open MainActivity.kt to see that the app already handles the deep link paths defined above in handleDeepLink().

Referencing the App Action in Manifest File

Open AndroidManifest.xml and add the following code just before the closing application tag:

<meta-data
  android:name="com.google.android.actions"
  android:resource="@xml/actions" />

The piece of code above makes sure that your actions.xml file is visible to the app. If you used a different name for your actions file, then you must change your android:resource attribute accordingly.

Great job on adding your first App Action successfully! It’s now time to test your App Action.

Testing App Actions

Testing App Actions requires a physical device running API 21 or above. If you try it on a virtual emulator, it may lead to unexpected results. Connect your physical device to your local development machine.

Preparing for Testing

Make sure your device connects to the internet and that Google Assistant is already set up and running. Long-press the home button. If you see a screen similar to the screen below, then you’re all good.

Setting up Google Assistant

Sign in to Android Studio with the same Google account connected to your physical device. This should also be the same account you used to upload the draft app.

Click the white user icon in the top-right of Android Studio 4.0.0 or later. Follow the instructions as they appear. Once you sign in, you can verify your email is correct by clicking the user icon.

Next, install the App Actions Test Tool plugin by going to File ▸ Settings (Android Studio ▸ Preferences on MacOS). Select the Plugins section on the left side and search for App Actions Test Tool in the marketplace.

Android Studio Marketplace plugins displaying that the app actions tool is installed.

Finally, it’s time to try out your new plugin.

Using the App Actions Test Tool

The App Actions Test Tool is a plugin used to test App Actions from Android Studio. It’s a very useful tool during the development phase. It works by creating a preview of your App Action, parsing the actions from the actions.xml file you created above.

Open the App Action Test Tool by going to Tools ▸ App Actions ▸ App Actions Test Tool. You’ll see a screen that looks like this:

App Actions Test Tool window

In the Invocation name field, enter Stock Tracker. This invocation name triggers your App Action. Leave Locale at the default value. Click Create Preview. After a successful preview creation, you’ll see the screen below:

App Actions Test Tool

Notice that it recognizes the built-in intent you added in actions.xml. It also has a tickerSymbol field for making changes. Make sure your target device is showing correctly in this window.

Click Run to test your App Action. It invokes Google Assistant on your device and then deep links into the app to show the correct stock quote for the value passed in tickerSymbol.

Try to invoke Google Assistant manually by saying the command, “Hey, Google, tell me the stock price of Tesla in Stock Tracker”. You’ll see the screen below for a few seconds and then StockTracker opens up, showing you the latest quote.

Google Assistant invoking App Action

Play with your App Actions by testing Google Assistant with different stocks. To test the fallback fulfillment, say “Hey, Google, tell me the current stock price in Stock Tracker”. Since you didn’t specify any stock this time, it uses the fallback fulfillment and opens the home screen of the app with a welcome message.

Stock Tracker home screen

Now that you’ve built and tested your App Action, you can release it to the world!

Deploying App Actions

Note: This section is optional. Feel free to continue if you’d like to know more about the deployment process.

Before deploying your App Action, you’ll need to satisfy a few requirements:

  • If your app has a search functionality, then you must implement the GET_THING built-in intent. This allows users to trigger search queries from Google Assistant.
  • Google also recommends that you use Firebase App Indexing API to improve the Assistant’s search results and suggestions.

Once you’ve met the requirements above, it’s time to start the App Actions review process. Open Google Play Console.

After selecting your app, go to Advanced Settings and click the Actions on Google tab.

Actions on Google tab selected in Advanced Settings

Select the checkbox to open the Actions on Google Terms of Service.

Terms of Service for Actions on Google

Read through the Terms of Service carefully, then click Accept.

Then, upload your app containing actions.xml to Play Console. After this step, Google will email you to let you know if they accept or reject your App Actions.

It’s finally done! Congratulations on completing this tutorial. Now you have one more reason to love Google Assistant. :]

Where to Go From Here?

Download the final project using the Download Materials button at the top or bottom of the tutorial.

In this tutorial, you learned about App Actions and implemented them on a custom StockTracker app. New App Actions are added every day so it’s a great time to start integrating them into your apps.

You can add even more features to your App Actions by integrating them with Android Slices.

Also check out Building an Action for Google Assistant to learn more about conversational design.

I hope you enjoyed this tutorial! If you have any questions or comments, please join the forum discussion below.

Average Rating

5/5

Add a rating for this content

1 rating

More like this

Contributors

Comments