Criar atalhos

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

A maneira como você apresenta conteúdos com os atalhos depende do 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 de um atalho dinâmico mude constantemente, seu app controla o contexto nos dois casos. Nos casos em que um usuário escolhe como seu 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 conteúdo usando uma estrutura consistente ao longo da interação do usuário com o app. Como a maioria das telas de início mostra apenas quatro atalhos por vez, os atalhos estáticos são úteis para realizar uma tarefa de rotina de maneira consistente, como se o usuário quiser ver a agenda ou o e-mail de uma forma específica.
• Os atalhos dinâmicos são usados para ações em apps com reconhecimento de contexto. 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 permita que o usuário comece do nível atual na inicialização, atualize o atalho com frequência. Com um atalho dinâmico, é possível atualizar o atalho sempre que o usuário terminar uma fase.
• Os atalhos fixados são usados para ações específicas controladas pelo usuário. Por exemplo, o usuário pode querer fixar um site específico na tela de início. Isso é bom, porque permite que o usuário realize uma ação personalizada, como navegar para o site em uma só etapa, de modo mais rápido do que com o uso de 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. Essas ações precisam permanecer consistentes ao longo da vida útil da versão atual do app. Algumas boas opções para atalhos estáticos são ver mensagens enviadas, definir um alarme e mostrar a atividade física do usuário para o dia.

Para criar um atalho estático, faça o seguinte:

1. No arquivo AndroidManifest.xml do app, encontre a atividade cujos filtros de intent estejam 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 estã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 arquivo de recurso chamado res/xml/shortcuts.xml.

4. No novo arquivo de recursos, 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, os rótulos 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.Main" />
       <!-- 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>
   shortcuts.xml

Personalizar valores de atributos

A lista a seguir inclui descrições dos diferentes atributos em um atalho estático. Informe 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 executa operações nele.

android:shortcutShortLabel

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

Para ver mais informações, consulte setShortLabel().

android:shortcutLongLabel

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

Para ver mais informações, consulte setLongLabel().

android:shortcutDisabledMessage

A 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ê definir como false, defina uma android:shortcutDisabledMessage que explique por que você está desativando o atalho. Se você não acha necessário mostrar essa mensagem, remova completamente 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 de classe TaskStackBuilder para mais detalhes.

categories

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

Para ver uma lista de categorias de atalhos compatíveis, consulte a referência de 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 app. Essas ações podem mudar entre os usos do app e enquanto ele está em execução. Alguns bons exemplos de casos de uso para atalhos dinâmicos são ligar para uma pessoa específica, navegar para um local específico e carregar um jogo a partir do último ponto salvo pelo usuário. Você também pode usar atalhos dinâmicos para abrir uma conversa.

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

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

• Enviar e atualizar:use pushDynamicShortcut() para publicar e atualizar seus atalhos dinâmicos. Se já houver atalhos dinâmicos ou fixados com o mesmo ID, cada atalho mutável será atualizado.
• Remover:remova um conjunto de atalhos dinâmicos usando removeDynamicShortcuts(). Remova todos os atalhos dinâmicos usando removeAllDynamicShortcuts().

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

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

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)
ShortcutsSnippets.kt

Adicionar a biblioteca de integração do Google Shortcuts

A biblioteca de integração do Google Shortcuts é uma biblioteca opcional do Jetpack. Ela permite enviar atalhos dinâmicos que podem ser exibidos em plataformas do Android, como a tela de início, e em plataformas do Google. Com essa biblioteca, os usuários descobrem seus atalhos para acessar rapidamente conteúdo específico ou repetir ações no app.

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 concluir uma ação associada no app. Enviar atalhos frequentes dessa forma permite que o Google entenda os padrões de uso do usuário e sugira atalhos contextualmente relevantes para ele.

Por exemplo, o Google Assistente pode aprender com atalhos enviados do seu app de monitoramento de condicionamento físico que um usuário costuma correr toda manhã e sugerir proativamente um atalho "iniciar uma corrida" quando o usuário pegar o smartphone pela manhã.

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

Para usar essa biblioteca no seu app, adicione dependências para a Biblioteca de integração do Google Shortcuts e ShortcutManagerCompat ao arquivo app/build.gradle ou app/build.gradle.kts:

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

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 seu Projeto do Android, seu app pode usar o método pushDynamicShortcut() de ShortcutManagerCompat para enviar atalhos dinâmicos que podem ser exibidos 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 fixados aparecem em ícones separados nos iniciadores compatíveis. A Figura 1 mostra a distinção entre esses dois tipos de atalhos.

Para fixar um atalho em um iniciador compatível usando seu app, siga estas etapas:

1. Use isRequestPinShortcutSupported() para verificar se o iniciador padrão do dispositivo é compatível com a fixação de atalhos no app.

2. Crie um objeto ShortcutInfoCompat que contenha um ID, uma intent e um rótulo curto para o atalho. Se o atalho existir, use o ID dele. O sistema encontra e fixa automaticamente todas as outras informações relacionadas ao atalho.

3. Fixe o atalho no iniciador do dispositivo chamando requestPinShortcut(). Durante esse processo, você pode transmitir um objeto PendingIntent, que notifica seu app apenas quando o atalho é fixado.

   Depois que um atalho é fixado, o app pode atualizar o conteúdo dele usando o método updateShortcuts(). Para mais informações, leia Atualizar atalhos.

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

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

Criar uma atividade de atalho personalizada

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 configura 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. O app cria o atalho usando o método createShortcutResultIntent(). Esse método retorna um Intent, que o app retransmite para a atividade em execução anterior usando setResult().
5. Seu app chama finish() na atividade usada para criar o atalho personalizado.

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

Testar atalhos

Para testar os atalhos do app, instale-o em um dispositivo com um iniciador que aceite atalhos. Em seguida, faça o seguinte:

• Toque e pressione o ícone na tela de início do app para conferir os atalhos definidos para ele.
• Arraste um atalho para fixá-lo no iniciador do dispositivo.