Criar blocos personalizados de Configurações rápidas para o app

As Configurações rápidas são blocos exibidos no painel de Configurações rápidas, representando ações que os usuários podem tocar para concluir rapidamente tarefas recorrentes. O app pode fornecer um Bloco personalizado aos usuários pela classe TileService e usar um objeto Tile para acompanhar o estado do Bloco. Por exemplo, é possível criar um bloco que permita aos usuários ativar ou desativar uma VPN fornecida pelo app.

Figura 1. Painel de configurações rápidas com o bloco de VPN ativado e desativado.

Observação: este guia discute apenas blocos que não são do Wear. Os blocos de configurações rápidas não têm relação com os blocos definidos no Wear OS. Para blocos do Wear OS, consulte o guia de blocos do Wear OS.

Decidir quando criar um bloco

Recomendamos criar blocos para funcionalidades específicas que você espera que os usuários acessem com frequência ou precisem de acesso rápido (ou ambos). Os blocos mais eficazes são aqueles que correspondem a essas duas qualidades, oferecendo acesso rápido a ações realizadas com frequência.

Por exemplo, você pode criar um Bloco para um app de fitness que permita aos usuários iniciar rapidamente uma sessão de treino. No entanto, não recomendamos criar um Bloco para o mesmo app que permita aos usuários analisar todo o histórico de treinos.

Figura 2. Exemplos de blocos recomendados e não recomendados para um app de fitness.

Para melhorar a detecção e a facilidade de uso do bloco, recomendamos evitar algumas práticas:

• Evite usar blocos para iniciar um app. Use um atalho de app ou um iniciador padrão.

• Evite usar blocos para ações únicas do usuário. Use um atalho de app ou uma notificação.

• Evite criar muitos Blocos. Recomendamos no máximo dois por app. Use um atalho de app.

• Evite usar blocos que mostram informações, mas não são interativos para os usuários. Use uma notificação ou um widget.

Criar o bloco

Para criar um bloco, primeiro é necessário criar um ícone de bloco adequado e, em seguida, criar e declarar o TileService no arquivo de manifesto do app.

Observação: criar uma TileService para o app não adiciona o app ao painel de configurações rápidas do usuário. O TileService atua como uma interface com o bloco somente depois que o usuário o adiciona.

O exemplo de Configurações rápidas mostra como criar e gerenciar um bloco.

Criar um ícone personalizado

Você precisa fornecer um ícone personalizado, que aparece no bloco no painel "Configurações rápidas". Você vai adicionar esse ícone ao declarar o TileService, descrito na próxima seção. O ícone precisa ser branco sólido com um plano de fundo transparente, ter 24 x 24 dp e estar na forma de um VectorDrawable.

Figura 3. Exemplo de drawable vetorial.

Crie um ícone que indique visualmente o propósito do bloco. Isso ajuda os usuários a identificar facilmente se o bloco atende às necessidades deles. Por exemplo, é possível criar um ícone de um cronômetro para um Bloco em um app fitness que permite que os usuários iniciem uma sessão de treino.

Criar e declarar o TileService

Crie um serviço para o bloco que estenda a classe TileService.

Kotlin

class MyQSTileService: TileService() {

  // Called when the user adds your tile.
  override fun onTileAdded() {
    super.onTileAdded()
  }
  // Called when your app can update your tile.
  override fun onStartListening() {
    super.onStartListening()
  }

  // Called when your app can no longer update your tile.
  override fun onStopListening() {
    super.onStopListening()
  }

  // Called when the user taps on your tile in an active or inactive state.
  override fun onClick() {
    super.onClick()
  }
  // Called when the user removes your tile.
  override fun onTileRemoved() {
    super.onTileRemoved()
  }
}

Java

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

Declare o TileService no arquivo de manifesto do app. Adicione o nome e o rótulo do TileService, o ícone personalizado que você criou na seção anterior e a permissão adequada.

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

Gerenciar o TileService

Depois de criar e declarar o TileService no manifesto do app, é necessário gerenciar o estado dele.

