Cómo administrar accesos directos

Después de crear accesos directos, es posible que debas administrarlos durante el ciclo de vida de tu app. Por ejemplo, es posible que desees optimizar tu app determinando la frecuencia con la que tus usuarios realizan acciones específicas con tus accesos directos. En otro caso, podrías decidir inhabilitar un acceso directo fijo para evitar que tu app realice acciones desactualizadas o que ya no están disponibles. En el caso de los accesos directos a los que se hace referencia en las conversaciones, es posible que desees hacer un seguimiento del uso para proporcionar indicadores que mejoren la clasificación de los accesos directos.

En esta página, se describen estas y muchas otras formas comunes de administrar tus accesos directos.

Comportamiento de los accesos directos

En las siguientes secciones, se incluye información general sobre el comportamiento de los accesos directos, como la visibilidad, el orden de visualización y las clasificaciones.

Visibilidad de los accesos directos

Los accesos directos estáticos y dinámicos aparecen en un selector o asistente compatibles cuando el usuario realiza un gesto o comando por voz específico. En los selectores admitidos, el gesto implica mantener presionado el ícono de selector de la app, pero puede ser diferente en otras apps de selector. Con Asistente de Google, los accesos directos pueden mostrarse en Asistente o iniciarse desde un comando por voz del usuario.

La clase LauncherApps proporciona APIs para que las apps de selector accedan a accesos directos.

Como los accesos directos fijos aparecen en el selector, siempre son visibles. Solo en las siguientes situaciones se quita un acceso directo fijo del selector:

• El usuario lo quita.
• Se desinstaló la app asociada con el acceso directo.
• El usuario borra los datos de una app en Configuración > Apps y notificaciones seleccionando la app y, luego, presionando Almacenamiento > Liberar espacio de almacenamiento.

Los objetivos de uso compartido son un subconjunto de accesos directos dinámicos que aparecen en la fila de uso compartido directo de la hoja de uso compartido de Android.

Orden de visualización de los accesos directos

Cuando el selector muestra los accesos directos de una app, deben aparecer en el siguiente orden:

1. Atajos estáticos: Son atajos cuyo método isDeclaredInManifest() devuelve true.
2. Accesos directos dinámicos: Son accesos directos cuyo método ShortcutInfo.isDynamic() devuelve true.

Dentro de cada tipo de acceso directo (estático y dinámico), estos se ordenan por clasificación creciente según ShortcutInfo.getRank. Asistente de Google también tiene en cuenta la clasificación de accesos directos a la hora de determinar los accesos directos contextuales para mostrarlos a los usuarios.

Las clasificaciones son números enteros secuenciales no negativos. Los accesos directos estáticos se clasifican del primero al último en el orden en que aparecen en tu archivo shortcuts.xml. En el caso de los accesos directos dinámicos, puedes actualizar las clasificaciones de los accesos directos existentes cuando llamas a updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) o setDynamicShortcuts(Context, List).

El orden de los destinos para compartir se basa en varios factores, como el historial del usuario, la actualidad, la frecuencia, la sugerencia de clasificación, el uso de la app y la prioridad establecida en la conversación asociada con un acceso directo de uso compartido. Los objetivos de uso compartido creados con la API de Sharing Shortcuts tienen prioridad sobre los objetivos de uso compartido que produce ChooserTargetService, que quedó obsoleta en Android 11. En Android 12 y versiones posteriores, los destinos de uso compartido generados por el objeto ChooserTargetService en desuso ya no aparecerán en la hoja de uso compartido.

La mayoría de los selectores muestran un máximo de cuatro accesos directos. Para cualquier combinación de accesos directos estáticos y dinámicos que se definan, el selector muestra un máximo de dos accesos directos estáticos y dos dinámicos. Por ejemplo, si defines cuatro accesos directos estáticos y creas tres accesos directos dinámicos de forma programática, el selector mostrará los dos primeros accesos directos estáticos y los dos accesos directos dinámicos con la clasificación más alta.

Cómo administrar varios intents y actividades

Si deseas que tu app realice varias operaciones cuando el usuario active un acceso directo, puedes configurarlo para que inicie actividades sucesivas. Para ello, asigna varios intents, inicia una actividad desde otra o configura marcas de intents, según el tipo de acceso directo.

Cómo comenzar una actividad desde otra

