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 la app determinando la frecuencia con la que tus usuarios realizan acciones específicas con los 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 esta guía, se describen estas y muchas otras maneras 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

Nota de seguridad importante: Toda la información de los accesos directos se guarda en almacenamiento encriptado con credenciales, por lo que tu app no podrá acceder a los accesos directos del usuario hasta que este haya desbloqueado el dispositivo.

Los accesos directos estáticos y dinámicos aparecen en un selector o asistente compatibles cuando el usuario realiza gestos o comandos por voz específicos. 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 API 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 una app y luego presionando Almacenamiento > Liberar espacio de almacenamiento.

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: su método isDeclaredInManifest() muestra true.
  2. Accesos directos dinámicos: su método ShortcutInfo.isDynamic() muestra true.

Dentro de cada tipo de acceso directo (estático y dinámico), estos se clasifican en orden ascendente 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. Puedes actualizar las clasificaciones de los accesos directos existentes cuando llamas a updateShortcuts(Context, List), addDynamicShortcuts(Context, List) o setDynamicShortcuts(Context, List).

Nota: Las clasificaciones se ajustan automáticamente, por lo que son únicas para cada tipo de acceso directo (estático o dinámico). Por ejemplo, si hay tres accesos directos dinámicos con las clasificaciones 0, 1 y 2, agregar otro acceso directo dinámico con una clasificación de 1 representa una solicitud para ubicar este acceso directo en la segunda posición. En respuesta, los accesos directos en tercera y cuarta posición se acercan a la parte inferior de la lista, y sus clasificaciones cambian a 2 y 3, respectivamente.

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 a partir de otra o configura marcas de intents, según el tipo de acceso directo.

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. Para ello, debes colocar todas las actividades de la lista, excepto la última, en la pila de actividades. Si el usuario decide presionar el botón Atrás del dispositivo, verá otra actividad en tu app en lugar de regresar al selector del dispositivo.

Nota: Cuando el usuario selecciona un acceso directo y, luego, presiona la tecla Atrás, la app iniciará la actividad correspondiente con el penúltimo intent del acceso directo que se incluye en el archivo de recursos. Este patrón de comportamiento continúa cuando se presiona repetidamente el botón Atrás, hasta que el usuario borre la pila de actividades que creó un acceso directo. Cuando el usuario vuelve a presionar el botón Atrás, el sistema lo dirige nuevamente al selector.

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 tendrá Intent.FLAG_ACTIVITY_NEW_TASK y Intent.FLAG_ACTIVITY_CLEAR_TASK configurados. Esto significa que, cuando la app está en ejecución, se destruyen todas las actividades existentes en tu app cuando se inicia un acceso directo estático. Si este comportamiento no es lo que deseas, puedes usar una actividad disparadora o una actividad invisible que comience otra actividad en Activity.onCreate(Bundle) y luego llame a Activity.finish():

  1. En el archivo AndroidManifest.xml, la actividad disparadora debe incluir la asignación de atributos android:taskAffinity="".
  2. En el archivo de recursos de accesos directos, el intent dentro del acceso directo estático debe hacer referencia a la actividad disparadora.

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

Cómo configurar marcas de intents

Los accesos directos dinámicos se pueden publicar con cualquier conjunto de marcas Intent. Preferentemente, especificarás 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 acerca de las tareas y las marcas de intents, consulta la guía Tareas y pilas de actividades.

Cómo actualizar los accesos directos

Cada ícono de selector de las apps puede contener como máximo la cantidad getMaxShortcutCountPerActivity() de accesos directos estáticos y dinámicos combinados. Sin embargo, no hay un 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 de los accesos directos dinámicos, el acceso directo fijo permanecerá visible y se podrá iniciar. Esto permite que una app tenga más de la cantidad getMaxShortcutCountPerActivity() de accesos directos.

Como ejemplo, supongamos que getMaxShortcutCountPerActivity() es cuatro:

  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), por lo que 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.

    Ahora, el usuario puede acceder a un total de siete accesos directos vinculados 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.

  4. 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 los íconos de apps de chat similares hayan cambiado.
  5. También se pueden usar los métodos addDynamicShortcuts(Context, List) y setDynamicShortcuts(Context, List) para actualizar los accesos directos existentes con los mismos ID. Sin embargo, no se pueden usar para actualizar accesos directos fijos no dinámicos porque 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 de Jetpack a fin de crear y actualizar accesos directos para usarlos en apps de asistentes. Además, debes agregar la Biblioteca de integración de accesos directos de Google a tu app a fin de que los vínculos dinámicos sean aptos para aparecer en Asistente de Google.

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

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 que se cambió la configuración regional del sistema.

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

Para determinar las situaciones en las que deben aparecer 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 en 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 de eventos 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.

Nota: Se requiere la Biblioteca de integración de accesos directos de Google para habilitar los vínculos dinámicos que tu app envía a fin de que se puedan mostrar en las plataformas de Google, como Asistente de Google Si agregas esta biblioteca a tu app, permitirás que Asistente transfiera tus vínculos dinámicos y se los sugiera a los usuarios desde la app de Asistente.

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 sus copias fijas. También puedes usar una versión sobrecargada de este método, que acepta un objeto CharSequence como mensaje de error personalizado. Ese mensaje de error aparece cuando los usuarios tratan de iniciar cualquier acceso directo inhabilitado.

Nota: Si quitas algunos de los accesos directos estáticos de tu app cuando la actualizas, el sistema los inhabilita automáticamente.

Límite de frecuencia

Cuando uses los métodos setDynamicShortcuts(), addDynamicShortcuts() o updateShortcuts(), ten en cuenta que quizás 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 se usa para evitar que ShortcutManagerCompat consuma recursos del dispositivo en exceso.

Cuando el límite de frecuencia está activo, isRateLimitingActive() muestra un valor verdadero. Sin embargo, el límite de frecuencia se restablece durante determinados eventos, en los 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 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, puedes incluir la asignación del atributo android:allowBackup="true" en el archivo de manifiesto de tu app. Si habilitas la copia de seguridad y el restablecimiento, ten en cuenta los siguientes puntos sobre 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 abre 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, debes guardar las imágenes de los accesos directos fijos en tu app para que sea fácil 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 una app y cómo comprobar 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. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts have been 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. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}

Recursos adicionales

En el ejemplo de Android AppShortcuts, hay más detalles sobre el uso de los flujos de trabajo que se cubren en esta página.