Cómo crear tarjetas de Configuración rápida personalizadas para tu app

La Configuración rápida son tarjetas que se muestran en el panel de Configuración rápida y que representan acciones que los usuarios pueden presionar para completar rápidamente tareas recurrentes. Tu app puede proporcionar una tarjeta personalizada a los usuarios a través de la clase TileService y usar un objeto Tile para hacer un seguimiento del estado de la tarjeta. Por ejemplo, podrías crear una tarjeta que permita a los usuarios activar o desactivar una VPN proporcionada por tu app.

Figura 1: Panel de Configuración rápida con la tarjeta de VPN activada encenderse y apagarse.

Nota: En esta guía, solo se analizan las tarjetas que no son de Wear; las de Configuración rápida no tienen con las tarjetas definidas en Wear OS. Para tarjetas de Wear OS, consulta el Guía de tarjetas de WearOS.

Decide cuándo crear una tarjeta

Te recomendamos que crees tarjetas para funcionalidades específicas a las que esperas que los usuarios accedan con frecuencia o que necesiten acceso rápido (o ambas). Las tarjetas más eficaces son las que combinan ambas cualidades y proporcionan acceso rápido a las acciones que se realizan con frecuencia.

Por ejemplo, puedes crear una tarjeta para una app de fitness que permita a los usuarios iniciar rápidamente una sesión de entrenamiento. Sin embargo, no te recomendamos crear una tarjeta para la misma app que permitiría a los usuarios revisar todo su historial de entrenamiento.

Figura 2: Ejemplos de tarjetas recomendadas y no recomendadas para una app de fitness

Para ayudar a mejorar la visibilidad y facilidad de uso de tu tarjeta, te recomendamos y evitar ciertas prácticas:

• Evita usar tarjetas para iniciar una app. En su lugar, usa un atajo de la app o un selector estándar.

• Evita usar tarjetas para las acciones del usuario únicas. Usa un acceso directo a una app o notification.

• Evita crear demasiadas tarjetas. Recomendamos un máximo de dos por app. En su lugar, usa un atajo de la app.

• Evita usar tarjetas que muestren información, pero que no sean interactivas para los usuarios. En su lugar, usa una notificación o un widget.

Crea tu tarjeta

Para crear una tarjeta, primero debes crear un ícono de tarjeta adecuado y, luego, Crea y declara tu TileService en el archivo de manifiesto de tu app.

Nota: Crear un TileService para tu app no la agrega al panel de Configuración rápida del usuario. Tu TileService actúa como una interfaz solo con la tarjeta luego de que el usuario la haya agregado.

El ejemplo de Configuración rápida proporciona un ejemplo de cómo crear y administrar una tarjeta.

Crea tu ícono personalizado

Deberás proporcionar un ícono personalizado, que se mostrará en la tarjeta del panel de Configuración rápida. (Agregarás este ícono cuando declares el TileService, como se describe en la siguiente sección). El ícono debe ser de color blanco sólido con un fondo transparente, medir 24 × 24 dp y tener la forma de un VectorDrawable.

Figura 3: Ejemplo de un elemento de diseño vectorial.

Crea un ícono que sugiera visualmente el propósito de tu tarjeta. Esto ayuda a los usuarios identificar fácilmente si tu mosaico se ajusta a sus necesidades. Por ejemplo, puedes crear un ícono de cronómetro para una tarjeta de una app de fitness que permita a los usuarios iniciar una sesión de entrenamiento.

Cómo crear y declarar tu TileService

Crea un servicio para tu tarjeta que extienda la clase 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();
  }
}

Declara tu TileService en el archivo de manifiesto de tu app. Agrega el nombre y la etiqueta de tu TileService, el ícono personalizado que creaste en la sección anterior y el permiso adecuado.

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

Administra tu TileService

Una vez que hayas creado y declarado tu TileService en el manifiesto de tu app, debes administrar su estado.

TileService es un servicio vinculado. Tu TileService está vinculado cuando solicitada por tu app o si el sistema necesita comunicarse con ella. Un ciclo de vida de servicio vinculado típico contiene los siguientes cuatro métodos de devolución de llamada: onCreate(), onBind(), onUnbind() y onDestroy(). El sistema invoca estos métodos cada vez que el servicio entra en una nueva fase del ciclo de vida.