Los accesos directos estáticos no pueden tener marcas de intents personalizadas. El primer intent de un acceso directo estático siempre tiene configurados Intent.FLAG_ACTIVITY_NEW_TASK y Intent.FLAG_ACTIVITY_CLEAR_TASK. Esto significa que, cuando tu app está en ejecución, se destruyen todas las actividades existentes en la app cuando se inicia un acceso directo estático. Si no quieres este comportamiento, puedes usar una actividad de trampolín, es decir, una actividad invisible que inicia otra actividad, llamando a finish dentro de un bloque de inicio o onCreate antes de que se establezca el contenido de Compose:

1. En el AndroidManifest.xml file, incluye la asignación de atributos android:taskAffinity="" en la actividad de trampolín.

2. En el archivo de recursos de accesos directos, haz referencia a la actividad disparadora en el intent dentro del acceso directo estático.

Para obtener más información sobre las actividades disparadoras, consulta Cómo comenzar una actividad desde otra.

Cómo configurar marcas de intents

Puedes publicar accesos directos dinámicos con cualquier conjunto de marcas Intent. De preferencia, especifica la combinación de Intent.FLAG_ACTIVITY_SINGLE_TOP y Intent.FLAG_ACTIVITY_CLEAR_TOP en el intent del acceso directo. Esto garantiza que, si tu ComponentActivity ya está activo, se lo lleve al primer plano y se lo reutilice sin que se destruya, lo que permite que tu arquitectura de actividad única controle correctamente el evento de acceso directo a través de onNewIntent().

Para obtener más información sobre las tareas y las marcas de intents, consulta Tareas y la pila de actividades.

Cómo actualizar los accesos directos

Cada ícono de selector de la app puede contener, como máximo, una cantidad de accesos directos estáticos y dinámicos combinados que sea igual al valor que devuelve getMaxShortcutCountPerActivity. No hay límite para la cantidad de accesos directos fijos que puede crear una app.

Cuando un acceso directo dinámico está fijo, incluso si el publicador lo quita como acceso directo dinámico, el acceso directo fijo permanece visible y se puede iniciar. Esto permite que una app tenga más de getMaxShortcutCountPerActivity cantidad de accesos directos.

Considera el siguiente ejemplo, que supone que el valor que devuelve getMaxShortcutCountPerActivity es 4:

1. Una app de chat publica cuatro accesos directos dinámicos que representan las cuatro conversaciones más recientes: c1, c2, c3 y c4.
2. El usuario fija los cuatro accesos directos.
3. Más tarde, el usuario inicia tres conversaciones adicionales: c5, c6 y c7. La app del publicador vuelve a publicar sus accesos directos dinámicos. La nueva lista de accesos directos dinámicos es c4, c5, c6 y c7.

La app tiene que quitar c1, c2 y c3 porque no puede mostrar más de cuatro accesos directos dinámicos. Sin embargo, c1, c2 y c3 siguen siendo accesos directos fijos a los que el usuario puede acceder e iniciar.

Luego, el usuario puede acceder a un total de siete accesos directos que vinculan actividades en la app del publicador. Esto se debe a que el total incluye la cantidad máxima de accesos directos y los tres accesos directos fijos.

1. La app puede usar updateShortcuts(Context, List) para actualizar cualquiera de los siete accesos directos existentes. Por ejemplo, puedes actualizar este conjunto de accesos directos cuando cambien los íconos de las apps de chat similares.
2. Puedes usar los métodos addDynamicShortcuts(Context, List) y setDynamicShortcuts(Context, List) para actualizar los accesos directos existentes con los mismos IDs. Sin embargo, no puedes usarlos para actualizar accesos directos fijos no dinámicos, ya que estos dos métodos intentan convertir las listas dadas de accesos directos en accesos directos dinámicos.

No hay límite para la cantidad de accesos directos que se pueden enviar para mostrarlos en apps de asistentes, como Asistente de Google. Usa el método pushDynamicShortcut de la biblioteca de ShortcutManagerCompat Jetpack para crear y actualizar accesos directos para usarlos en apps de asistentes. Además, agrega la biblioteca de integración de atajos de Google a tu app para que los vínculos dinámicos sean aptos para aparecer en Asistente de Google.

Si deseas obtener más información sobre los lineamientos para los accesos directos a aplicaciones, incluida su actualización, consulta Prácticas recomendadas para los accesos directos.

Cómo procesar los cambios de la configuración regional del sistema

Las apps deben actualizar los accesos directos dinámicos y fijos cuando reciben la transmisión Intent.ACTION_LOCALE_CHANGED que indica un cambio en la configuración regional del sistema.

