Gerenciar atalhos

Depois de criar atalhos, talvez seja necessário gerenciá-los durante o ciclo de vida seu app. Por exemplo, talvez você queira otimizar seu app determinando como a frequência com que os usuários concluem ações específicas com seus atalhos. Em outro caso, desative um atalho fixado para evitar que seu app com ações desatualizadas ou ausentes. Para atalhos referenciados em você pode querer acompanhar o uso para fornecer sinais que melhoram classificação de atalhos.

Esta página descreve essas e várias outras formas comuns de gerenciar sua atalhos de teclado.

Comportamento de atalhos

As seções a seguir contêm informações gerais sobre o comportamento dos atalhos, incluindo visibilidade, ordem de exibição e classificações.

Visibilidade de atalhos

Importante: todas as informações de atalhos são armazenadas em credenciais criptografadas por credencial armazenamento, para que o app não possa acessar os atalhos do usuário até que ele seja desbloqueado no dispositivo.

Os atalhos estáticos e os atalhos dinâmicos aparecem em uma tela de início compatível ou um assistente quando o usuário faz um gesto ou comando de voz específico. Ativado telas de início compatíveis, o gesto é um toque e segure o ícone na tela de início do app mas o gesto pode ser diferente em outros apps de tela de início. Com o Google Assistente: os atalhos podem ser mostrados no Assistente ou iniciados por um usuário comando de voz.

A classe LauncherApps fornece APIs para que apps na tela de início acessem. atalhos de teclado.

Como os atalhos fixados aparecem na própria tela de início, eles estão sempre visíveis. Um atalho fixado só é removido da tela de início nas seguintes situações:

• Removido pelo usuário.
• O app associado ao atalho foi desinstalado.
• O usuário limpa os dados de um app acessando Configurações > Aplicativos e notificações, selecione o app e toque em Armazenamento > Limpar armazenamento.

Metas de compartilhamento são um subconjunto de atalhos dinâmicos que aparecem na linha de compartilhamento direto do Página de compartilhamento do Android.

Figura 1. Android Sharesheet. Os alvos de compartilhamento direto aparecem na primeira linha, seguidos pelos apps classificados e pelas listas de apps.

Ordem de exibição de atalhos

Quando a tela de início mostra os atalhos de um app, eles precisam aparecer da seguinte forma: ordem:

1. Atalhos estáticos: atalhos que têm o método isDeclaredInManifest() retorna true.
2. Atalhos dinâmicos: atalhos com ShortcutInfo.isDynamic() retorna true.

Em cada tipo de atalho (estático e dinâmico), os atalhos são classificados em ordem Aumentando a classificação de acordo com ShortcutInfo.getRank. Google Assistente também considera a classificação do atalho ao determinar os atalhos contextuais a serem exibidos usuários.

As classificações são números inteiros sequenciais não negativos. Os atalhos estáticos são classificados primeiro na ordem em que aparecem no arquivo shortcuts.xml. Para recursos dinâmicos atalhos, você pode atualizar as classificações de atalhos existentes ao chamar updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) ou setDynamicShortcuts(Context, List)

A ordem das metas de compartilhamento é baseada em vários fatores, incluindo usuários anteriores histórico, tempo para retorno, frequência, dica de classificação, uso do app e a prioridade definida na conversa associada a um o atalho de compartilhamento. Metas de compartilhamento criadas com o API Share Shortcuts são priorizados em relação aos alvos de compartilhamento ChooserTargetService que foi descontinuado no Android 11. No Android 12 e em metas de compartilhamento mais recentes gerados pelo ChooserTargetService descontinuado não vão mais aparecer na compartilhar planilha.

A maioria das telas de início exibem no máximo quatro atalhos. Para qualquer combinação de atalhos estáticos e dinâmicos definidos, o inicializador exibe uma no máximo dois atalhos estáticos e dois atalhos dinâmicos. Por exemplo, se você definir quatro atalhos estáticos e criar programaticamente três atalhos dinâmicos o acesso rápido mostra os dois primeiros atalhos estáticos e os dois atalhos dinâmicos com melhor classificação.

Observação :as classificações são ajustadas automaticamente para serem exclusivas para cada tipo de estático ou dinâmico. Por exemplo, se houver três atalhos dinâmicos com classificações 0, 1 e 2, adicionando outro atalho dinâmico com classificação 1 representa uma solicitação para colocar esse atalho na segunda posição. Em resposta, a classificação dos atalhos que antes eram classificados como 1 e 2 muda para 2 e 3. respectivamente.

Gerenciar várias intents e atividades

Se você quiser que seu app execute várias operações quando o usuário ativar uma , é possível configurá-lo para acionar atividades sucessivas. Você pode para isso, atribuindo várias intents, iniciando uma atividade a partir outro ou definir flags de intent, dependendo do tipo de atalho.

