Cómo administrar accesos directos

Después de crear atajos, es posible que debas administrarlos durante el ciclo de vida de tu app. Por ejemplo, para optimizar tu app, determina la frecuencia con la que los usuarios completan acciones específicas con tus atajos. En otro caso, puedes inhabilitar un atajo fijo para evitar que tu app realice acciones desactualizadas o faltantes. En el caso de los atajos a los que se hace referencia en las conversaciones, te recomendamos que hagas un seguimiento del uso para proporcionar indicadores que mejoren su clasificación.

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

Comportamiento de los accesos directos

Las siguientes secciones contienen 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 atajos estáticos y dinámicos aparecen en un selector o asistente compatible cuando el usuario realiza un gesto o un comando por voz específicos. En los selectores compatibles, 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, las combinaciones de teclas se pueden mostrar en Asistente o iniciarse desde un comando por voz del usuario.

La clase LauncherApps proporciona APIs para que las apps de selector accedan a los 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.
  • Para borrar los datos de una app, el usuario debe ir a Configuración > Apps y notificaciones, seleccionar la app y, luego, presionar 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.

Captura de pantalla de Android Sharesheet
Figura 1: Android Sharesheet Los objetivos de uso compartido directo aparecen en la primera fila, seguidos de las apps clasificadas y, luego, las listas de apps.

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. Accesos directos estáticos: Combinaciones de teclas cuyo método isDeclaredInManifest() muestra true.
  2. Accesos directos dinámicos: Son aquellos cuyo método ShortcutInfo.isDynamic() muestra true.

Dentro de cada tipo de combinación de teclas (estática y dinámica), estas se ordenan en función de la clasificación creciente según ShortcutInfo.getRank. Asistente de Google también tiene en cuenta la clasificación de atajos a la hora de determinar los atajos contextuales que se mostrarán 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 objetivos de uso compartido se basa en varios factores, como el historial del usuario anterior, las visitas recientes, la frecuencia, la sugerencia de rango, 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 accesos directos de uso compartido tienen prioridad sobre los objetivos de uso compartido que produce ChooserTargetService, que dejó de estar disponible en Android 11. En Android 12 y versiones posteriores, los objetivos de uso compartido generados por el ChooserTargetService obsoleto ya no aparecerán en la hoja para compartir.

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 accesos directos dinámicos. Por ejemplo, si defines cuatro accesos directos estáticos y creas de forma programática tres accesos directos dinámicos, el selector mostrará los dos primeros accesos directos estáticos y los dos accesos directos dinámicos mejor clasificados.

Cómo administrar varios intents y actividades

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

Cómo asignar varios intents

Cuando creas un acceso directo con ShortcutInfoCompat.Builder, puedes usar setIntents() en lugar de setIntent(). Si llamas a setIntents(), puedes iniciar varias actividades dentro de tu app cuando el usuario selecciona un acceso directo y coloca todas las actividades de la lista en la pila de actividades, excepto la última. Si el usuario presiona el botón Atrás del dispositivo, verá otra actividad en tu app en lugar de regresar al selector del dispositivo.

Cómo comenzar una actividad desde otra

Los accesos directos estáticos no pueden tener marcas de intents personalizados. El primer intent de un acceso directo estático siempre tiene Intent.FLAG_ACTIVITY_NEW_TASK y Intent.FLAG_ACTIVITY_CLEAR_TASK configurados. Esto significa que, cuando se ejecuta tu app, se destruyen todas las actividades existentes en ella cuando se inicia un acceso directo estático. Si no deseas este comportamiento, puedes usar una actividad disparadora (una actividad invisible que inicia otra actividad) en Activity.onCreate(Bundle) que llame a Activity.finish():

  1. En el archivo AndroidManifest.xml, incluye la asignación de atributo android:taskAffinity="" en la actividad disparadora.
  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 iniciar una actividad desde otra.

Cómo configurar marcas de intents

Puedes publicar accesos directos dinámicos con cualquier conjunto de marcas Intent. Preferentemente, especifica Intent.FLAG_ACTIVITY_CLEAR_TASK junto con tus otras marcas. De lo contrario, si intentas iniciar otra tarea mientras tu app está en ejecución, es posible que la actividad objetivo no aparezca.

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 combinada de accesos directos estáticos y dinámicos igual al valor que muestra getMaxShortcutCountPerActivity. No hay un límite para la cantidad de accesos directos fijos que puede crear una app.

Cuando se fija un acceso directo dinámico, incluso si el publicador lo quita como atajo 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, en el que se supone que el valor que muestra 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 atajos 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, ya que 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 a 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 combinaciones de teclas cuando cambien los íconos de apps similares de chat.
  2. Puedes usar los métodos addDynamicShortcuts(Context, List) y setDynamicShortcuts(Context, List) para actualizar los accesos directos existentes con los mismos ID. Sin embargo, no puedes usarlos para actualizar atajos no dinámicos fijos, ya que estos dos métodos intentan convertir las listas proporcionadas de accesos directos en atajos dinámicos.

No hay un límite para la cantidad de combinaciones de teclas que se pueden enviar para que se muestren en las apps del asistente, como Asistente de Google. Usa el método pushDynamicShortcut() de la biblioteca ShortcutManagerCompat de Jetpack para crear y actualizar atajos que se pueden usar en apps de Asistente. Además, agrega la biblioteca de integración de atajos de Google a tu app a fin de que los vínculos dinámicos sean aptos para aparecer en Asistente de Google.

Para obtener más información sobre los lineamientos de los accesos directos a aplicaciones, incluida su actualización, consulta Prácticas recomendadas para 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 el historial de activación de los accesos directos. En el caso de los atajos estáticos, puedes hacer un seguimiento de cuándo los usuarios completan acciones específicas en tu app. Para ello, llama al método reportShortcutUsed() y pásale el ID de un acceso directo cuando ocurra cualquiera de los siguientes eventos:

  • El usuario selecciona el acceso directo con el ID específico.
  • Dentro de la app, el usuario completa de forma manual la acción correspondiente al mismo atajo.

Para hacer un seguimiento del uso de atajos dinámicos, tu app llama al método pushDynamicShortcut() y pásale el ID del atajo cuando se produzca un evento relevante. Enviar el uso dinámico de atajos con este método permite que las apps de asistente, como Asistente de Google, sugieran atajos relevantes a los usuarios. Debido a que el método pushDynamicShortcut() informa el uso cuando se lo llama, no llames al método reportShortcutUsed() para los mismos atajos.

En el caso de las combinaciones de teclas relacionadas con las conversaciones, es importante hacer un seguimiento del uso de los mensajes salientes y entrantes. Si deseas obtener más detalles, consulta las prácticas recomendadas para las personas y las conversaciones.

Cómo inhabilitar accesos directos

Debido a que tu app y sus usuarios pueden fijar accesos directos al selector del dispositivo, es posible que estos accesos directos fijos puedan dirigir 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, y también inhabilita 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 llamar a estos métodos 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 sobre 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() muestra el valor 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. Entre estos eventos, se incluyen los siguientes:

  • Una app pasa al primer plano.
  • Se cambia la configuración regional del sistema.
  • El usuario realiza la acción de respuesta en línea 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 your-user-id ]

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, incluye la asignación del atributo android:allowBackup="true" en el archivo de manifiesto de tu app. Si admites copias de seguridad y restablecimientos, 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 tu 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 fácil restablecerlas 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 verificar si se conservaron los accesos directos fijos:

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}