Adicionar recursos a atalhos

Os recursos no shortcuts.xml permitem que você declare os tipos de ações que os usuários podem realizar para iniciar o app e executar diretamente uma tarefa específica.

Por exemplo, as Ações no app do Google Assistente usam recursos para permitir que os desenvolvedores estendam recursos no app para intents integradas (BIIs), permitindo que os usuários ativem e controlem esses recursos usando comandos falados. Um recurso consiste no nome da ação e em um intent direcionado ao destino no app que resolve a intenção do usuário.

Definir recursos em atalhos.xml

Você define elementos capability em um arquivo de recurso shortcuts.xml no seu projeto de desenvolvimento do app Android. Para definir um elemento capability, faça o seguinte:

  1. Crie um recurso shortcuts.xml seguindo as instruções em Criar atalhos estáticos.

  2. Inclua no seu recurso as seguintes informações necessárias:

    • Nome do recurso:a ação que você quer que seu aplicativo aceite. Consulte a documentação do componente para o recurso que requer definições de recurso. Os comandos ativados por voz das Ações no app usam o BII Action ID com nomes de recursos, que podem ser encontrados na referência de BII. Por exemplo, o GET_THING BII lista o Action ID como actions.intent.GET_THING.

    • Destino do app: o destino no seu app que a ação lança para atender à solicitação do usuário. Defina os destinos de aplicativos usando intent elementos aninhados dentro do capability.

    • Mapeamentos de parâmetros: cada intent pode conter parâmetros a serem transmitidos como dados extra do intent. Por exemplo, cada BII de ações do app inclui campos que representam informações que os usuários geralmente fornecem em consultas que acionam o BII.

O exemplo a seguir demonstra uma definição de recursos em shortcuts.xml para actions.intent.START_EXERCISE, uma BI que permite que os usuários usem comandos falados com o Google Assistente para iniciar um treino em um app de fitness:

<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:targetPackage="com.example.sampleApp"
      android:targetClass="com.example.sampleApp.ExerciseActivity">
      <parameter
        android:name="exercise.name"
        android:key="exerciseType"/>
    </intent>
  </capability>
</shortcuts>

No exemplo anterior, o atributo <capability> android:name se refere a o BII START_EXERCISE. Se um usuário invocar essa BII pedindo ao Assistente, "Ok Google, inicie uma execução em ExampleApp", o Assistente atenderá a solicitação usando as informações fornecidas no elemento intent aninhado. O intent neste exemplo define os seguintes detalhes:

  • O android:targetPackage define o pacote do aplicativo de destino para este intent.
  • O campo android:targetClass especifica a atividade de destino: com.example.sampleApp.ExerciseActivity.
  • A intent parameter declara suporte a um parâmetro de BII exercise.name e como transmitir o valor do parâmetro, coletado do usuário, como dados extras no intent.

Associar atalhos a um recurso

Depois de definir um recurso, é possível estender a funcionalidade associando atalhos estáticos ou dinâmicos a ele. A forma como os atalhos são vinculados a um capability depende do recurso que está sendo implementado e das palavras reais incluídas na solicitação do usuário. Por exemplo, quando um usuário inicia uma execução no seu app de rastreamento de condicionamento físico perguntando ao Google Assistente: "Ok Google, iniciar uma execução em ExampleApp" O Google Assistente pode usar um atalho para iniciar uma instância de um capability que define uma entidade de exercício válida de "execução" para o parâmetro exercise.name.

Para mais informações sobre como associar atalhos às Ações no app, consulte a Visão geral das Ações no app.