Atribuir várias intents

Ao criar um atalho com o ShortcutInfoCompat.Builder, você pode usar setIntents() em vez de setIntent(). Ao chamar setIntents(), você pode iniciar várias atividades no aplicativo quando o usuário seleciona um atalho; colocando todas as atividades da lista, exceto a última, na pilha de retorno. Se o o usuário então toca no botão "Voltar" do dispositivo, outra atividade é mostrada no app. em vez de retornar à tela de início do dispositivo.

Observação: quando o usuário seleciona um atalho e toca no botão "Voltar", seu O app vai iniciar a atividade correspondente à penúltima intent listada em no arquivo de recursos de atalhos. Esse padrão de comportamento continua enquanto o usuário continua tocando no botão "Voltar" até que o usuário limpe a backstack que um o atalho é criado. Então, se o usuário tocar no botão "Voltar" novamente, o sistema leva-o de volta para a tela de início.

Iniciar uma atividade a partir de outra

Os atalhos estáticos não podem ter flags de intent personalizadas. O primeiro intent de um objeto estático atalho sempre tem Intent.FLAG_ACTIVITY_NEW_TASK e Intent.FLAG_ACTIVITY_CLEAR_TASK definido. Isso significa que, quando seu app em execução, todas as atividades existentes no aplicativo serão destruídas quando um objeto atalho seja iniciado. Se não quiser que isso aconteça, use um trampolim atividade: uma atividade invisível que inicia outra atividade em Activity.onCreate(Bundle) que chama Activity.finish():

1. No arquivo AndroidManifest.xml, inclua a atribuição do atributo android:taskAffinity= pol. na atividade trampolim.
2. No arquivo de recursos dos atalhos, faça referência à atividade trampolim no dentro do atalho estático.

Para mais informações sobre atividades trampolim, consulte Como iniciar uma atividade de outro.

Definir sinalizações de intent

Você pode publicar atalhos dinâmicos com qualquer conjunto de sinalizações Intent. De preferência, especifique Intent.FLAG_ACTIVITY_CLEAR_TASK junto com o outro de status. Caso contrário, se você tentar iniciar outra tarefa enquanto o aplicativo estiver em execução, a atividade de destino pode não aparecer.

Para saber mais sobre tarefas e flags de intent, consulte Tarefas e a backstack.

Atualização de atalhos

O ícone na tela de início de cada app pode conter, no máximo, vários recursos estáticos e dinâmicos atalhos combinados, que é igual ao valor retornado por getMaxShortcutCountPerActivity Não há um limite para o número de atalhos fixados que um aplicativo pode criar.

Quando um atalho dinâmico é fixado, mesmo quando o editor o remove como um atalho dinâmico, o atalho fixado vai estar visível e poderá ser iniciado. Isso permite um app tem mais de getMaxShortcutCountPerActivity() de atalhos.

Considere o exemplo a seguir, que pressupõe que o valor retornado por getMaxShortcutCountPerActivity() é 4:

1. Um app de chat publica quatro atalhos dinâmicos, representando os quatro conversas recentes: c1, c2, c3 e c4.
2. O usuário fixa todos os quatro atalhos.
3. Mais tarde, o usuário inicia outras três conversas: c5, c6 e c7. A app de editor republica seus atalhos dinâmicos. O novo atalho dinâmico lista é: c4, c5, c6, e c7.

O app precisa remover c1, c2 e c3, porque não é possível exibir mais de quatro atalhos dinâmicos. No entanto, c1, c2 e c3 ainda são atalhos fixados que o que o usuário pode acessar e iniciar.

O usuário pode então acessar um total de sete atalhos que se vinculam a atividades em app do editor. Isso ocorre porque o total inclui o número máximo de e os três atalhos fixados.

1. O app pode usar updateShortcuts(Context, List) para atualizar qualquer um dos sete atalhos existentes. Por exemplo, você pode atualizar este conjunto de atalhos quando os colegas do chat mudança dos ícones.
2. É possível usar as APIs addDynamicShortcuts(Context, List) e Métodos setDynamicShortcuts(Context, List) para atualizar atalhos existentes com os mesmos IDs. No entanto, não é possível usá-las para atualizar modelos fixados, porque esses dois métodos tentam converter as listas fornecidas de para atalhos dinâmicos.

Não há um limite para o número de atalhos que podem ser enviados para exibição no como o Google Assistente. Usar o pushDynamicShortcut() método da biblioteca ShortcutManagerCompat do Jetpack para criar e atualizar atalhos para uso em apps de assistência. Além disso, adicione a integração do Google Shortcuts biblioteca ao seu app para tornar os links dinâmicos qualificados para exibição no Google Google Assistente.