TileService é um serviço vinculado. O TileService é vinculado quando solicitado pelo app ou se o sistema precisar se comunicar com ele. Um ciclo de vida de serviço vinculado típico contém os quatro métodos de callback a seguir: onCreate(), onBind(), onUnbind() e onDestroy(). Esses métodos são invocados pelo sistema sempre que o serviço entra em uma nova fase do ciclo de vida.

Importante: o TileService ainda vai passar pelo ciclo de vida típico do Service. No entanto, o TileService é diferente da maioria dos outros serviços vinculados porque ele contém métodos de ciclo de vida específicos do TileService aos quais o app precisa reagir.

Visão geral do ciclo de vida do TileService

Além dos callbacks que controlam o ciclo de vida do serviço vinculado, é necessário implementar outros métodos específicos do ciclo de vida TileService. Esses métodos podem ser chamados fora de onCreate() e onDestroy() porque os métodos de ciclo de vida Service e TileService são chamados em dois encadeamentos assíncronos separados.

O ciclo de vida da TileService contém os seguintes métodos, que são invocados pelo sistema sempre que a TileService entra em uma nova fase do ciclo de vida:

• onTileAdded(): esse método é chamado apenas quando o usuário adiciona o bloco pela primeira vez e se o usuário remover e adicionar o bloco novamente. Esse é o melhor momento para fazer qualquer inicialização única. No entanto, isso pode não atender a toda a inicialização necessária.

  Observação: onTileAdded() não é chamado sempre que o Bloco é criado. Por exemplo, onTileAdded() não é chamado quando o dispositivo é reinicializado ou ligado se o bloco foi adicionado e não removido antes que o dispositivo fosse desligado.

• onStartListening() e onStopListening(): esses métodos são chamados sempre que o app atualiza o bloco e são chamados com frequência. O TileService permanece vinculado entre onStartListening() e onStopListening(), permitindo que o app modifique o Bloco e envie atualizações.

• onTileRemoved(): esse método é chamado apenas se o usuário remover o bloco.

Atenção: essas fases podem não ocorrer consecutivamente. O onTileAdded() só pode ser chamado uma vez quando o bloco é adicionado por um usuário ao painel de Configurações rápidas. onStartListening() e onStopListening() podem ser chamados várias vezes durante o ciclo de vida da TileService. onTileRemoved() nunca será chamado se o usuário não remover o bloco do painel de Configurações rápidas.

Selecionar um modo de escuta

O TileService ouve no modo ativo ou não ativo. Recomendamos o uso do modo ativo, que você precisa declarar no manifesto do app. Caso contrário, o TileService é o modo padrão e não precisa ser declarado.

Não suponha que o TileService vai existir fora do par de métodos onStartListening() e onStopListening().

Modo ativo (recomendado)

Use o modo ativo para uma TileService que ouve e monitora o estado dela no próprio processo. Um TileService no modo ativo é vinculado a onTileAdded(), onTileRemoved(), eventos de toque e quando solicitado pelo processo do app.

Recomendamos o modo ativo se o TileService for notificado quando o estado do bloco precisar ser atualizado pelo próprio processo. Os blocos ativos limitam a tensão no sistema porque não precisam ser vinculados sempre que o painel de Configurações rápidas fica visível para o usuário.

O método estático TileService.requestListeningState() pode ser chamado para solicitar o início do estado de escuta e receber um callback para onStartListening().

É possível declarar o modo ativo adicionando o META_DATA_ACTIVE_TILE ao arquivo de manifesto do app.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

Modo não ativo

O modo não ativo é o padrão. Um TileService está no modo não ativo se for vinculado sempre que o bloco estiver visível para o usuário. Isso significa que o TileService pode ser criado e vinculado novamente em momentos fora de seu controle. Ele também pode ser desvinculado e destruído quando o usuário não está visualizando o bloco.

O app recebe um callback para onStartListening() depois que o usuário abre o painel de configurações rápidas. É possível atualizar o objeto Tile quantas vezes quiser entre onStartListening() e onStopListening().

