Intents integradas para Ações no app

As intents integradas (BIIs, na sigla em inglês) permitem que o app expresse os recursos de fulfillment para o Google. Ao declarar recursos no arquivo shortcuts.xml e mapear os parâmetros de intent para o fulfillment, o Google Assistente pode iniciar o app em uma tela específica, em resposta a uma consulta, para que o usuário possa concluir uma tarefa.

As intents integradas são agrupadas de acordo com as categorias do app. Cada categoria representa um conjunto de tarefas comuns que os usuários querem realizar nos apps. A lista completa de BIIs disponíveis, os parâmetros delas e as consultas de exemplo que podem ser usadas para testes está na referência de intents integradas.

Muitas BIIs têm requisitos e recomendações de implantação específicos. Esses requisitos e recomendações ajudam seu app a oferecer a melhor experiência possível aos usuários.

Figura 1. Invoque a BII START_EXERCISE com uma consulta por voz ao Google Assistente.
Figura 2. Inicie o app em uma tela específica para iniciar a tarefa START_EXERCISE.
Figura 3. Mostrar um widget em resposta a uma consulta.

​

Implementar BIIs e processar parâmetros de intent

Para Ações no app, declare recursos e processe parâmetros de BII no arquivo shortcuts.xml. Para implementar uma BII e processar os parâmetros, siga estas etapas:

  1. Declare capability com a BII escolhida.
  2. Adicione elementos parameter aninhados para cada campo de BII que você quiser adicionar.
    1. Se você usar targetClass ou targetPackage, mapeie-os para a intent extras do Android usando um nome escolhido.
    2. Se você usar um URL de link direto, use os parâmetros nomeados na string de consulta do modelo de URL.

Para processar um parâmetro de BII, associe-o ao parâmetro correspondente de uma intent explícita do Android na sua capability. Em seguida, você pode usar o valor dela no seu app. Ele não precisa processar parâmetros de BII. No entanto, tente processar os campos de dados marcados como "Recomendados" na referência de intents integradas.

É possível definir vários fulfillments de intent, cada um com o próprio conjunto de parâmetros recomendados. O Google seleciona o fulfillment apropriado com base nos parâmetros de recurso identificados na consulta do usuário e nos declarados em uma intent.

Por exemplo, a intent actions.intent.START_EXERCISE recomenda que o app processe o parâmetro de BII exercise.name, mas você pode implementar a BII no app sem parâmetros. Você pode fazer isso se quiser processar consultas de usuários sem o nome do exercício específico, como "Peça ao app de exemplo para começar a monitorar o exercício".

O snippet a seguir tem um substituto para um fulfillment sem parâmetros obrigatórios, se os parâmetros não estiverem incluídos na consulta do usuário:

<?xml version="1.0" encoding="utf-8"?>
<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:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

O Google Assistente faz o possível para fornecer as informações mais relevantes ao usuário ao retornar valores de parâmetro ao seu app. Por exemplo, as consultas do usuário para pedir pizza no app para dispositivos móveis do Restaurante Exemplo nem sempre incluem um local. Para atender melhor o usuário, o Google Assistente pode fornecer os valores de latitude e longitude do restaurante de exemplo mais próximo ao app.

Além disso, você não quer que o app execute uma ação diretamente que modifique o estado real de um usuário (por exemplo, transferir dinheiro, fazer um pedido ou enviar uma mensagem) sem primeiro confirmar a ação com o usuário.

Desambiguação

Os argumentos transmitidos ao app por <url-parameter> ou extras de intent podem não identificar exclusivamente o item que você quer mostrar ao usuário. Nesse caso, use o valor do argumento como argumento de pesquisa e leve o usuário à página de pesquisa do app. Ele pode remover a ambiguidade e escolher o item certo.

Por exemplo, se a consulta de um usuário for "Pedido do restaurante de exemplo" para a BII ORDER_MENU_ITEM, você poderá apresentar ao usuário uma lista de restaurantes com nomes que correspondem ao termo "Example Restaurant".

Suporte a idiomas e localidades

As localidades com suporte para desenvolvimento e teste de cada BII de Ações no app estão listadas na referência de intents integradas. Algumas BIIs têm suporte local para testes de desenvolvedores e para acionamento de usuários no Google Assistente.