Criar atalhos

Os atalhos apresentam tipos específicos de conteúdo aos usuários, ajudando-os a acessar rapidamente partes do app.

Imagem mostrando o contraste entre atalhos de apps e atalhos fixados
Figura 1. Atalhos de apps e atalhos fixados.

A forma como você envia conteúdo com atalhos depende do seu caso de uso e se o contexto do atalho é orientado pelo app ou pelo usuário. Embora o contexto de um atalho estático não mude e o contexto de um atalho dinâmico mude constantemente, o contexto é impulsionado nos dois casos. Nos casos em que um usuário escolhe como o app entrega conteúdo, como com um atalho fixado, o contexto é definido pelo usuário. Os cenários a seguir descrevem alguns casos de uso para cada tipo de atalho:

  • Os atalhos estáticos são melhores para apps que vinculam a conteúdo usando uma estrutura consistente durante todo o ciclo de vida da interação do usuário com o app. Como a maioria das telas de início exibe apenas quatro atalhos por vez, os atalhos estáticos são úteis para realizar uma tarefa rotineira de maneira consistente, por exemplo, para conferir a agenda ou o e-mail de uma forma específica .
  • Os atalhos dinâmicos são usados para ações em apps contextuais. Os atalhos sensíveis ao contexto são personalizados para as ações que os usuários realizam em um app. Por exemplo, se você criar um jogo que permite que o usuário comece do nível atual na inicialização, é necessário atualizar o atalho com frequência. O uso de um atalho dinâmico permite que você o atualize sempre que o usuário terminar uma fase.
  • Os atalhos fixados são usados para ações específicas do usuário. Por exemplo, o usuário pode querer fixar um site específico na tela de início. Isso é útil porque permite que o usuário realize uma ação personalizada, como navegar até o site em uma etapa, mais rapidamente do que usar uma instância padrão de um navegador.

Criar atalhos estáticos

Os atalhos estáticos oferecem links para ações genéricas no app, e essas ações precisam permanecer consistentes durante o ciclo de vida da versão atual do app. Boas opções para atalhos estáticos incluem visualizar mensagens enviadas, definir um alarme e exibir a atividade física do usuário do dia.

Para criar um atalho estático, siga estas etapas:

  1. No arquivo AndroidManifest.xml do app, localize a atividade com filtros de intent definidos para a ação android.intent.action.MAIN e a categoria android.intent.category.LAUNCHER.

  2. Adicione um elemento <meta-data> a essa atividade que faça referência ao arquivo de recursos em que os atalhos do app são definidos:

      <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                package="com.example.myapplication">
        <application ... >
          <activity android:name="Main">
            <intent-filter>
              <action android:name="android.intent.action.MAIN" />
              <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            
            <meta-data android:name="android.app.shortcuts"
                       android:resource="@xml/shortcuts" /> 
          </activity>
        </application>
      </manifest>
      
  3. Crie um novo arquivo de recursos com o nome res/xml/shortcuts.xml.

  4. No novo arquivo, adicione um elemento raiz <shortcuts> que contenha uma lista de elementos <shortcut>. Em cada elemento <shortcut>, inclua informações sobre um atalho estático, incluindo o ícone, as etiquetas de descrição e as intents que ele inicia no app:

      <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
        <shortcut
          android:shortcutId="compose"
          android:enabled="true"
          android:icon="@drawable/compose_icon"
          android:shortcutShortLabel="@string/compose_shortcut_short_label1"
          android:shortcutLongLabel="@string/compose_shortcut_long_label1"
          android:shortcutDisabledMessage="@string/compose_disabled_message1">
          <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.myapplication"
            android:targetClass="com.example.myapplication.ComposeActivity" />
          <!-- If your shortcut is associated with multiple intents, include them
               here. The last intent in the list determines what the user sees when
               they launch this shortcut. -->
          <categories android:name="android.shortcut.conversation" />
          <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
        </shortcut>
        <!-- Specify more shortcuts here. -->
      </shortcuts>
      

Personalizar valores de atributos

A lista a seguir inclui descrições para os diferentes atributos em um atalho estático. Forneça um valor para android:shortcutId e android:shortcutShortLabel. Todos os outros valores são opcionais.

android:shortcutId

Um literal de string que representa o atalho quando um objeto ShortcutManager realiza operações nele.

android:shortcutShortLabel

Uma frase concisa que descreve a finalidade do atalho. Quando possível, limite essa descrição breve a 10 caracteres.

Para saber mais, consulte setShortLabel().

android:shortcutLongLabel

