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, 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, puedes crear una tarjeta que permita a los usuarios activar o desactivar una VPN que proporcione tu app.

Decide cuándo crear una tarjeta

Te recomendamos que crees tarjetas para funciones específicas a las que esperas que los usuarios accedan con frecuencia o que necesiten acceder con rapidez (o ambas). Las tarjetas más eficaces son las que cumplen con estas dos cualidades, ya que proporcionan acceso rápido a las acciones que se realizan con frecuencia.

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

Para mejorar la visibilidad y la facilidad de uso de tu tarjeta, te recomendamos que evites ciertas prácticas:

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

• Evita usar tarjetas para acciones de usuario únicas. En su lugar, usa un acceso directo de la app o una notificación.

• Evita crear demasiadas tarjetas. Recomendamos un máximo de dos por app. En su lugar, usa un acceso directo a 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, crear y declarar tu TileService en el archivo de manifiesto de tu app.

En la muestra de Configuración rápida, se 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.

Crea un ícono que sugiera visualmente el propósito de tu tarjeta. Esto ayuda a los usuarios a identificar si tu tarjeta se adapta 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.

Crea y declara tu TileService

Crea un servicio para tu tarjeta que extienda la clase TileService.

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()
    }
}
QuickSettingsTilesSnippets.kt

Declara tu TileService en el archivo de manifiesto de tu app. Agrega el nombre y la etiqueta de tu TileService (hasta 18 caracteres para android:label), el ícono personalizado que creaste en la sección anterior y el permiso adecuado.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     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 la app, debes administrar su estado.

TileService es un servicio vinculado. Tu TileService se vincula cuando tu app lo solicita o si el sistema necesita comunicarse con él. 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.

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. Es posible que se llame a estos métodos fuera de onCreate() y onDestroy(), ya que los métodos de ciclo de vida de Service y los de TileService se llaman en dos subprocesos asíncronos independientes.

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

• onTileAdded(): Se llama a este método solo 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, es posible que esto no satisfaga toda la inicialización necesaria.

• onStartListening() y onStopListening(): Se llama a estos métodos cada vez que tu app actualiza la tarjeta, y se los llama con frecuencia. TileService permanece vinculado 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.

Selecciona un modo de escucha

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

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

Modo activo (recomendado)

Usa el modo activo para un TileService que escuche y supervise su estado en su propio proceso. Un TileService en modo activo se vincula a onTileAdded(), onTileRemoved(), eventos de presión y cuando lo solicita el proceso de la app.

Te recomendamos el modo activo si se notifica a tu TileService cuando el estado de la tarjeta se debe actualizar con su propio proceso. Las tarjetas activas limitan la carga en el sistema porque no tienen que vincularse cada vez que el panel de Configuración rápida se vuelve visible para el usuario.

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

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

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

Modo inactivo

El modo no activo es el modo estándar. Un TileService está en modo no activo si se vincula cada vez que la tarjeta es visible para el usuario. Esto significa que tu TileService se puede crear y vincular de nuevo en momentos que escapan a su control. También se puede desvincular y destruir 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 el panel de Configuración rápida. Puedes actualizar tu objeto Tile todas las veces que quieras entre onStartListening() y onStopListening().

No es necesario que declares el modo no activo: no agregues el elemento META_DATA_ACTIVE_TILE al archivo de manifiesto de tu app.

Descripción general de los estados de las tarjetas

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

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

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

• STATE_INACTIVE: Indica un estado de desactivación o pausa. El usuario puede interactuar con tu tarjeta mientras se encuentra 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 no disponible temporalmente. El usuario no puede interactuar con tu tarjeta mientras se encuentra en este estado.

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

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

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

Actualiza tu tarjeta

Puedes actualizar tu 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 una devolución de llamada a onStopListening(). En el modo no activo, puedes actualizar tu tarjeta tantas veces como quieras entre las onStartListening() y las onStopListening().

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

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

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

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 = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}
QuickSettingsTilesSnippets.kt

Cómo controlar los toques

Los usuarios pueden presionar tu tarjeta para activar una acción si esta se encuentra en STATE_ACTIVE o STATE_INACTIVE. Luego, el sistema invoca la devolución de llamada onClick() de tu app.

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 tu tarjeta.

