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. Los accesos directos contextuales se adaptan a las acciones que los usuarios realizan en una app. Por ejemplo, si compilas un juego que permite al usuario comenzar desde su nivel actual en el lanzamiento, debes actualizar el acceso directo 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:

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.

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>

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

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" />
    <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
  </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.

capability-binding

Declara la capacidad vinculada con este acceso directo.

En este ejemplo, el acceso directo está vinculado a una función declarada para CREATE_MESSAGE, que es un intent integrado de Acciones en apps. Esta vinculación de capacidad particular permite a los usuarios usar comandos por voz con Asistente de Google para invocar este acceso directo.

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 determinada, navegar a una ubicación específica y cargar un juego desde la última partida guardada

La biblioteca de ShortcutManagerCompat de Jetpack es útil para la API de ShortcutManager, y te permite administrar accesos directos dinámicos en tu app. Usar la biblioteca de ShortcutManagerCompat reduce el código estándar y garantiza que tus accesos directos funcionen de manera coherente en todas las versiones de Android. Esta biblioteca también se requiere para enviar accesos directos dinámicos a fin de que puedan aparecer en las plataformas de Google, como Asistente, con la Biblioteca de integración de accesos directos de Google.

La API de ShorcutManagerCompat permite que tu app realice las siguientes operaciones con accesos directos dinámicos:

Envío y actualización: Usa pushDynamicShortcut() para publicar y actualizar tus accesos directos dinámicos. Si ya existen accesos directos dinámicos o fijos con el mismo ID, se actualizará cada uno de ellos.
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 ShortcutManagerCompat.

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:

Kotlin


val shortcut = ShortcutInfoCompat.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()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfo shortcut = new ShortcutInfoCompat.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();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

Cómo agregar la Biblioteca de integración de accesos directos de Google

La Biblioteca de integración de accesos directos de Google es una biblioteca de Jetpack opcional. Te permite insertar accesos directos dinámicos que se pueden mostrar en plataformas de Android (como el selector) y de Google (como Asistente). El uso de esta biblioteca permite a tus usuarios descubrir fácilmente tus accesos directos para acceder al instante a contenido específico o acciones de repetición en tu app. Por ejemplo, una app de mensajería podría insertar un acceso directo dinámico para un contacto "Alex", después de que un usuario envía mensajes a esa persona. Después de que se envía el acceso directo dinámico, si el usuario le pregunta al Asistente "Hey Google, envía un mensaje a Alex en AppDeEjemplo", Asistente podría iniciar AppDeEjemplo y configurarla automáticamente para que envíe un mensaje a Alex.

Los accesos directos dinámicos enviados con esta biblioteca no están sujetos al límite de cinco accesos directos, lo que permite que tu app envíe un acceso directo cada vez que un usuario complete una acción asociada en tu app. Si envías accesos directos frecuentes de esta manera, Google podrá comprender el contexto del usuario y sugerirle accesos directos relevantes. Por ejemplo, Asistente puede aprender de los accesos directos enviados desde tu app de seguimiento de actividad física que un usuario suele salir a caminar por la mañana y sugerir de manera proactiva un acceso directo para "iniciar una caminata" cuando el usuario toma el teléfono por la mañana.

La Biblioteca de integración de accesos directos de Google no ofrece ninguna funcionalidad direccionable. Agregar esta biblioteca a tu app permite que las plataformas de Google transfieran los accesos directos que envía tu app mediante ShortcutManagerCompat.

Para usar la biblioteca en tu app, sigue estos pasos:

Actualiza el archivo gradle.properties de modo que sea compatible con las bibliotecas de AndroidX:


         android.useAndroidX=true
         # Automatically convert third-party libraries to use AndroidX
         android.enableJetifier=true

En app/build.gradle, agrega dependencias para la Biblioteca de integración de accesos directos de Google y ShortcutManagerCompat:


         dependencies {
           implementation "androidx.core:core:1.6.0-beta01"
           implementation 'androidx.core:core-google-shortcuts:1.0.0-beta01'
           ...
         }

Con las dependencias de la biblioteca agregadas a tu proyecto de Android, tu app puede usar el método pushDynamicShortcut() de ShortcutManagerCompat a fin de aplicar accesos directos dinámicos que serán aptos para mostrarse en el selector y en las plataformas participantes de Google.

Nota: Recomendamos usar pushDynamicShortcut para enviar accesos directos dinámicos mediante la Biblioteca de integración de accesos directos de Google. Tu app puede usar otros métodos para publicar accesos directos, pero pueden fallar si alcanzan el límite máximo de accesos directos.

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.

Captura de pantalla que muestra el contraste entre los accesos directos a aplicaciones y los accesos directos fijos — **Figura 1:** Apariencia de accesos directos a aplicaciones y accesos directos fijos

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

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.
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.
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.

Kotlin

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)
}

Java

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

La actividad de diálogo personalizada muestra el mensaje "¿Quieres agregar el ícono de selector de Gmail en tu pantalla principal?". Las opciones personalizadas son "No, gracias" y "Agregar ícono". — **Figura 2:** Ejemplo de una actividad personalizada de diálogo de acceso directo a aplicaciones

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:

El sistema inicia la actividad especializada de tu app.
El usuario configura opciones para el acceso directo.
El usuario selecciona el botón de confirmación.
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().
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.