Cómo crear accesos directos

Los accesos directos proporcionan tipos específicos de contenido a los usuarios, ya que los ayudan a acceder rápidamente a partes de tu app.

La forma en que entregas contenido con los accesos directos depende de tu caso de uso y de si el contexto del acceso directo está controlado por la app o por el usuario. Aunque el contexto de un acceso directo estático no cambia y el de uno dinámico cambia constantemente, tu app controla el contexto en ambos casos. En los casos en que un usuario elige cómo tu app le entrega contenido, como con un acceso directo fijado, el usuario define el contexto. En las siguientes situaciones, se describen algunos casos de uso para cada tipo de acceso directo:

• Los atajos estáticos son más adecuados para las apps que vinculan contenido con una estructura coherente durante toda la interacción del usuario con la app. Como la mayoría de los selectores solo muestran cuatro atajos a la vez, los atajos estáticos son útiles para realizar una tarea de rutina de manera coherente, como cuando el usuario quiere ver su calendario o correo electrónico de una manera específica.
• Los atajos dinámicos se usan para acciones en apps que son sensibles al contexto. Los atajos contextuales se adaptan a las acciones que realizan los usuarios en una app. Por ejemplo, si creas un juego que permite que el usuario comience desde su nivel actual en el momento del inicio, debes actualizar el atajo con frecuencia. Usar un atajo dinámico te permite actualizarlo cada vez que el usuario supera un nivel.
• Los accesos directos fijados se usan para acciones específicas que realiza el usuario. Por ejemplo, es posible que un usuario quiera fijar un sitio web específico en el selector. Esto es beneficioso porque permite que el usuario realice una acción personalizada, como navegar al sitio web en un solo paso, con mayor rapidez que con una instancia predeterminada de un navegador.

Cómo crear accesos directos estáticos

Los atajos estáticos proporcionan vínculos a acciones genéricas dentro de tu app, y estas acciones deben permanecer coherentes durante el ciclo de vida de la versión actual de tu app. Entre las buenas opciones para los accesos directos estáticos, se incluyen ver los mensajes enviados, configurar una alarma y mostrar la actividad de ejercicio de un usuario durante 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 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 en el que 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 archivo de recursos nuevo 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 atajo 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.Main" />
       <!-- 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>
   shortcuts.xml

Cómo personalizar valores de atributos

En la siguiente lista, se incluyen descripciones de los diferentes atributos 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 una cadena literal que representa el acceso directo cuando un objeto ShortcutManager realiza operaciones en él.

android:shortcutShortLabel

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

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

android:shortcutLongLabel

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. Si es posible, limita esta 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 explicarle 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 estableces en false, configura un android:shortcutDisabledMessage que explique por qué inhabilitas el acceso directo. Si crees que no necesitas proporcionar ese mensaje, quita el acceso directo del archivo XML por completo.

android:icon

Es el mapa de bits o el ícono adaptable que usa el selector cuando muestra el acceso directo al usuario. Este valor puede ser la ruta de acceso 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.

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

Es la acción que inicia el sistema 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. Consulta Cómo administrar varios intents y actividades, Cómo establecer un intent y la referencia de la clase TaskStackBuilder para obtener más detalles.

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 las categorías de accesos directos compatibles, consulta la referencia de la clase ShortcutInfo.

capability-binding

Declara la capability 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 el Asistente de Google para invocar un atajo.

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 y mientras esta se encuentra en ejecución. Algunos buenos ejemplos de casos de uso para accesos directos dinámicos incluyen llamar a una persona determinada, navegar a una ubicación específica y cargar un juego desde el último punto obtenido del usuario. También puedes usar accesos directos dinámicos para abrir una conversación.

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

La API de ShortcutManagerCompat 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 hay accesos directos dinámicos o fijados con el mismo ID, se actualiza cada acceso directo mutable.
• Quitar: Quita un conjunto de accesos directos dinámicos con removeDynamicShortcuts(). Quita todos los accesos directos dinámicos con removeAllDynamicShortcuts().

Para obtener más información sobre cómo realizar operaciones en los accesos directos, consulta Administra accesos directos y la referencia de ShortcutManagerCompat.

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

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)
ShortcutsSnippets.kt

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 las plataformas de Android, como el selector, y en las plataformas de Google. El uso de esta biblioteca ayuda a los usuarios a descubrir tus atajos para acceder rápidamente a contenido específico o volver a reproducir acciones en tu app.

Los accesos directos dinámicos que se envían 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 complete una acción asociada en tu app. El envío de atajos frecuentes de esta manera permite que Google comprenda los patrones de uso de tu usuario y le sugiera atajos contextualmente relevantes.

Por ejemplo, Asistente puede aprender de los atajos que envía tu app de seguimiento de actividad física que un usuario suele correr todas las mañanas y sugerir de forma proactiva un atajo para "comenzar a correr" cuando el usuario toma su teléfono por la mañana.

La biblioteca de integración de accesos directos de Google no ofrece ninguna funcionalidad direccionable por sí misma. Agregar esta biblioteca a tu app permite que las plataformas de Google asimilen los atajos que tu app envía con ShortcutManagerCompat.

Para usar esta biblioteca en tu app, agrega dependencias para la biblioteca de integración de accesos directos de Google y ShortcutManagerCompat a tu archivo app/build.gradle o app/build.gradle.kts:

dependencies {
    implementation("androidx.core:core:1.6.0")
    implementation("androidx.core:core-google-shortcuts:1.0.0")
}

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

Con las dependencias de la biblioteca agregadas a tu proyecto de Android, tu app puede usar el método pushDynamicShortcut() de ShortcutManagerCompat para enviar atajos dinámicos que se pueden mostrar 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 fijados aparecen en los selectores compatibles como íconos independientes. En la figura 1, se muestra la diferencia 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 ShortcutInfoCompat que contenga un ID, un intent y una etiqueta corta para el acceso directo. Si el acceso directo existe, usa el ID del acceso directo existente. El sistema busca y fija automáticamente toda la información relacionada con el 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 atajo, tu app puede actualizar su contenido con el método updateShortcuts(). Para obtener más información, consulta Cómo actualizar accesos directos.

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

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

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, 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 establece las opciones del acceso directo.
3. El usuario selecciona el botón de confirmación.
4. Tu app crea el acceso directo con el método createShortcutResultIntent(). Este método devuelve un objeto Intent, que tu app retransmite a la actividad que se estaba ejecutando anteriormente con setResult().
5. Tu app llama a finish() en la actividad que se usa para crear el acceso directo personalizado.

Del mismo modo, tu app puede solicitarles a los usuarios que agreguen accesos directos fijados 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 los usuarios a crear un acceso directo como parte de su flujo de trabajo habitual.

Prueba los 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 para ver los accesos directos que definiste para ella.
• Arrastra un acceso directo para fijarlo al selector del dispositivo.