Uma frase estendida que descreve a finalidade do atalho. Se houver espaço suficiente, a tela de início exibirá esse valor em vez de android:shortcutShortLabel. Quando possível, limite essa descrição longa a 25 caracteres.

Para saber mais, consulte setLongLabel().

android:shortcutDisabledMessage

Mensagem que aparece em uma tela de início compatível quando o usuário tenta iniciar um atalho desativado. A mensagem precisa explicar ao usuário por que o atalho está desativado. O valor desse atributo não terá efeito se android:enabled for true.

android:enabled

Determina se o usuário pode interagir com o atalho em uma tela de início compatível. O valor padrão de android:enabled é true. Se você defini-lo como false, defina um android:shortcutDisabledMessage que explique por que você está desativando o atalho. Se você acha que não precisa enviar essa mensagem, remova totalmente o atalho do arquivo XML.

android:icon

O bitmap ou o ícone adaptativo que a tela de início usa ao mostrar o atalho para o usuário. Esse valor pode ser o caminho para uma imagem ou o arquivo de recursos que contém a imagem. Use ícones adaptativos sempre que possível para melhorar o desempenho e a consistência.

Configurar elementos internos

O arquivo XML que lista os atalhos estáticos de um app é compatível com os seguintes elementos dentro de cada elemento <shortcut>. Você precisa incluir um elemento interno intent para cada atalho estático definido.

intent

A ação iniciada pelo sistema quando o usuário seleciona o atalho. Essa intent precisa fornecer um valor para o atributo android:action.

É possível fornecer várias intents para um único atalho. Consulte Gerenciar várias intents e atividades, Definir uma intent e a referência da classe TaskStackBuilder para mais detalhes.

categories

Oferece um agrupamento dos tipos de ações executadas pelos atalhos do app, como a criação de novas mensagens de chat.

Para ver uma lista de categorias de atalhos com suporte, consulte a referência da classe ShortcutInfo.

capability-binding

Declara o recurso vinculado ao atalho.

No exemplo anterior, o atalho está vinculado a um recurso declarado para CREATE_MESSAGE, que é uma intent integrada de Ações no app. Essa vinculação de capacidade permite que os usuários usem comandos falados com o Google Assistente para invocar um atalho.

Criar atalhos dinâmicos

Os atalhos dinâmicos oferecem links para ações específicas e contextuais no seu app. Essas ações podem mudar entre o uso do app e enquanto ele está em execução. Bons usos de atalhos dinâmicos incluem ligar para uma pessoa específica, navegar até um local específico e carregar um jogo do último ponto salvo do usuário. Você também pode usar atalhos dinâmicos para abrir uma conversa.

A biblioteca ShortcutManagerCompat do Jetpack é um auxiliar da API ShortcutManager, que permite gerenciar atalhos dinâmicos no seu app. O uso da biblioteca ShortcutManagerCompat reduz o código boilerplate e ajuda a garantir que os atalhos funcionem de forma consistente nas versões do Android. Essa biblioteca também é necessária ao enviar atalhos dinâmicos para que eles possam aparecer nas plataformas do Google, como o Google Assistente, com a Biblioteca de integração Google Shortcuts.

A API ShortcutManagerCompat permite que o app execute as seguintes operações com atalhos dinâmicos:

Para ver mais informações sobre como executar operações em atalhos, consulte Gerenciar atalhos e a referência ShortcutManagerCompat.

Veja um exemplo de como criar um atalho dinâmico e associá-lo ao app:

Kotlin


val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

Adicionar a biblioteca de integração do Google Shortcuts

A biblioteca de integração do Google Shortcuts é uma biblioteca opcional do Jetpack. Ele permite enviar atalhos dinâmicos que podem ser mostrados nas plataformas do Android, como a tela de início, e nas plataformas do Google, como o Google Assistente. O uso dessa biblioteca ajuda os usuários a descobrir seus atalhos para acessar rapidamente conteúdo específico ou repetir ações no app.

Por exemplo, um app de mensagens pode enviar um atalho dinâmico para um contato chamado "Alex" depois que um usuário envia uma mensagem para essa pessoa. Depois que o atalho dinâmico for enviado, se o usuário perguntar ao Google Assistente: "Ok Google, enviar uma mensagem ao Alex no ExampleApp", o Assistente poderá iniciar o ExampleApp e configurá-lo automaticamente para enviar uma mensagem para Alex.

Os atalhos dinâmicos enviados com essa biblioteca não estão sujeitos aos limites de atalhos aplicados por dispositivo. Isso permite que o app envie um atalho sempre que um usuário conclui uma ação associada no app. O envio de atalhos frequentes dessa forma permite que o Google entenda os padrões de uso do usuário e sugira atalhos contextuais para ele.

