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
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.
![Uma captura de tela do Android Sharesheet](https://developer.android.com/static/images/guide/topics/ui/shortcuts/sharesheet.png?hl=pt-br)
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:
- Atalhos estáticos: atalhos que têm o método
isDeclaredInManifest()
retornatrue
. - Atalhos dinâmicos: atalhos com
ShortcutInfo.isDynamic()
retornatrue
.
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.
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.
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()
:
- No arquivo
AndroidManifest.xml
, inclua a atribuição do atributoandroid:taskAffinity=
pol. na atividade trampolim. - 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
:
- Um app de chat publica quatro atalhos dinâmicos, representando os quatro conversas recentes: c1, c2, c3 e c4.
- O usuário fixa todos os quatro atalhos.
- 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.
- 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. - É possível usar as APIs
addDynamicShortcuts(Context, List)
e MétodossetDynamicShortcuts(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.
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.
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. } } } // ... }