Importante: Tu TileService seguirá pasando por el ciclo de vida típico de Service. Sin embargo, TileService difiere de la mayoría de los otros servicios vinculados porque contiene métodos de ciclo de vida específicos de TileService a los que tu app debe reaccionar.

Descripción general del ciclo de vida de TileService

Además de las devoluciones de llamada que controlan el ciclo de vida del servicio vinculado, debes implementar otros métodos específicos del ciclo de vida de TileService. Estos métodos se puede llamar fuera de onCreate() y onDestroy() porque el Service a los métodos de ciclo de vida y a los métodos de ciclo de vida de TileService se llama en dos subprocesos asíncronos separados.

El ciclo de vida de TileService contiene los siguientes métodos, que se invocan que el sistema hace cada vez que tu TileService ingresa en una nueva fase del ciclo de vida:

• onTileAdded(): Solo se llama a este método cuando el usuario agrega tu tarjeta por primera vez y si la quita y la vuelve a agregar. Este es el mejor momento para realizar cualquier inicialización única. Sin embargo, esto puede no satisface toda la inicialización necesaria.

  Nota: No se llama a onTileAdded() cada vez que se crea la tarjeta. Para Por ejemplo, no se llama a onTileAdded() cuando se reinicia el dispositivo. encendido si la tarjeta se había agregado y no quitado antes de que se apagado.

• onStartListening() y onStopListening(): Se llama a estos métodos cada vez que tu app actualiza la tarjeta y con frecuencia. El TileService permanece limitada entre onStartListening() y onStopListening(), lo que permite que tu app modifique la tarjeta y envíe actualizaciones.

• onTileRemoved(): Solo se llama a este método si el usuario quita tu tarjeta.

Precaución: Es posible que estas fases no se produzcan de forma consecutiva. onTileAdded() solo puede ser una vez cuando un usuario agrega tu mosaico a su panel de Configuración rápida. Se puede llamar varias veces a onStartListening() y onStopListening(). a lo largo del ciclo de vida de TileService. Nunca se llamará a onTileRemoved() si el usuario no quita tu tarjeta del panel de Configuración rápida.

Selecciona un modo de reproducción

Tu TileService escucha en modo activo o no activo. Recomendaciones con el modo activo, que deberás declarar en el manifiesto de la app. De lo contrario, TileService es el modo estándar y no es necesario declararlo.

No supongas que tu TileService vivirá fuera del par de métodos onStartListening() y onStopListening().

Modo activo (recomendado)

Usa el modo activo para un TileService que escucha y supervisa su estado en el propio proceso. Un TileService en modo activo está vinculado a onTileAdded(), onTileRemoved(), eventos de presión y cuando el proceso de la app lo solicita.

Recomendamos el modo activo si tu TileService recibe una notificación cuando se muestra el estado de la tarjeta debe actualizarse mediante su propio proceso. Las tarjetas activas limitan la carga del sistema, ya que no tienen que vincularse cada vez que el usuario ve el panel de Configuración rápida.

Se puede llamar al método TileService.requestListeningState() estático para solicitar el inicio del estado de escucha y recibir una devolución de llamada para onStartListening()

Para declarar el modo activo, agrega META_DATA_ACTIVE_TILE a tu archivo de manifiesto de tu app.

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

Modo no activo

El modo no activo es el modo estándar. Un TileService está en modo no activo si está vinculado cada vez que el usuario puede ver tu tarjeta. Esto significa que tu TileService se puede crear y volver a vincular en momentos fuera de su control. Integra también puede desvincularse y destruirse cuando el usuario no esté viendo la tarjeta.

Tu app recibe una devolución de llamada a onStartListening() después de que el usuario abre su Panel de Configuración rápida Puedes actualizar tu objeto Tile todas las veces que entre onStartListening() y onStopListening().

Precaución: Si usas el modo no activo en lugar del modo activo, es posible que tu TileService se vincule cada vez que el usuario abra el panel de Configuración rápida.

