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 parâmetros de intent para o fulfillment, você permite que o Google Assistente inicie seu 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 e as consultas de exemplo que podem ser usados para teste está na referência de intents integradas.

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

​

Implementar BIIs e processar parâmetros de intent

Para Ações no app, declare recursos e processe parâmetros de BII no arquivo atalhos.xml. Para implementar uma BII e processar os parâmetros dela, 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. Caso você use targetClass ou targetPackage, mapeie-os para a intent extras do Android usando o 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, mapeie esse parâmetro para o parâmetro correspondente de uma intent explícita do Android no capability. Em seguida, você pode usar o valor dele no seu app, que não precisa processar parâmetros de BII. No entanto, tente processar os campos de dados marcados como "Recomendado" 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 adequado com base nos parâmetros de recurso identificados na consulta do usuário e naqueles 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 app. Por exemplo, as consultas de usuários 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 desse app.

Como requisito extra, o app não deve executar diretamente uma ação que modifica 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

Argumentos transmitidos ao app por <url-parameter> ou extras de intents podem não identificar exclusivamente o item que você quer mostrar ao usuário. Nesse caso, use o valor do argumento como um 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 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 à localidade diferente para testes de desenvolvedores e para acionamento de usuários pelo Google Assistente.