Cómo crear accesos directos

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

Una imagen que muestra el contraste entre los accesos directos a aplicaciones y los accesos directos fijos
Figura 1: Accesos directos a aplicaciones y accesos directos fijos

La forma de entregar 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. Si bien el contexto de un acceso directo estático no cambia y el contexto de un atajo dinámico cambia constantemente, tu app controla el contexto en ambos casos. En los casos en los que un usuario elige cómo le entrega contenido tu app, por ejemplo, con un acceso directo fijo, el usuario define el contexto. En las siguientes situaciones, se describen algunos casos de uso para cada tipo de atajo:

  • Los accesos directos estáticos son ideales para apps que vinculan a contenido mediante una estructura coherente durante el ciclo de vida de la interacción del usuario con ella. Debido a que la mayoría de los selectores solo muestran cuatro accesos directos a la vez, los accesos directos estáticos son útiles para realizar una tarea rutinaria de manera coherente, por ejemplo, si el usuario desea ver su calendario o correo electrónico de una manera específica .
  • Los accesos directos dinámicos se usan para acciones en apps sensibles al contexto. Los accesos directos sensibles al contexto 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 inicio, debes actualizar el acceso directo con frecuencia. El uso de un acceso directo dinámico te permite actualizar el acceso directo 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 podría 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 usar una instancia predeterminada de un navegador.

Cómo crear accesos directos estáticos

Los atajos 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. Entre las buenas opciones de atajos estáticos, se incluyen ver los mensajes enviados, establecer una alarma y mostrar la actividad de ejercicio de un usuario para el día.

Para crear un acceso directo estático, haz lo siguiente:

  1. En el archivo AndroidManifest.xml de tu app, busca la actividad cuyos filtros de intents se configuraron 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 llamado res/xml/shortcuts.xml.

  4. En el nuevo archivo de recursos, agrega un elemento raíz <shortcuts> que contenga una lista de elementos <shortcut>. En cada elemento <shortcut>, incluye información sobre un acceso directo estático, como su ícono, las 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. Proporciona un valor para android:shortcutId y android:shortcutShortLabel. Todos los demás valores son opcionales.

android:shortcutId

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

android:shortcutShortLabel

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

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

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 descripción larga a 25 caracteres.

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

android:shortcutDisabledMessage

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é se inhabilitó el acceso directo. El valor de este atributo no tiene efecto si android:enabled es true.

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, configura un android:shortcutDisabledMessage que explique por qué inhabilitas el acceso directo. Si crees que no es necesario proporcionar un mensaje de este tipo, quita el acceso directo del archivo en formato XML por completo.

android:icon

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

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.

Puedes proporcionar varios intents para un solo acceso directo. Para obtener más información, consulta Cómo administrar varios intents y actividades, Cómo configurar un 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 crear 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 el acceso directo.

En el ejemplo anterior, 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 funciones permite que los usuarios usen comandos por voz con Asistente de Google para invocar un acceso directo.

Cómo crear accesos directos dinámicos

Los atajos dinámicos proporcionan vínculos a acciones específicas y contextuales dentro de tu app. Estas acciones pueden cambiar entre los usos de tu app y mientras esta se ejecuta. Los buenos usos de los atajos dinámicos incluyen llamar a una persona específica, navegar a una ubicación específica y cargar un juego desde el último punto de guardado del usuario. También puedes usar accesos directos dinámicos para abrir una conversación.

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

La API de ShortcutManagerCompat permite que tu app realice las siguientes operaciones con atajos dinámicos:

  • Envío y actualización: Usa pushDynamicShortcut() para publicar y actualizar tus atajos 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(). Quita todos los accesos directos dinámicos con removeAllDynamicShortcuts().

Si quieres obtener más información para realizar operaciones en accesos directos, consulta Cómo administrar accesos directos y la referencia ShortcutManagerCompat.

A continuación, se muestra un ejemplo de cómo crear un atajo dinámico y asociarlo con tu app:

Kotlin


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

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.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 enviar atajos dinámicos que se pueden mostrar en plataformas de Android, como el selector, y las plataformas de Google, como Asistente. El uso de esta biblioteca ayuda a los usuarios a descubrir tus atajos para acceder rápidamente a contenido específico o acciones de repetición en tu app.

Por ejemplo, una app de mensajería podría enviar un atajo dinámico para un contacto llamado "Alex" después de que un usuario envíe un mensaje a esa persona. Después de que se envía el atajo dinámico, si el usuario le pregunta al Asistente "Hey Google, envía un mensaje a Alex en AppDeEjemplo", Asistente podrá iniciar AppDeEjemplo y configurarla automáticamente para enviar un mensaje a Alex.

Los atajos dinámicos enviados con esta biblioteca no están sujetos a los límites de accesos directos que se aplican por dispositivo. Esto permite que tu app envíe un atajo cada vez que un usuario completa una acción asociada en ella. Si envías atajos frecuentes de esta manera, Google podrá comprender los patrones de uso del usuario y sugerirle atajos relevantes según el contexto.

Por ejemplo, Asistente puede aprender de los atajos enviados desde tu app de seguimiento de actividad física que un usuario suele ejecutar todas las mañanas y sugerir de manera proactiva un atajo para "iniciar una carrera" cuando el usuario tome el teléfono por la mañana.

La Biblioteca de integración de accesos directos de Google no ofrece ninguna funcionalidad direccionable. Si agregas esta biblioteca a tu app, las plataformas de Google podrán usar los atajos que envía tu app con ShortcutManagerCompat.

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

  1. 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
          
          
  2. 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"
            implementation 'androidx.core:core-google-shortcuts:1.0.0'
            ...
          }
          
          

Con las dependencias de bibliotecas agregadas a tu proyecto de Android, tu app puede usar el método pushDynamicShortcut() de ShortcutManagerCompat para enviar atajos dinámicos aptos para mostrarse en el selector y en las plataformas de Google participantes.

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.

Para fijar un acceso directo a un selector compatible con tu app, sigue estos pasos:

  1. Usa isRequestPinShortcutSupported() para verificar que el selector predeterminado del dispositivo admita la fijación de accesos directos en la app.
  2. Crea un objeto ShortcutInfo de dos maneras diferentes, según si existe el acceso directo:

    1. Si el acceso directo 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 corta para el nuevo acceso directo.
  3. Fija 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.

    Después de fijar un acceso directo, tu 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 muestra cómo crear un acceso directo fijo.

Kotlin

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

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements 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()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements 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());
}

Cómo crear una actividad de accesos directos personalizada

Imagen en la que se muestra la actividad del diálogo personalizado con el mensaje &quot;¿Quieres agregar el ícono de selector de Gmail a tu pantalla principal?&quot; Las opciones personalizadas son &quot;No, gracias&quot; y &quot;Agregar ícono&quot;.
Figura 2: Ejemplo de una actividad personalizada de diálogo de accesos directos a aplicaciones.

También puedes crear una actividad especializada que ayude a los usuarios a crear accesos directos, completar con opciones personalizadas y 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 tu app retransmite a la actividad en ejecución anterior mediante setResult().
  5. Tu 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 normal.

Cómo probar combinaciones de teclas

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 la app para ver los accesos directos que definas para ella.
  • Arrastra un acceso directo para fijarlo en el selector del dispositivo.