var counter = 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()
}
QuickSettingsTilesSnippets.kt

Inicia 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 requiere una entrada adicional o el consentimiento del usuario.

Cómo iniciar una actividad

startActivityAndCollapse() inicia una actividad mientras contrae el panel. Las actividades son útiles si hay información más detallada para mostrar que la que se incluye en un diálogo o si tu acción es muy 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 se mantiene presionada una tarjeta, se muestra la pantalla Información de la app para el usuario. Para anular este comportamiento y, en su lugar, iniciar una actividad para establecer preferencias, agrega un <intent-filter> a una de tus actividades con ACTION_QS_TILE_PREFERENCES.

A partir del nivel de API 28 de Android, el PendingIntent debe tener el Intent.FLAG_ACTIVITY_NEW_TASK:

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

Como alternativa, puedes agregar la marca en el AndroidManifest.xml en la sección Activity específica.

Cómo marcar tu tarjeta como activable o desactivable

Te recomendamos que marques tu mosaico como activable o desactivable si funciona principalmente como un interruptor de dos estados (que es el comportamiento más común de los mosaicos). Esto ayuda a proporcionar información sobre el comportamiento de la tarjeta al sistema operativo y a mejorar la accesibilidad general.

Establece los metadatos de TOGGLEABLE_TILE en true para marcar la tarjeta como activable o desactivable.

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

Realizar solo acciones seguras en dispositivos bloqueados de forma segura

Es posible que tu mosaico se muestre sobre la pantalla de bloqueo en los dispositivos bloqueados. Si la tarjeta contiene información sensible, verifica el valor de isSecure() para determinar si el dispositivo se encuentra en un estado seguro, y tu TileService debería cambiar su comportamiento según corresponda.

Si es seguro realizar la acción de la tarjeta mientras el dispositivo está 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 pedirle al usuario que desbloquee el dispositivo. Si se ejecuta correctamente, el sistema ejecuta el objeto Runnable que pasas a este método.

Categoriza tu tarjeta

Para mejorar la experiencia del usuario en la Configuración rápida, puedes categorizar tu tarjeta. El sistema organiza las tarjetas en categorías, como Conectividad, Pantalla y Privacidad. El sistema usa estas categorías para ordenar y agrupar las tarjetas en el modo de edición de la Configuración rápida, lo que facilita que los usuarios las encuentren y administren.

Implementación

Para especificar una categoría para tu TileService, agrega un campo de metadatos a la declaración del servicio en el archivo AndroidManifest.xml:

• En tu AndroidManifest.xml, dentro del elemento <service> para tu TileService, agrega un elemento <meta-data>.
• android:name: Configura este valor en android.service.quicksettings.TILE_CATEGORY.
• android:value: Asigna una de las constantes de categoría predefinidas, como android.service.quicksettings.CATEGORY_CONNECTIVITY o android.service.quicksettings.CATEGORY_DISPLAY.

Como se muestra en el siguiente ejemplo:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

La API proporciona un conjunto de categorías predefinidas para elegir. Estas categorías se definen como constantes de cadena dentro de la clase TileService.

Si no se especifica una categoría, el sistema asigna automáticamente una categoría predeterminada:

• De apps del sistema: Para las tarjetas que forman parte de una aplicación del sistema.
• De las apps que instalaste: Para las tarjetas de las aplicaciones instaladas por el usuario.

Si bien los dispositivos Google Pixel usan categorías en la Configuración rápida, los OEM pueden usar o ignorar esta información de categoría en sus respectivas IU del sistema.

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 del dispositivo hasta que encuentres 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 los usuarios puedan agregar tu tarjeta a un dispositivo con mucha más facilidad. Este método muestra a los usuarios una solicitud para agregar rápidamente tu tarjeta directamente a su panel de Configuración rápida. El mensaje incluye el nombre de la aplicación, la etiqueta proporcionada y el ícono.

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 para decidir cuándo y con qué frecuencia se debe mostrar el mensaje a los usuarios. Te recomendamos que llames 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 de un ComponentName determinado si el usuario lo rechazó suficientes veces antes. El usuario se determina a partir del Context que se usa para recuperar este servicio: debe coincidir con el usuario actual.