Cuidado: se você usar o modo não ativo em vez do modo ativo, o TileService poderá ser vinculado sempre que o usuário abrir o painel de configurações rápidas.

Não é necessário declarar o modo não ativo. Basta não adicionar o META_DATA_ACTIVE_TILE ao arquivo de manifesto do app.

Visão geral dos estados de blocos

Depois que um usuário adiciona o bloco, ele sempre existe em um dos seguintes estados.

• STATE_ACTIVE: indica um estado ativado ou ativo. O usuário pode interagir com o bloco nesse estado.

  Por exemplo, em um bloco de app de fitness que permite que os usuários iniciem uma sessão de treino com cronômetro, STATE_ACTIVE significa que o usuário iniciou uma sessão de treino e o cronômetro está em execução.

• STATE_INACTIVE: indica um estado desativado ou pausado. O usuário pode interagir com o bloco nesse estado.

  Para usar o exemplo de bloco de app de fitness novamente, um bloco em STATE_INACTIVE significaria que o usuário não iniciou uma sessão de treino, mas poderia fazer isso se quisesse.

• STATE_UNAVAILABLE: indica um estado temporariamente indisponível. O usuário não pode interagir com o bloco nesse estado.

  Por exemplo, um bloco em STATE_UNAVAILABLE significa que ele não está disponível para o usuário no momento por algum motivo.

  Cuidado: use STATE_UNAVAILABLE para blocos que estão indisponíveis no momento, mas que podem ser disponibilizados mais tarde. Se o componente nunca vai estar disponível para o usuário novamente, transmita COMPONENT_ENABLED_STATE_DISABLED para setComponentEnabledSetting().

O sistema só define o estado inicial do objeto Tile. Você define o estado do objeto Tile ao longo do restante do ciclo de vida dele.

O sistema pode colorir o ícone e o plano de fundo do bloco para refletir o estado do objeto Tile. Os objetos Tile definidos como STATE_ACTIVE são os mais escuros, com STATE_INACTIVE e STATE_UNAVAILABLE cada vez mais claros. A matiz exata é específica para o fabricante e a versão.

Figura 4. Exemplos de um bloco colorido para refletir o estado dele (ativo, inativo e indisponível, respectivamente).

Atualizar o Bloco

Você pode atualizar o Bloco depois de receber um callback para onStartListening(). Dependendo do modo do bloco, ele pode ser atualizado pelo menos uma vez até receber um callback para onStopListening().

No modo ativo, você pode atualizar o bloco exatamente uma vez antes de receber um callback para onStopListening(). No modo não ativo, você pode atualizar o bloco quantas vezes quiser entre onStartListening() e onStopListening().

Observação: o modo ativo permite atualizar o Bloco, independentemente de ele estar visível para o usuário ou não.

É possível recuperar o objeto Tile chamando getQsTile(). Para atualizar campos específicos do objeto Tile, chame estes métodos:

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

Observação: o ícone e o rótulo definidos no arquivo de manifesto do app são os valores padrão exibidos no bloco do painel de configurações rápidas. No entanto, você pode chamar os métodos setIcon() e setLabel() ao atualizar o bloco para definir os campos com novos valores.

Chame updateTile() para atualizar o bloco depois de definir os campos do objeto Tile com os valores corretos. Isso fará com que o sistema analise os dados atualizados do bloco e atualize a interface.

Kotlin

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
  super.onStartListening()
  val state = getStateFromService()
  qsTile.label = state.label
  qsTile.contentDescription = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

Java

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

Processar toques

Os usuários podem tocar no bloco para acionar uma ação se ele estiver em STATE_ACTIVE ou STATE_INACTIVE. Em seguida, o sistema invoca o callback onClick() do app.

Quando o app recebe um callback para onClick(), ele pode iniciar uma caixa de diálogo ou atividade, acionar um trabalho em segundo plano ou mudar o estado do bloco.

Kotlin

var clicks = 0
override fun onClick() {
  super.onClick()
  counter++
  qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.label = "Clicked $counter times"
  qsTile.contentDescription = qsTile.label
  qsTile.updateTile()
}

