Cómo crear accesos directos

Los accesos directos entregan tipos específicos de contenido a tus usuarios ayudándolos a acceder rápidamente a distintas partes de tu app.

Cómo entregas contenido con accesos directos depende de tu caso de uso y de si el contexto del acceso directo es controlado por la app o por el usuario. Aunque el contexto de un acceso directo estático no cambie y el contexto de un acceso directo dinámico cambie constantemente, en ambos casos, tu app controla el contexto. El usuario define el contexto en los casos en los que desea elegir cómo quiere que tu app le entregue contenido, como con un acceso directo fijo. En las siguientes situaciones, se demuestran algunos casos de uso para cada tipo de acceso directo:

• Los accesos directos estáticos son mejores para las apps que se vinculan al contenido usando una estructura coherente desde el principio de la interacción del usuario con la app. Como la mayoría de los selectores solo pueden mostrar cuatro accesos directos a la vez, los accesos directos estáticos son útiles para las actividades frecuentes. Por ejemplo, si el usuario desea ver su calendario o correo electrónico de una manera específica, el uso de un acceso directo estático garantiza que su experiencia en la realización de una tarea de rutina sea coherente.
• Los accesos directos dinámicos se usan para acciones en apps sensibles al contexto. Por ejemplo, si creas un juego que le permite al usuario comenzar desde su nivel actual al iniciar la app, el acceso directo deberá actualizarse con frecuencia. El uso de un acceso directo dinámico permite que el acceso directo se actualice cada vez que el usuario pasa de nivel.
• Los accesos directos fijos se usan para acciones específicas controladas por el usuario. Por ejemplo, un usuario puede querer fijar un sitio web específico al selector. Esto es beneficioso porque permite que el usuario realice una acción personalizada, como navegar al sitio web en un solo paso, más rápido que si usara una instancia predeterminada de un navegador.

Cómo crear accesos directos estáticos

Los accesos directos estáticos proporcionan vínculos a acciones genéricas en tu app, y estas acciones deben ser coherentes durante la vigencia de la versión actual de la app. Los buenos candidatos para accesos directos estáticos incluyen visualizar mensajes enviados, establecer alarmas y mostrar la actividad de ejercicio de un usuario para el día.

Para crear un acceso directo estático, completa la siguiente secuencia de pasos:

1. En el archivo de manifiesto de tu app (AndroidManifest.xml), busca una actividad cuyos filtros de intents estén configurados en la acción android.intent.action.MAIN y la categoría android.intent.category.LAUNCHER.

2. Agrega un elemento <meta-data> a esta actividad que haga referencia al archivo de recursos donde se definen los accesos directos de la app:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" /> 
       </activity>
     </application>
   </manifest>
   

3. Crea un nuevo archivo de recursos: res/xml/shortcuts.xml.

4. En este nuevo archivo de recursos, agrega un elemento raíz <shortcuts>, que contiene una lista de elementos <shortcut>. Cada elemento <shortcut> contiene información sobre un acceso directo estático, como su ícono, sus etiquetas de descripción y los intents que inicia dentro de la app:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.ComposeActivity" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
   

Cómo personalizar valores de atributos

En la siguiente lista, se incluyen descripciones de los diferentes atributos dentro de un acceso directo estático. Debes proporcionar un valor para android:shortcutId y android:shortcutShortLabel. Todos los demás valores son opcionales.

android:shortcutId

Este es un literal de string, que representa el acceso directo cuando un objeto ShortcutManager realiza operaciones en él.

Nota: No puedes configurar el valor de este atributo en una string de recursos, como @string/foo.

android:shortcutShortLabel

Esta es una frase concisa que describe el propósito del acceso directo. Cuando sea posible, limita la longitud de la "descripción breve" de un acceso directo a 10 caracteres.

Para obtener más detalles, consulta la información de setShortLabel().

Nota: El valor de este atributo debe ser una string de recursos, como @string/shortcut_short_label.

android:shortcutLongLabel

Este es una frase extendida que describe el propósito del acceso directo. Si hay suficiente espacio, el selector muestra este valor en lugar de android:shortcutShortLabel. Cuando sea posible, limita la longitud de la "descripción larga" del acceso directo a 25 caracteres.

