Invocação de aplicativo em primeiro plano

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.

Observação: não é possível testar a invocação de aplicativo em primeiro plano usando o botão Executar na ferramenta de teste de Ações no app. Para tentar a invocação de aplicativo em primeiro plano antes do envio, acione Ações no app no dispositivo de teste usando o Google Assistente depois de criar uma prévia para o app.

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.

Observação: ao usar fragmentos como destinos no app, comunique as informações da intent ao fragmento relevante.

Para implementar a invocação de app em primeiro plano para uma BII, faça o seguinte:

1. No arquivo shortcuts.xml, adicione uma tag <intent> à BII <capability> que você quer oferecer suporte à invocação de apps em primeiro plano.
2. Na tag <intent>, adicione uma tag <extra>.
3. Na tag <extra>, defina android:key como "requiredForegroundActivity" e defina android: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
4. Na atividade em primeiro plano especificada para "requiredForegroundActivity", implemente o método onNewIntent() para processar uma intent de link direto com a sinalização SINGLE_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.
5. 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.

Observação: as intents são resolvidas de cima para baixo. Portanto, coloque as intents com uma atividade em primeiro plano necessária acima de outras intents em um <capability> para dar prioridade a elas.

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:

1. Siga as instruções na seção Permissões do usuário para ativar a configuração Usar texto da tela no dispositivo.
2. Abra o app na atividade listada como a atividade em primeiro plano necessária.
3. 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.