No es necesario declarar el modo no activo; simplemente, no agregues el META_DATA_ACTIVE_TILE en el archivo de manifiesto de tu app.

Descripción general de los estados de las tarjetas

Después de que un usuario agrega tu tarjeta, siempre existe en uno de los siguientes estados.

• STATE_ACTIVE: Indica un estado activado o habilitado. El usuario puede interactuar con tu tarjeta mientras esté en este estado.

  Por ejemplo, para una tarjeta de app de fitness que permite a los usuarios iniciar un entrenamiento cronometrado STATE_ACTIVE indicaría que el usuario inició un entrenamiento. sesión y el temporizador está en funcionamiento.

• STATE_INACTIVE: Indica un estado apagado o pausado. El usuario puede interactuar con tu tarjeta mientras esté en este estado.

  Para volver a usar el ejemplo de la tarjeta de la app de fitness, una tarjeta en STATE_INACTIVE significaría que el usuario no inició una sesión de entrenamiento, pero podría hacerlo si quisiera.

• STATE_UNAVAILABLE: Indica un estado que no se encuentra disponible temporalmente. El el usuario no puede interactuar con tu mosaico en este estado.

  Por ejemplo, una tarjeta en STATE_UNAVAILABLE significa que, por algún motivo, no está disponible para el usuario en ese momento.

  Precaución: Usa STATE_UNAVAILABLE para las tarjetas que no están disponibles en este momento, pero que podrían estarlo más adelante. Si el componente nunca más estará disponible para el usuario, pasa COMPONENT_ENABLED_STATE_DISABLED a setComponentEnabledSetting().

El sistema solo establece el estado inicial del objeto Tile. Estableces el Tile del objeto durante el resto de su ciclo de vida.

El sistema puede cambiar el tono del ícono y el fondo del mosaico para reflejar el estado de tu Tile. Los objetos Tile establecidos en STATE_ACTIVE son los más oscuros, con STATE_INACTIVE y STATE_UNAVAILABLE son cada vez más claros. El tono exacto es específico del fabricante y la versión.

Figura 4: Ejemplos de una tarjeta teñida para reflejar su estado (activo, inactivo y no disponible, respectivamente).

Actualiza tu tarjeta

Puedes actualizar la tarjeta una vez que recibas una devolución de llamada a onStartListening(). Según el modo de la tarjeta, esta se puede actualizar al menos una vez hasta que reciba una devolución de llamada a onStopListening().

En el modo activo, puedes actualizar tu tarjeta exactamente una vez antes de recibir un devolución de llamada a onStopListening(). En el modo no activo, puedes actualizar la tarjeta tantas veces como quieras entre onStartListening() y onStopListening().

Nota: El modo activo te permite actualizar tu tarjeta independientemente de si está visibles para el usuario o no.

Para recuperar tu objeto Tile, llama a getQsTile(). Para actualizar campos específicos de tu objeto Tile, llama a los siguientes métodos:

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

Nota: El ícono y la etiqueta establecidos en el archivo de manifiesto de tu app son los valores predeterminados que se muestran en la tarjeta del panel de Configuración rápida. Sin embargo, puedes llamar a los métodos setIcon() y setLabel() cuando actualices la tarjeta para establecer los campos en valores nuevos.

Debes llamar a updateTile() para actualizar la tarjeta una vez que termines de configurar la del objeto Tile con los valores correctos. Esto hará que el sistema analice los datos de la tarjeta actualizados y actualice la IU.

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();
}

Cómo controlar los toques

Los usuarios pueden presionar tu tarjeta para activar una acción si esta está en STATE_ACTIVE o STATE_INACTIVE. Luego, el sistema invoca la interfaz Devolución de llamada onClick().

Una vez que tu app recibe una devolución de llamada a onClick(), puede iniciar un diálogo o una actividad, activar el trabajo en segundo plano o cambiar el estado de la tarjeta.

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 un diálogo

showDialog() contrae el panel de Configuración rápida y muestra un diálogo. Usa un diálogo para agregar contexto a tu acción si se requiere una entrada adicional o el consentimiento del usuario.