Para obtener más detalles, consulta la información de setLongLabel().

Nota: El valor de este atributo debe ser una string de recursos, como @string/shortcut_long_label.

android:shortcutDisabledMessage

Este es el mensaje que aparece en un selector compatible cuando el usuario intenta iniciar un acceso directo inhabilitado. El mensaje debe explicar al usuario por qué el acceso directo ahora está inhabilitado. El valor de este atributo no tiene efecto si android:enabled es true.

Nota: El valor de este atributo debe ser una string de recursos, como @string/shortcut_disabled_message.

android:enabled

Determina si el usuario puede interactuar con el acceso directo desde un selector compatible. El valor predeterminado de android:enabled es true. Si lo configuras como false, también debes configurar un objeto android:shortcutDisabledMessage que explique por qué inhabilitaste el acceso directo. Si crees que no es necesario proporcionar un mensaje de este tipo, es más fácil quitar el acceso directo del archivo XML.

android:icon

Es el mapa de bits o ícono adaptable que usa el selector cuando se muestra el acceso directo al usuario. Este valor puede ser la ruta a una imagen o el archivo de recursos que contiene la imagen. Usa íconos adaptables siempre que sea posible para mejorar el rendimiento y la coherencia.

Nota: Los íconos de accesos directos no pueden incluir tonos.

Cómo configurar elementos internos

El archivo en formato XML que enumera los accesos directos estáticos de una app admite los siguientes elementos dentro de cada elemento <shortcut>. Debes incluir un elemento interno intent para cada acceso directo estático que definas.

intent

Esta es la acción que el sistema inicia cuando el usuario selecciona el acceso directo. Este intent debe proporcionar un valor para el atributo android:action.

Nota: Este elemento intent no puede incluir recursos de strings.

Puedes proporcionar varios intents para un solo acceso directo. Para obtener más detalles, consulta Cómo administrar varios intents y actividades, Cómo configurar un elemento intent y la referencia de la clase TaskStackBuilder.

categories

Proporciona una agrupación para los tipos de acciones que realizan los accesos directos de tu app, como la creación de nuevos mensajes de chat.

Para obtener una lista de categorías de accesos directos compatibles, consulta la referencia de la clase ShortcutInfo.

Cómo crear accesos directos dinámicos

Los accesos directos dinámicos proporcionan vínculos a acciones específicas y coherentes con el contexto dentro de tu app. Estas acciones pueden cambiar entre los usos de tu app e incluso mientras esta se encuentra en ejecución. Algunos buenos candidatos para accesos directos dinámicos incluyen llamar a una persona específica, navegar a una ubicación específica y cargar un juego desde el último punto obtenido del usuario.

La API ShortcutManager te permite completar las siguientes operaciones en accesos directos dinámicos:

• Publicar: Usa setDynamicShortcuts() para redefinir la lista completa de accesos directos dinámicos o usa addDynamicShortcuts() para aumentar una lista existente de accesos directos dinámicos.
• Actualizar: Usa el método updateShortcuts().
• Quitar: Quita un conjunto de accesos directos dinámicos con removeDynamicShortcuts() o quita todos con removeAllDynamicShortcuts().

Para obtener más información para realizar operaciones en accesos directos, consulta Cómo administrar accesos directos y la referencia de ShortcutManager.

En el siguiente fragmento de código, se muestra un ejemplo de cómo crear un acceso directo dinámico y asociarlo con tu app:

Nota: Las instancias de la clase ShortcutManager se deben obtener usando Context.getSystemService(Class) con el argumento ShortcutManager.class o Context.getSystemService(String) con el argumento Context.SHORTCUT_SERVICE.

val shortcutManager = getSystemService<ShortcutManager>(ShortcutManager::class.java)

val shortcut = ShortcutInfo.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

shortcutManager!!.dynamicShortcuts = Arrays.asList(shortcut)

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

ShortcutInfo shortcut = new ShortcutInfo.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

Cómo crear accesos directos fijos

En Android 8.0 (nivel de API 26) y versiones posteriores, puedes crear accesos directos fijos. A diferencia de los accesos directos estáticos y dinámicos, los accesos directos fijos aparecen en los selectores compatibles como íconos separados. En la Figura 1, se muestra la distinción entre estos dos tipos de accesos directos.

