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 tareas recurrentes con rapidez.
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 proporcionada por tu app.
Cómo decidir 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 a las que necesiten acceso rápido (o ambas). Las tarjetas más eficaces son las que coinciden con ambas cualidades, lo que proporciona acceso rápido a las acciones realizadas 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 recomendamos crear una tarjeta para la misma app que permitiría a los usuarios revisar todo su historial de entrenamiento.
Para ayudar a mejorar la visibilidad y 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 una app o un selector estándar.
Evita usar tarjetas para las acciones del usuario únicas. En su lugar, usa un acceso directo a 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 aplicación.
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.
Cómo crear 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 aparecerá en el mosaico en el panel de Configuración rápida. (Agregarás este ícono cuando declares el TileService, que se describe en la siguiente sección). El ícono debe ser blanco sólido con un fondo transparente, medir 24 dp × 24 dp y tener la forma de VectorDrawable.
Crea un ícono que sugiera visualmente el propósito de tu 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 para 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 correspondiente.
<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>
Cómo administrar 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 lo solicita tu app o si el sistema necesita comunicarse con ella. Un ciclo de vida de servicios vinculados contiene los siguientes cuatro métodos de devolución de llamada: onCreate(), onBind(), onUnbind() y onDestroy(). El sistema invoca a 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 para el ciclo de vida de TileService. Se puede llamar a estos métodos fuera de onCreate() y onDestroy() porque los métodos del ciclo de vida Service y los métodos del ciclo de vida 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(): Se llama a este método solo cuando el usuario agrega tu tarjeta por primera vez y si la quita y vuelve a agregarla. Este es el mejor momento para realizar cualquier inicialización única. Sin embargo, es posible que esto no cumpla con toda la inicialización necesaria.onStartListening()yonStopListening(): Se llama a estos métodos cada vez que tu app actualiza la tarjeta, y se llaman con frecuencia. ElTileServicepermanece vinculado entreonStartListening()yonStopListening(), lo que permite que tu app modifique la tarjeta y envíe actualizaciones.onTileRemoved(): Se llama a este método solo si el usuario quita la tarjeta.
Selecciona un modo de escucha
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 estará fuera del par de métodos onStartListening() y onStopListening().
Modo activo (recomendado)
Usa el modo activo para un objeto TileService que escucha y supervisa su estado en su propio proceso. Una TileService en el modo activo está vinculada a onTileAdded(), onTileRemoved(), eventos de presión y cuando lo solicita el proceso de la app.
Te recomendamos que uses el modo activo si tu TileService recibe una notificación cuando su propio proceso debería actualizar el estado de la tarjeta. Las tarjetas activas limitan el esfuerzo del 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 TileService.requestListeningState() estático 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. Una TileService está en modo no activo si está vinculada cada vez que tu tarjeta es visible para el usuario. Esto significa que tu TileService puede volver a crearse y vincularse a veces fuera de 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 el onStartListening() y el onStopListening().
No es necesario que declares el modo no activo; simplemente no agregues el META_DATA_ACTIVE_TILE al archivo de manifiesto de tu app.
Descripción general de los estados de los mosaicos
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, en el caso de una tarjeta de app de fitness que permite que los usuarios inicien una sesión de entrenamiento temporizada,
STATE_ACTIVEsignificaría que el usuario inició una sesión de entrenamiento y se está ejecutando el cronómetro.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_INACTIVEsignificaría que el usuario no inició una sesión de entrenamiento, pero podría hacerlo si lo quisiera.STATE_UNAVAILABLE: Indica un estado que no se encuentra disponible temporalmente. El usuario no puede interactuar con tu tarjeta en este estado.Por ejemplo, una tarjeta en
STATE_UNAVAILABLEsignifica que, por algún motivo, no está disponible para el usuario en este momento.
El sistema solo establece el estado inicial del objeto Tile. Estableces el estado del objeto Tile durante el resto de su ciclo de vida.
El sistema puede cambiar el tono del ícono de tarjeta y el fondo para reflejar el estado de tu objeto Tile. Los objetos Tile establecidos 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.
Cómo actualizar tu mosaico
Podrás 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 la 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 desees 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 tu 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 los toques
Los usuarios pueden presionarla para activar una acción si esta 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 reciba una devolución de llamada a onClick(), podrá iniciar un diálogo o una actividad, activar trabajos 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.
Cómo iniciar una actividad
startActivityAndCollapse() inicia una actividad mientras se contrae el panel. Las actividades son útiles si hay información más detallada para mostrar que en un diálogo o si tu acción es muy interactiva.
Si tu app requiere una interacción significativa del usuario, esta 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, iniciar una actividad para configurar preferencias, agrega un <intent-filter> a una de tus actividades con ACTION_QS_TILE_PREFERENCES.
A partir de la 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);
}
De forma alternativa, puedes agregar la marca en AndroidManifest.xml, en la sección Activity específica.
Marca tu tarjeta como seleccionable
Te recomendamos que marques la tarjeta para que se pueda activar o desactivar 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 a 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 tarjeta no es segura, usa unlockAndRun() para solicitarle al usuario que desbloquee su dispositivo. Si se ejecuta de forma correcta, el sistema ejecuta el objeto Runnable que pasas a este método.
Cómo pedirle 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 Editar.
- Desplázate por todas las tarjetas de su dispositivo hasta que encuentren 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 mucha más facilidad. Este método les solicita a los usuarios con una solicitud 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 y el ícono proporcionados.
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 enviar mensajes 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 para una ComponentName determinada si el usuario las rechazó suficientes veces. El usuario se determina a partir del Context que se usa para recuperar este servicio, que debe coincidir con el usuario actual.