Cómo hacer un seguimiento del uso de los accesos directos

Para determinar las situaciones en las que aparecen los accesos directos estáticos y dinámicos, el selector examina su historial de activación. En el caso de los accesos directos estáticos, puedes realizar un seguimiento de cuándo los usuarios completan acciones específicas en tu app llamando al método reportShortcutUsed y pasándole el ID de un acceso directo cuando ocurra alguno de los siguientes eventos:

• El usuario selecciona el acceso directo con el ID específico.
• En la app, el usuario completa manualmente la acción correspondiente al mismo acceso directo.

Tu app hace un seguimiento del uso de accesos directos dinámicos llamando al método pushDynamicShortcut y pasándole el ID del acceso directo cuando se produce un evento relevante. Enviar el uso dinámico de accesos directos con este método permite que las apps de asistentes, como Asistente de Google, sugieran accesos directos relevantes a los usuarios. Debido a que el método pushDynamicShortcut informa el uso cuando se lo llama, no debes llamar al método reportShortcutUsed para los mismos accesos directos.

En el caso de los accesos directos relacionados con conversaciones, es importante hacer un seguimiento del uso de los mensajes entrantes y salientes. Para obtener más detalles, consulta las prácticas recomendadas para personas y conversaciones.

Cómo inhabilitar accesos directos

Dado que tu app y los usuarios pueden fijar accesos directos al selector del dispositivo, es posible que estos accesos directos fijos dirijan a los usuarios a acciones dentro de la app que están desactualizadas o ya no existen. Para administrar esta situación, puedes inhabilitar los accesos directos que no deseas que los usuarios seleccionen llamando a disableShortcuts, que quita los accesos directos especificados de la lista de accesos directos estáticos y dinámicos, además de inhabilitar las copias fijas de estos accesos directos. También puedes usar una versión sobrecargada de este método que acepte un CharSequence como mensaje de error personalizado. Ese mensaje de error aparece cuando los usuarios intentan iniciar cualquier acceso directo inhabilitado.

Límite de frecuencia

Cuando uses los métodos setDynamicShortcuts, addDynamicShortcuts o updateShortcuts, es posible que solo puedas llamarlos una cantidad específica de veces en una app en segundo plano, es decir, una app sin actividades ni servicios en primer plano. El límite de la cantidad específica de veces que puedes llamar a estos métodos se denomina límite de frecuencia. Esta función evita que ShortcutManagerCompat consuma recursos del dispositivo en exceso.

Cuando el límite de frecuencia está activo, isRateLimitingActive devuelve verdadero. Sin embargo, el límite de frecuencia se restablece durante ciertos eventos, por lo que incluso las apps en segundo plano pueden llamar a los métodos ShortcutManager hasta que se vuelva a alcanzar el límite de frecuencia. Estos eventos incluyen lo siguiente:

• Una app pasa al primer plano.
• Se cambia la configuración regional del sistema.
• El usuario realiza la acción de respuesta intercalada en una notificación.

Si encuentras un límite de frecuencia durante el desarrollo o las pruebas, puedes seleccionar Opciones para desarrolladores > Restablecer la limitación de frecuencia de ShortcutManager en la configuración del dispositivo o puedes ingresar el siguiente comando en adb:

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

Copia de seguridad y restablecimiento

Para permitir que los usuarios realicen operaciones de copia de seguridad y restablecimiento en tu app cuando cambien de dispositivo, puedes incluir la asignación del atributo android:allowBackup="true" en el archivo de manifiesto de tu app. Si admites la copia de seguridad y el restablecimiento, ten en cuenta los siguientes puntos sobre los accesos directos a aplicaciones:

• Los accesos directos estáticos se vuelven a publicar automáticamente, pero solo después de que el usuario vuelve a instalar la app en un dispositivo nuevo.
• Los accesos directos dinámicos no tienen copia de seguridad, por lo que debes incluir la lógica en tu app para volver a publicarlos cuando un usuario la abra en un dispositivo nuevo.
• Los accesos directos fijos se restablecen automáticamente en el selector del dispositivo, pero el sistema no crea una copia de seguridad de los íconos asociados con los accesos directos fijos. Por lo tanto, guarda las imágenes de los accesos directos fijos en tu app para que sea rápido restablecerlos en un dispositivo nuevo.

En el siguiente fragmento de código, se muestra la mejor manera de restablecer los accesos directos dinámicos de tu app y cómo comprobar si se conservaron sus accesos directos fijos:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}