Nota: Cuando intentas fijar un acceso directo a un selector compatible, el usuario recibe un diálogo de confirmación en el que se le solicita permiso para fijar el acceso directo. Si el usuario no permite que se fije el acceso directo, el selector cancela la solicitud.

Para fijar un acceso directo a un selector compatible con tu app, completa la siguiente secuencia de pasos:

1. Usa isRequestPinShortcutSupported() para verificar que el selector predeterminado del dispositivo sea compatible con la función de fijación de accesos directos en la app.

2. Puedes crear un objeto ShortcutInfo de dos maneras diferentes según si el acceso directo ya existe:

   1. Si el acceso directo ya existe, crea un objeto ShortcutInfo que contenga solo el ID del acceso directo existente. El sistema encuentra y fija automáticamente el resto de la información relacionada con el acceso directo.
   2. Si quieres fijar un nuevo acceso directo, crea un objeto ShortcutInfo que contenga un ID, un intent y una etiqueta breve para el acceso directo.

   Nota: Como el sistema realiza la copia de seguridad y el restablecimiento de los accesos directos fijos automáticamente, los ID de estos accesos directos deben contener strings estables y constantes, o identificadores del servidor, en lugar de identificadores generados localmente que podrían no tener sentido en otros dispositivos.

3. Intenta fijar el acceso directo al selector del dispositivo llamando a requestPinShortcut(). Durante este proceso, puedes pasar un objeto PendingIntent, que notifica a tu app solo cuando el acceso directo se fija correctamente.

   Nota: Si el usuario no permite que el acceso directo se fije al selector, la app no recibirá una devolución de llamada.

   Después de fijar un acceso directo, la app puede actualizar su contenido con el método updateShortcuts(). Para obtener más información, consulta Cómo actualizar los accesos directos.

En el siguiente fragmento de código, se demuestra cómo crear un acceso directo fijo:

Nota: Las instancias de la clase ShortcutManager se deben obtener usando Context.getSystemService(Class) con el argumento ShortcutManager.class o Context.getSystemService(String) con el argumento Context.SHORTCUT_SERVICE.

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

Nota: Consulta también las API de la biblioteca de compatibilidad, isRequestPinShortcutSupported() y requestPinShortcut(), que funcionan en Android 7.1 (nivel de API 25) y versiones anteriores. La biblioteca de compatibilidad recurre al extra EXTRA_SHORTCUT_INTENT obsoleto para intentar llevar a cabo el proceso de fijación.

Cómo crear una actividad de accesos directos personalizada

También puedes crear una actividad especializada que ayude a los usuarios a crear accesos directos, completar con opciones personalizadas y crear un botón de confirmación. En la Figura 2, se muestra un ejemplo de este tipo de actividad en la app de Gmail.

En el archivo de manifiesto de tu app, agrega ACTION_CREATE_SHORTCUT al elemento <intent-filter> de la actividad. Esta declaración configura el siguiente comportamiento cuando el usuario intenta crear un acceso directo:

1. El sistema inicia la actividad especializada de tu app.
2. El usuario configura opciones para el acceso directo.
3. El usuario selecciona el botón de confirmación.
4. Tu app crea el acceso directo usando el método createShortcutResultIntent(). Este método muestra un Intent, que la app retransmite a la actividad ejecutada previamente mediante setResult().
5. La app llama a finish() en la actividad que se usa para crear el acceso directo personalizado.

Del mismo modo, la app puede solicitar a los usuarios que agreguen accesos directos fijos a la pantalla principal después de la instalación o la primera vez que se inicia la app. Este método es eficaz porque ayuda a tus usuarios a crear un acceso directo como parte de su flujo de trabajo habitual.

Cómo probar accesos directos

Para probar los accesos directos de tu app, instálala en un dispositivo con un selector que admita accesos directos. Luego, realiza las siguientes acciones:

• Mantén presionado el ícono de selector de tu app a fin de ver los accesos directos que definiste para ella.
• Presiona y arrastra un acceso directo para fijarlo en el selector del dispositivo.