Java

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

Iniciar uma caixa de diálogo

showDialog() reduz o painel de configurações rápidas e mostra uma caixa de diálogo. Use uma caixa de diálogo para adicionar contexto à ação se ela exigir mais entradas ou consentimento do usuário.

Observação: isLocked() verifica se a tela de bloqueio do usuário está sendo exibida. Quando isLocked() retorna verdadeiro, showDialog() não apresenta uma caixa de diálogo visível, porque ela é carregada abaixo da tela de bloqueio.

Iniciar uma atividade

startActivityAndCollapse() inicia uma atividade ao recolher o painel. As atividades são úteis quando há informações mais detalhadas para mostrar do que em uma caixa de diálogo ou quando a ação é muito interativa.

Se o app exigir uma interação significativa do usuário, ele só poderá iniciar uma atividade como último recurso. Em vez disso, use uma caixa de diálogo ou uma chave.

Tocar e segurar um bloco faz com que a tela Informações do app seja mostrada ao usuário. Para substituir esse comportamento e iniciar uma atividade para definir preferências, adicione um <intent-filter> a uma das suas atividades com ACTION_QS_TILE_PREFERENCES.

A partir da API 28 do Android, o PendingIntent precisa ter o Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

Como alternativa, adicione a flag no AndroidManifest.xml na seção Activity específica.

Marcar o bloco como comutável

Recomendamos marcar o Bloco como alternável se ele funcionar principalmente como um interruptor de dois estados, que é o comportamento mais comum dos Blocos. Isso ajuda a fornecer informações sobre o comportamento do bloco para o sistema operacional e melhorar a acessibilidade geral.

Defina os metadados TOGGLEABLE_TILE como true para marcar o Bloco como alternável.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Realizar apenas ações seguras em dispositivos com bloqueio seguro

O bloco pode aparecer na parte de cima da tela de bloqueio em dispositivos bloqueados. Se o bloco conter informações sensíveis, verifique o valor de isSecure() para determinar se o dispositivo está em um estado seguro. O TileService vai mudar o comportamento de acordo com isso.

Se a ação do bloco puder ser realizada com segurança enquanto o dispositivo estiver bloqueado, use startActivity() para iniciar uma atividade na parte de cima da tela de bloqueio.

Se a ação do bloco não for segura, use unlockAndRun() para pedir que o usuário desbloqueie o dispositivo. Se for bem-sucedido, o sistema vai executar o objeto Runnable transmitido para esse método.

Pedir que o usuário adicione seu bloco

Para adicionar o bloco manualmente, os usuários precisam seguir várias etapas:

1. Deslize para baixo para abrir o painel "Configurações rápidas".
2. Toque no botão de edição.
3. Role por todos os blocos no dispositivo até encontrar o seu.
4. Mantenha o bloco pressionado e arraste-o para a lista de blocos ativos.

O usuário também pode mover ou remover o bloco a qualquer momento.

A partir do Android 13, é possível usar o método requestAddTileService() para facilitar a adição do bloco a um dispositivo. Esse método pede aos usuários que adicionem o bloco diretamente ao painel de Configurações rápidas. O comando inclui o nome do aplicativo, o rótulo fornecido e o ícone.

Figura 5. Solicitação da API de posicionamento de Configurações rápidas.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

O callback contém informações sobre se o Bloco foi adicionado ou não, se ele já estava lá ou se algum erro ocorreu.

Use sua discrição ao decidir quando e com que frequência pedir algo aos usuários. Recomendamos chamar requestAddTileService() somente no contexto, por exemplo, quando o usuário interage pela primeira vez com um recurso que seu bloco facilita.

O sistema pode parar de processar solicitações para um determinado ComponentName se ele já tiver sido negado pelo usuário várias vezes. O usuário é determinado pelo Context usado para recuperar esse serviço. Ele precisa corresponder ao usuário atual.

Observação: recomendamos chamar requestAddTileService() para aumentar a visibilidade do bloco e reduzir a necessidade de o usuário adicionar o bloco ao painel de Configurações rápidas.