Nota: isLocked() verifica si se muestra la pantalla de bloqueo del usuario. Cuando isLocked() muestra un valor verdadero, showDialog() no presenta un diálogo visible porque se carga debajo de la pantalla de bloqueo.

Cómo iniciar una actividad

startActivityAndCollapse() inicia una actividad mientras se contrae la panel. Las actividades son útiles si hay información más detallada para mostrar que dentro de un diálogo o si tu acción es altamente interactiva.

Si tu app requiere una interacción significativa del usuario, debe iniciar una actividad solo como último recurso. En su lugar, considera usar un diálogo o un botón de activación.

Si el usuario mantiene presionada una tarjeta, aparece la pantalla App Info. Para anular este comportamiento y, en su lugar, inicia una actividad para configurar preferencias, agrega una <intent-filter> a una de tus actividades con ACTION_QS_TILE_PREFERENCES

A partir de la API 28 de Android, el elemento PendingIntent debe tienen el Intent.FLAG_ACTIVITY_NEW_TASK:

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

De forma alternativa, puedes agregar la marca en el AndroidManifest.xml en la ruta Sección Activity.

Marca tu tarjeta como activable

Te recomendamos que marques la tarjeta para que se pueda activar o desactivar si funciona principalmente como una interruptor de dos estados (que es el comportamiento más común de las tarjetas). Esto ayuda proporcionar información sobre el comportamiento de la tarjeta para el sistema operativo y mejorar la accesibilidad general.

Establece los metadatos de TOGGLEABLE_TILE en true para marcar tu tarjeta como se puede activar o desactivar.

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

Realiza solo acciones seguras en dispositivos bloqueados de forma segura

Tu mosaico puede aparecer en la parte superior de la pantalla de bloqueo en dispositivos bloqueados. Si la tarjeta contiene información sensible, verifica el valor de isSecure() para determinar si el dispositivo está en estado seguro, y tu TileService debería cambiar su comportamiento en consecuencia.

Si es seguro realizar la acción de la tarjeta con el dispositivo bloqueado, usa startActivity(). para iniciar una actividad sobre la pantalla de bloqueo.

Si la acción de la tarjeta no es segura, usa unlockAndRun() para solicitarle al usuario que haga lo siguiente: desbloquear su dispositivo. Si la operación se realiza correctamente, el sistema ejecuta el objeto Runnable que pasas a este método.

Cómo solicitarle al usuario que agregue tu tarjeta

Para agregar tu tarjeta de forma manual, los usuarios deben seguir varios pasos:

1. Desliza el dedo hacia abajo para abrir el panel de Configuración rápida.
2. Presiona el botón Editar.
3. Desplázate por todas las tarjetas de su dispositivo hasta que encuentre la tuya.
4. Mantén presionada la tarjeta y arrástrala a la lista de tarjetas activas.

El usuario también puede mover o quitar tu tarjeta en cualquier momento.

A partir de Android 13, puedes usar el método requestAddTileService() para que a los usuarios les resulte mucho más fácil agregar tu tarjeta a un dispositivo. Este método muestra a los usuarios una solicitud para agregar rápidamente tu tarjeta directamente a su cuenta de Quick Panel de configuración La instrucción incluye el nombre de la aplicación, la etiqueta proporcionada e ícono.

Figura 5: Mensaje de la API de Quick Settings Position

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

La devolución de llamada contiene información sobre si se agregó o no la tarjeta, si ya estaba allí o si se produjo algún error.

Usa tu criterio cuando decidas cuándo y con qué frecuencia solicitarles a los usuarios que realicen una acción. Mié se recomienda llamar a requestAddTileService() solo en contexto, como Cuando el usuario interactúa por primera vez con una función que facilita tu tarjeta.

El sistema puede optar por dejar de procesar solicitudes para un ComponentName si el usuario lo rechazó suficientes veces El usuario se determina a partir del Context que se usa para recuperar este servicio; debe coincidir con el usuario actual.

Nota: Te recomendamos que llames a requestAddTileService() para aumentar la visibilidad de tu tarjeta y reducir la carga para el usuario de agregarla a su panel de Configuración rápida.