Para saber mais sobre as diretrizes de atalhos de apps, incluindo atualização de atalhos, consulte Práticas recomendadas para atalhos.

Processar as mudanças de localidade do sistema

Os apps precisam atualizar os atalhos dinâmicos e fixados quando recebem a Transmissão Intent.ACTION_LOCALE_CHANGED indicando uma mudança no sistema localidade.

Rastrear o uso de atalhos

Para determinar as situações em que os atalhos estáticos e dinâmicos aparecem, o iniciador examina o histórico de ativação dos atalhos. Para atalhos estáticos, você pode acompanhar quando os usuários concluem ações específicas no seu aplicativo chamando o método reportShortcutUsed() e transmitindo o ID de um atalho quando ocorrer um dos seguintes eventos:

• O usuário selecionar o atalho com o ID fornecido.
• No app, o usuário conclui manualmente a ação correspondente ao mesmo atalho.

Seu app rastreia o uso de atalhos dinâmicos chamando o método método pushDynamicShortcut() e transmitindo o ID do atalho quando uma um evento relevante. Enviar o uso de atalhos dinâmicos com este método permite apps de assistente, como o Google Assistente, sugerem atalhos relevantes aos usuários. Como o método pushDynamicShortcut() informa o uso quando chamado, não chame o método reportShortcutUsed() para os mesmos atalhos.

Para atalhos relacionados a conversas, é importante controlar o uso de mensagens enviadas e as mensagens recebidas. Para mais detalhes, consulte as práticas recomendadas para pessoas e conversas.

Observação: a biblioteca de integração do Google Shortcuts é necessária para ativar os links dinâmicos enviados pelo app para que ele esteja qualificado para aparecer nas plataformas do Google como o Google Assistente. Ao adicionar essa biblioteca ao seu app, você permite que o Google Assistente recebe seus links dinâmicos e os sugere aos usuários pelo app Google Assistente.

Desativar atalhos

Como o app e os usuários podem fixar atalhos na tela de início do dispositivo, é é possível que esses atalhos fixados direcionem os usuários a ações no aplicativo que estão desatualizados ou não existem mais. Para gerenciar essa situação, você pode desative os atalhos que você não quer que os usuários selecionem chamando disableShortcuts, que remove os atalhos especificados da imagem estática e desativa cópias fixadas desses atalhos. Você também pode usar uma versão sobrecarregada desse método que aceita uma CharSequence como uma mensagem de erro personalizada. Essa mensagem de erro aparece quando os usuários tentam iniciar qualquer atalho desativado.

Observação: se você remover alguns atalhos estáticos do app ao atualizar o app, o sistema desativará esses atalhos automaticamente.

Limitação de taxa

Ao usar setDynamicShortcuts(), addDynamicShortcuts(), ou updateShortcuts(), talvez só seja possível chamá-los de um número específico de vezes em um app em segundo plano: um app sem atividades ou serviços em primeiro plano. O limite para o número específico de vezes que você pode chamar esses métodos é chamada de limitação de taxa. Esse recurso impede ShortcutManagerCompat por causa dos recursos do dispositivo que consomem em excesso.

Quando a limitação de taxa está ativa, isRateLimitingActive() retorna "true". No entanto, a limitação de taxa é redefinida durante certos eventos. Assim, mesmo os apps em segundo plano pode chamar métodos ShortcutManager até que o limite de taxa seja atingido novamente. Esses incluem o seguinte:

• Um app aparece em primeiro plano.
• A localidade do sistema muda.
• O usuário executa a ação de resposta in-line em uma notificação.

Se você encontrar limitação de taxa durante o desenvolvimento ou teste, selecione Opções do desenvolvedor > Redefina o limite de taxa do ShortcutsManager no dispositivo configurações ou digite o seguinte comando em adb:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Backup e restauração

Você pode permitir que os usuários realizem operações de backup e restauração no app quando a mudança de dispositivos incluindo o android:allowBackup="true" atributo atribuição no arquivo de manifesto do app. Se você oferecer suporte a backup e restauração, mantenha os seguintes pontos sobre atalhos de apps em mente:

• Os atalhos estáticos são publicados novamente de forma automática, mas somente depois que o usuário reinstala o app em um novo dispositivo.
• Os atalhos dinâmicos não são armazenados em backup. Por isso, inclua lógica no app para republicar quando um usuário abrir o app em um novo dispositivo.
• Os atalhos fixados são restaurados automaticamente na tela de início do dispositivo, mas o sistema não faz backup de ícones associados a atalhos fixados. Portanto, salve seus atalhos fixados" imagens no seu app para que seja fácil restaurá-las um novo dispositivo.

O snippet de código a seguir mostra a melhor forma de restaurar a dinâmica do app e como verificar se os atalhos fixados do seu app foram preservados:

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}