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 contexto de um atalho dinâmico mude constantemente, em ambos os casos ele é direcionado pelo app. Nos casos em que o usuário escolhe como o app exibirá o conteúdo, como com um atalho fixado, o contexto é definido pelo usuário. As situações a seguir demonstram alguns casos de uso para cada tipo de atalho:

  • Os atalhos estáticos são melhores para apps vinculados a conteúdo que usa uma estrutura consistente ao longo da interação do usuário com o app. Como a maior parte das telas de início só pode exibir quatro atalhos por vez, os atalhos estáticos são úteis para atividades comuns. Por exemplo, se o usuário quiser ver a agenda ou o e-mail de uma forma específica, um atalho estático garantirá que a experiência de execução de uma tarefa de rotina seja consistente.
  • Os atalhos dinâmicos são usados para ações em apps com reconhecimento de contexto. Por exemplo, caso você crie um jogo que permita que o usuário comece de onde parou na tela de início, o atalho precisará ser atualizado com frequência. O uso de um atalho dinâmico permite que o atalho seja atualizado 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. Alguns bons candidatos para atalhos estáticos são ver mensagens enviadas, definir um alarme e exibir a atividade física do usuário para um dia específico.

Para criar um atalho estático, siga a seguinte sequência de etapas:

  1. No arquivo de manifesto do app (AndroidManifest.xml), localize uma atividade cujos filtros de intent estejam configurados 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 novo arquivo de recursos: res/xml/shortcuts.xml.

  4. Nesse novo arquivo, adicione um elemento raiz <shortcuts>, que contenha uma lista de elementos <shortcut>. Cada elemento <shortcut> contém 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" />
      </shortcut>
      <!-- Specify more shortcuts here. -->
    </shortcuts>
    

Personalizar valores de atributos

A lista a seguir inclui descrições dos diferentes atributos em um atalho estático. Você precisa fornecer 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.

Observação: não é possível definir o valor desse atributo como uma string de recursos, como @string/foo.

android:shortcutShortLabel

Uma frase concisa que descreve a finalidade do atalho. Quando possível, limite o tamanho da "descrição curta" de um atalho a 10 caracteres.

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

Observação: o valor desse atributo precisa ser uma string de recursos, como @string/shortcut_short_label.

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 o tamanho da "descrição longa" de um atalho a 25 caracteres.

Para saber mais, consulte setLongLabel().

Observação: o valor desse atributo precisa ser uma string de recursos, como @string/shortcut_long_label.

android:shortcutDisabledMessage

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

Observação: o valor desse atributo precisa ser uma string de recursos, como @string/shortcut_disabled_message.

android:enabled

Determina se o usuário pode interagir com o atalho a partir de uma tela de início compatível. O valor padrão de android:enabled é true. Se você defini-lo como false, defina também uma android:shortcutDisabledMessage que explique por que você desativou o atalho. Se você não acha necessário exibir essa mensagem, é mais fácil remover completamente o atalho do arquivo XML.

android:icon

Bitmap ou ícone adaptativo usado pela tela de início ao exibir o atalho para o usuário. Esse valor pode ser o caminho para uma imagem ou o arquivo de recursos contendo a imagem. Use ícones adaptativos sempre que possível para melhorar o desempenho e a consistência.

Observação: os ícones de atalhos não podem incluir tonalidades.

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 de 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.

Observação: esse elemento de intent não pode incluir recursos de string.

É 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 saber 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.

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 até mesmo enquanto o app está em execução. Alguns bons candidatos a 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.

A API ShortcutManager permite que você execute as seguintes operações em atalhos dinâmicos:

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

Um exemplo de como criar um atalho dinâmico e associá-lo ao seu app aparece no snippet de código a seguir:

Observação: as instâncias da classe ShortcutManager precisam ser adquiridas usando Context.getSystemService(Class) com o argumento ShortcutManager.class ou Context.getSystemService(String) com o argumento Context.SHORTCUT_SERVICE.

Kotlin

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

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

shortcutManager!!.dynamicShortcuts = Arrays.asList(shortcut)

Java

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

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

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

Criar atalhos fixados

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

Observação: quando você tenta fixar um atalho em uma tela de início compatível, o usuário recebe uma caixa de diálogo de confirmação que solicita permissão para fixar o atalho. Se o usuário não permitir, a tela de início cancelará a solicitação.

Captura de tela mostrando a diferença entre os atalhos de apps
  e os atalhos fixados.
Figura 1. Aparência de atalhos de apps e atalhos fixados.

Para fixar um atalho a uma tela de início compatível usando seu app, siga esta sequência de 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 uma das duas formas, dependendo da existência ou não do atalho:

    1. Se o atalho já existe, crie um objeto ShortcutInfo contendo apenas o ID do atalho existente. O sistema encontra e fixa automaticamente todas as outras informações relacionadas ao atalho.
    2. Ao fixar um novo atalho, crie um objeto ShortcutInfo contendo um ID, uma intent e uma descrição curta do novo atalho.

    Observação: como o sistema realiza automaticamente o backup e a restauração em atalhos fixados, os IDs desses atalhos precisam conter strings estáveis e constantes ou identificadores do lado do servidor, em vez de identificadores gerados localmente que podem não fazer sentido em outros dispositivos.

  3. Tente fixar o atalho à tela de início do dispositivo chamando requestPinShortcut(). Durante esse processo, é possível transmitir um objeto PendingIntent, que notifica seu app somente quando o atalho é fixado.

    Observação: se o usuário não permitir que o atalho seja fixado à tela de início, o app não receberá um callback.

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

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

Observação: as instâncias da classe ShortcutManager precisam ser adquiridas usando Context.getSystemService(Class) com o argumento ShortcutManager.class ou Context.getSystemService(String) com o argumento Context.SHORTCUT_SERVICE.

Kotlin

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

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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());
}

Observação: consulte também as APIs da Biblioteca de Suporte, isRequestPinShortcutSupported() e requestPinShortcut(), que funcionam no Android 7.1 (API de nível 25) e versões anteriores. A Biblioteca de Suporte aciona o EXTRA_SHORTCUT_INTENT suspenso para tentar realizar o processo de fixação.

Criar uma atividade de atalho personalizada

A atividade da caixa de diálogo personalizada mostra a solicitação &quot;Adicionar
      o ícone do Gmail na tela de início?&quot;. As opções personalizadas são
     &quot;Não&quot; e &quot;Adicionar ícone&quot;.
Figura 2. Exemplo de uma atividade de caixa de diálogo personalizada para o atalho de app.

Também é possível criar uma atividade especializada que ajuda o usuário 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.

Adicione ACTION_CREATE_SHORTCUT ao elemento <intent-filter> da atividade no arquivo de manifesto do seu app. 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 que estava em execução anteriormente, usando setResult().
  5. O app chama finish() na atividade usada para criar o atalho personalizado.

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

Testar atalhos

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 no ícone do seu app na tela de início para ver os atalhos que você definiu para o app.
  • Toque em um atalho e arraste-o para fixá-lo na tela de início do dispositivo.