As Ações no app permitem que os usuários conversem com o Google Assistente e acessem diretamente destinos específicos quando dizem algo como Ok Google, peça uma viagem no app de exemplo. Com a invocação de aplicativo em primeiro plano, você pode melhorar ainda mais a experiência quando um usuário já está com o app aberto.
A invocação de app em primeiro plano permite que intents integradas (BIIs, na sigla em inglês) sejam correspondidas sem exigir que o nome do app seja mencionado enquanto uma atividade específica está no primeiro plano do dispositivo.
Por exemplo, um usuário está com o app de transporte por aplicativo compartilhado em primeiro plano e diz ou digita: "Fazer uma viagem para Mountain View" no Google Assistente. O app usa essa entrada para definir o campo de destino como Mountain View. Então, quando o usuário disser ou digitar "Pedir uma viagem saindo do aeroporto de Guarulhos", seu app poderá definir o local de embarque e preservar o estado dele.
Limitações
A invocação de aplicativo em primeiro plano está disponível apenas para as BIIs abaixo:
actions.intent.CREATE_MONEY_TRANSFER
actions.intent.CREATE_TAXI_RESERVATION
actions.intent.OPEN_APP_FEATURE
actions.intent.ORDER_MENU_ITEM
actions.intent.PAUSE_EXERCISE
actions.intent.RECORD_EXERCISE
actions.intent.RECORD_FOOD_OBSERVATION
actions.intent.RESUME_EXERCISE
actions.intent.START_EXERCISE
actions.intent.STOP_EXERCISE
Para ter suporte a localidades e ver consultas de exemplo relacionadas à invocação de aplicativo em primeiro plano para uma BII específica, consulte a referência de intents integradas.
Suporte à invocação de aplicativo em primeiro plano
Para oferecer suporte à invocação de aplicativo em primeiro plano, é preciso adicionar o comportamento de fulfillment com base em uma atividade em primeiro plano desejada. Quando essa atividade está em primeiro plano e Ações no app são invocadas, o Google Assistente transmite a intent de link direto com uma sinalização extra a essa atividade para que o app possa atualizar o estado dela.
Para implementar a invocação de app em primeiro plano para uma BII, faça o seguinte:
- No arquivo
shortcuts.xml
, adicione uma tag<intent>
à BII<capability>
que você quer oferecer suporte à invocação de apps em primeiro plano. - Na tag
<intent>
, adicione uma tag<extra>
. - Na tag
<extra>
, definaandroid:key
como"requiredForegroundActivity"
e definaandroid:value
como a atividade que você quer que fique em primeiro plano. Especifique a atividade sem abreviações de classe usando o nome do pacote do app, seguido de uma barra (/) seguida pelo nome da atividade:APP_PACKAGE_NAME/ACTIVITY_NAME
- Na atividade em primeiro plano especificada para
"requiredForegroundActivity"
, implemente o métodoonNewIntent()
para processar uma intent de link direto com a sinalizaçãoSINGLE_TOP
definida. O Google Assistente transmite a intent de link direto com essa sinalização como fulfillment quando a atividade especificada está em primeiro plano. - Trate chamadas do método
onNewIntent()
como atualizações da atividade em primeiro plano e gerencie o estado nessa atividade usando parâmetros extraídos do link direto.
Se o app usa uma atividade do roteador para permitir que todos os links diretos externos acionem uma única atividade do roteador, consulte Gerenciar atividades do roteador.
Exemplo
O snippet abaixo de um exemplo de arquivo shortcuts.xml
mostra como adicionar o
atributo requiredForegroundActivity
:
<capability name="actions.intent.CREATE_TAXI_RESERVATION"> <!-- Trigger with foreground app invocation if MainActivity is in the foreground. --> <intent android:targetClass="com.example.app.MainActivity" android:targetPackage="com.example.app"> <parameter android:name="taxiReservation.dropoffLocation.name" android:key="dropoff" /> <extra android:key="requiredForegroundActivity" android:value="com.example.app/com.example.app.MainActivity" /> </intent> <!-- This won't trigger if MainActivity is in the foreground. --> <intent android:targetClass="com.example.app.MainActivity" android:targetPackage="com.example.app"> <parameter android:name="taxiReservation.dropoffLocation.name" android:key="dropoff" /> </intent> </capability>
Permissões do usuário
Para que a invocação de aplicativo em primeiro plano funcione para um usuário, a configuração Usar texto da tela do dispositivo precisa estar ativada. O local e o nome exato dessa configuração podem variar de acordo com o OEM ou fabricante do dispositivo. Por exemplo, a configuração do dispositivo pode ter o nome Usar contexto da tela no dispositivo de um usuário.
Para acessar essa configuração do Android em um smartphone Pixel, primeiro acesse Configurações > Apps e notificações > Apps padrão > App Assistente. Depois, na tela Assistente e entrada por voz, ative a opção Usar texto da tela.
Testar a invocação
Para testar a invocação do aplicativo em primeiro plano, siga estas etapas:
- Siga as instruções na seção Permissões do usuário para ativar a configuração Usar texto da tela no dispositivo.
- Abra o app na atividade listada como a atividade em primeiro plano necessária.
- Toque e pressione o botão home para abrir o Google Assistente como uma sobreposição no app atual. Faça uma consulta que corresponda à BII implementada, sem mencionar o nome do app. Quando implementado corretamente, o app é atualizado com base na consulta, mantendo o estado e sem reiniciar a atividade.
Processar atividades do roteador
Alguns apps processam todos os links diretos externos usando uma única atividade de roteador de bloqueio. A atividade do roteador inicia a atividade de lógica de negócios apropriada (após qualquer verificação e validação) e retorna a atividade de lógica de negócios ao primeiro plano.
Acionar um link direto pode fazer com que a atividade do roteador seja adicionada à parte de cima da pilha de tarefas, acima da atividade em primeiro plano. Para apps que usam uma atividade de roteador, verifique se a atividade do roteador mostra a intent enviada pelo Google Assistente à instância de atividade em primeiro plano atual. A forma como você satisfaz esse requisito muda dependendo de onde a atividade do roteador começa.
Se o roteador começar na mesma pilha de tarefas que a atividade da lógica de negócios,
encaminhe a intent usando o operador bit a bit OR de SINGLE_TOP
, CLEAR_TOP
e NEW_TASK
:
Kotlin
Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK
Java
Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK
Se o roteador começar em uma pilha de tarefas separada da atividade de lógica
de negócios, encaminhe a intent com a sinalização SINGLE_TOP
para a atividade de lógica
de negócios.