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.
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 les 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 las siguientes 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 acciones únicas del usuario. En su lugar, usa un atajo de la app o una notificación.
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, crear y declarar tu TileService
en el archivo de manifiesto de tu app.
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
.
Crea un ícono que insinúe visualmente el propósito de la tarjeta. Esto ayuda a los usuarios a identificar fácilmente si tu tarjeta 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.
Crea y declara 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
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
. Se puede llamar a estos métodos fuera de onCreate()
y onDestroy()
porque los métodos de ciclo de vida de Service
y los métodos de ciclo de vida de TileService
se llaman en dos subprocesos asíncronos separados.
El ciclo de vida de TileService
contiene los siguientes métodos, que el sistema invoca cada vez que tu TileService
entra 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, es posible que esto no satisfaga toda la inicialización necesaria.onStartListening()
yonStopListening()
: Se llama a estos métodos cada vez que tu app actualiza la tarjeta y con frecuencia. ElTileService
permanece vinculado entreonStartListening()
yonStopListening()
, 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 reproducción
Tu TileService
escucha en modo activo o no activo. Te recomendamos que uses 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 escuche y supervise su estado en su 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 se notifica a tu TileService
cuando el estado de la tarjeta debe actualizarse con 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 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 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. También puede estar sin vincular 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
tantas veces como quieras entre onStartListening()
y onStopListening()
.
No es necesario que declares el modo no activo; simplemente, 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 está 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 ejecución.STATE_INACTIVE
: Indica un estado de 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 de no disponibilidad temporal. 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 ese 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 teñir el ícono y el fondo de la tarjeta para reflejar el estado de tu objeto Tile
. Los objetos Tile
configurados en STATE_ACTIVE
son los más oscuros, con STATE_INACTIVE
y STATE_UNAVAILABLE
cada vez más claros. El tono exacto es específico del fabricante y la versión.
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 una devolución de llamada a onStopListening()
. En el modo no activo, puedes actualizar la tarjeta tantas veces como quieras entre onStartListening()
y onStopListening()
.
Para recuperar tu objeto Tile
, llama a getQsTile()
. Para actualizar
campos específicos de tu objeto Tile
, llama a los siguientes métodos:
Debes llamar a updateTile()
para actualizar la tarjeta una vez que hayas terminado de configurar los campos 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 las presiones
Los usuarios pueden tocar tu tarjeta para activar una acción si está 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 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(); }
Cómo 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 requiere entradas adicionales 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 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 presionas una tarjeta durante un tiempo prolongado, se le mostrará al usuario la pantalla Información de la app. 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, PendingIntent
debe tener Intent.FLAG_ACTIVITY_NEW_TASK
:
if (Build.VERSION.SDK_INT >= 28) {
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}
Como alternativa, puedes agregar la marca en AndroidManifest.xml
en la sección Activity
específica.
Marca tu tarjeta como activable
Te recomendamos que marques la tarjeta como activada o desactivada si funciona principalmente como un interruptor de dos estados (que es el comportamiento más común de las tarjetas). Esto ayuda a proporcionar información sobre el comportamiento de la tarjeta al sistema operativo y mejorar la accesibilidad general.
Establece los metadatos TOGGLEABLE_TILE
en true
para marcar la tarjeta como activada o desactivada.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
Realiza solo acciones seguras en dispositivos bloqueados de forma segura
Es posible que la tarjeta se muestre 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 un estado seguro, y tu TileService
debería cambiar su comportamiento según corresponda.
Si la acción de la tarjeta es segura para realizar 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 solicitarle al usuario que desbloquee 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:
- Desliza el dedo hacia abajo para abrir el panel de Configuración rápida.
- Presiona el botón de edición.
- Desplázate por todas las tarjetas de su dispositivo hasta que encuentre la tuya.
- 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 mayor facilidad. Con este método, se les solicita a los usuarios que agreguen rápidamente tu tarjeta directamente a su panel de Configuración rápida. La instrucción 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 cuando decidas cuándo y con qué frecuencia solicitarles a los usuarios que realicen una acción. Te recomendamos que llames a requestAddTileService()
solo en contexto, por ejemplo, cuando el usuario interactúa por primera vez con una función que facilita tu tarjeta.
El sistema puede dejar de procesar solicitudes para un ComponentName
determinado si el usuario las denegó varias veces. El usuario se determina a partir del Context
que se usa para recuperar este servicio; debe coincidir con el usuario actual.