Join us live on October 16-18th for our virtual DevFest. Register now.

Preparing to deploy your App Action

To ensure that users enjoy a seamless experience when using App Actions, there are additional implementation steps before activating App Actions for your app:

  • (Required) Implement the GET_THING built-in intent: If your app has a search function, implement the actions.intent.GET_THING built-in intent (BII) for that search function. Your app can then provide search results to users for queries like "Hey Google, search for ExampleThing on ExampleApp.".
  • (Optional, but highly recommended) Report App Action interaction results: To help Google proactively suggest your App Actions to users, use the Firebase App Indexing API to let Assistant know whether your app has successfully handled a built-in intent.

By implementing these functions, you complete the first step to submitting App Actions for review and deployment.

Implement the GET_THING built-in intent

If your app has a search function, implement the actions.intent.GET_THING built-in intent for that search function. Google Assistant can then forward users to your app's search function for in-app results when they make queries like "Hey Google, search for ExampleThing on ExampleApp.".

In your actions.xml file, implement actions.intent.GET_THING as you would implement any other BII. You can use multiple fulfillments for GET_THING, as long as you provide at least one fulfillment that passes the user query to your app's search function.

Here's an example of adding the actions.intent.GET_THING built-in intent in actions.xml:

<action intentName="actions.intent.GET_THING">
    <fulfillment urlTemplate="exampleapp://search{?query}">
        <parameter-mapping intentParameter="thing.name" urlParameter="query"/>
    </fulfillment>
</action>

In the deep link handler that triggers your search activity, extract the search query and pass it to your app's search functionality. In the above code, the search query (passed as the urlParameter value) maps to the "thing.name" built-in intent parameter. Then, perform a search with the query and display the results in the user interface.

Here's an example of extracting the query parameter in a search activity:

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  // ...
  Intent intent = getIntent();
  switch(intent.getData().getPath()) {
    case "/search":
      String query = intent.getData().getQueryParameter("query");
      // Use query value to perform a search
      break;
  }
  // ...
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    //...
    when (intent?.data?.path) {
        "/search" -> {
            val query = intent.data?.getQueryParameter(DeepLink.Params.QUERY)
            // Use query value to perform a search
        }
    }
    // ...
}

Report interaction results

Google monitors the health of your App Actions to know when they aren't working as intended. You can let Google know using Firebase whether your app successfully handled a built-in intent with App Actions.

To report interaction results, take these steps in your Android app:

  1. Add Firebase and the App Indexing library to your Android Studio project.
  2. For deep-linked activities launched via App Actions, use the FirebaseUserActions class to report either that the App Action invocation was handled by your app successfully or that it was not.

    For example, a user uses App Actions to order soup from a soup provider. The user is deep linked to a confirmation page prior to adding the soup to a cart. At this point, the app reports a success via FirebaseUserActions.

    As another example, a user uses App Actions to order soup from a provider who can't fulfill their request (like a shoe store). The app only supports deep links for items in inline inventory. When the deep link handler runs, the app reports a failure via FirebaseUserActions.

    Note that if this app handled the absence of the desired item with a fallback search for the string in inventory, the app would have reported a success instead.

You can tell that an activity was launched via App Actions if the incoming deep link matches the format of a URL template defined in your actions.xml file. Because you define both the URL template and how an activity handles deep links, you can flag and recognize deep links from App Actions in a way that best suits your app.

For example, in your actions.xml file, you can add a query string parameter to the URL template of the <fulfillment> element. In the corresponding activity, you can then look for that parameter to determine whether a user triggered the deep link via App Actions.

The following code snippet shows how to use the FirebaseUserActions class to report status when users invoke your App Actions:

Java

private static final String ACTION_TOKEN_EXTRA =
        "actions.fulfillment.extra.ACTION_TOKEN";

void notifyActionStatus(String status) {
  String actionToken = getIntent().getStringExtra(ACTION_TOKEN_EXTRA);
  final Action action = new AssistActionBuilder()
          .setActionToken(actionToken)
          .setActionStatus(status)
          .build();
  FirebaseUserActions.getInstance().end(action);
}

// On Action success
notifyActionStatus(Action.Builder.STATUS_TYPE_COMPLETED);

// On Action failed
notifyActionStatus(Action.Builder.STATUS_TYPE_FAILED);
      

Kotlin

private val actionTokenExtra = "actions.fulfillment.extra.ACTION_TOKEN"

fun notifyActionStatus(status: String) {
    val actionToken = intent.getStringExtra(actionTokenExtra)
    val action = AssistActionBuilder()
            .setActionToken(actionToken)
            .setActionStatus(status)
            .build()
    FirebaseUserActions.getInstance().end(action)
}

// On Action success
notifyActionStatus(Action.Builder.STATUS_TYPE_COMPLETED)

// On Action failed
notifyActionStatus(Action.Builder.STATUS_TYPE_FAILED)
      

Make sure that you're uploading the action data to Google servers (default behavior) by not setting setUpload(false).

You can verify that the correct logs are being reported by doing the following:

  1. In Android Studio, open the App Actions test tool and create a preview of your App Actions. If you've already created a preview, update your preview instead.
  2. On your test device, enable developer options if not already enabled.
  3. In the Settings app, select Google, then Firebase App Indexing.
  4. Toggle Capture User Actions and Errors to On.
  5. Trigger your App Action intent on your test device using Assistant or the App Actions test tool.
  6. Return to the Firebase App Indexing page of the Settings app and select your app.

  7. Verify that the AssistAction user action contains items for actionToken and actionStatus.

  8. Verify that the actionStatus item contains the status corresponding to success or failure of the triggered built-in intent. Validate your Firebase logging separately for successes and failures.

The actionStatus and actionToken items are highlighted in a device screenshot of the User Action Details page.