Por exemplo, ele pode aprender com atalhos enviados pelo app de monitoramento de condicionamento físico que um usuário normalmente executa todas as manhãs e sugerir proativamente um atalho "iniciar uma corrida" quando o usuário pegar o smartphone de manhã.

A biblioteca de integração Google Shortcuts não oferece nenhuma funcionalidade endereçável. A adição dessa biblioteca ao app permite que as plataformas do Google aceitem os atalhos enviados pelo app usando ShortcutManagerCompat.

Para usar essa biblioteca no seu app, siga estas etapas:

  1. Atualize o arquivo gradle.properties para oferecer compatibilidade com as bibliotecas do AndroidX:

          
          android.useAndroidX=true
          # Automatically convert third-party libraries to use AndroidX
          android.enableJetifier=true
          
          
  2. Em app/build.gradle, adicione dependências para a biblioteca de integração Google Shortcuts e ShortcutManagerCompat:

          
          dependencies {
            implementation "androidx.core:core:1.6.0"
            implementation 'androidx.core:core-google-shortcuts:1.0.0'
            ...
          }
          
          

Com as dependências de biblioteca adicionadas ao projeto Android, o app pode usar o método pushDynamicShortcut() de ShortcutManagerCompat para enviar atalhos dinâmicos qualificados para exibição na tela de início e nas plataformas do Google participantes.

Criar atalhos fixados

No Android 8.0 (nível 26 da API) ou versões posteriores, é possível criar atalhos fixados. Ao contrário dos atalhos estáticos e dinâmicos, os atalhos fixados aparecem nas telas de início com suporte como ícones separados. A Figura 1 mostra a diferença entre esses dois tipos de atalhos.

Para fixar um atalho em uma tela de início compatível usando o app, siga estas etapas:

  1. Use isRequestPinShortcutSupported() para verificar se a tela de início padrão do dispositivo é compatível com a fixação de atalhos no app.
  2. Crie um objeto ShortcutInfo de duas maneiras, dependendo da existência do atalho:

    1. Se o atalho existir, crie um objeto ShortcutInfo que contenha apenas o ID do atalho existente. O sistema encontra e fixa automaticamente todas as outras informações relacionadas ao atalho.
    2. Se você estiver fixando um novo atalho, crie um objeto ShortcutInfo que contenha um ID, uma intent e um rótulo curto para o novo atalho.
  3. Fixe o atalho na tela de início do dispositivo chamando requestPinShortcut(). Durante esse processo, você pode transmitir um objeto PendingIntent, que notifica seu app somente quando o atalho é fixado.

    Depois que um atalho é fixado, seu app pode atualizar o conteúdo usando o método updateShortcuts(). Para saber mais, leia Atualizar atalhos.

O snippet de código a seguir demonstra como criar um atalho fixado.

Kotlin

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Java

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

Criar uma atividade de atalho personalizada

Uma imagem mostrando a atividade da caixa de diálogo personalizada que mostra a solicitação &quot;Quer adicionar o ícone na tela de início do Gmail?&quot;. As opções personalizadas são &quot;Agora não&quot; e &quot;Adicionar ícone&quot;.
Figura 2. Exemplo de uma atividade personalizada da caixa de diálogo do atalho de app.

Você também pode criar uma atividade especializada que ajuda os usuários a criar atalhos, com opções personalizadas e um botão de confirmação. A Figura 2 mostra um exemplo desse tipo de atividade no app Gmail.

No arquivo de manifesto do app, adicione ACTION_CREATE_SHORTCUT ao elemento <intent-filter> da atividade. Essa declaração define o seguinte comportamento quando o usuário tenta criar um atalho:

  1. O sistema inicia a atividade especializada do app.
  2. O usuário define opções para o atalho.
  3. O usuário seleciona o botão de confirmação.
  4. Seu app cria o atalho usando o método createShortcutResultIntent(). Esse método retorna um Intent, que o app redireciona para a atividade em execução anteriormente usando setResult().
  5. Seu app chama finish() na atividade usada para criar o atalho personalizado.

Da mesma forma, seu app pode solicitar que os usuários adicionem atalhos fixados à tela inicial após a instalação ou na primeira vez que o app for iniciado. Esse método é eficaz porque ajuda os usuários a criar um atalho como parte do fluxo de trabalho comum.

Atalhos de teste

Para testar os atalhos do app, instale-o em um dispositivo com uma tela de início compatível com atalhos. Em seguida, faça o seguinte:

  • Toque e mantenha pressionado o ícone na tela de início do app para conferir os atalhos que você definiu para ele.
  • Arraste um atalho para fixá-lo na tela de início do dispositivo.