Los atajos entregan tipos específicos de contenido a tus usuarios ayudándolos a acceder rápidamente a partes de tu app.
La manera de entregar contenido con atajos 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 acceso directo 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 fijo, el usuario define el contexto. En las siguientes situaciones, se describen algunos casos de uso para cada tipo de acceso directo:
- Los accesos directos estáticos son mejores para las apps que vinculan a contenido mediante una estructura coherente durante el ciclo de vida de la interacción de un usuario con ella. Debido a que la mayoría de los selectores solo muestran cuatro accesos directos a la vez, los atajos 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 atajos 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 le permite al usuario realizar 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. Las buenas opciones de atajos estáticos incluyen ver los mensajes enviados, configurar 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:
-
En el archivo
AndroidManifest.xml
de tu app, busca la actividad cuyos filtros de intents están configurados en la acciónandroid.intent.action.MAIN
y la categoríaandroid.intent.category.LAUNCHER
. -
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>
-
Crea un nuevo archivo de recursos llamado
res/xml/shortcuts.xml
. -
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, incluidos 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 la 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 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 explicar al usuario por qué está inhabilitado el acceso directo. El valor de este atributo no tiene efecto si
android:enabled
estrue
. -
android:enabled
-
Determina si el usuario puede interactuar con el acceso directo desde un selector compatible. El valor predeterminado de
android:enabled
estrue
. Si lo configuras comofalse
, configura unandroid: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 atajos 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 detalles, consulta Cómo administrar varios intents y actividades, Cómo configurar un intent y la referencia de 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 las 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 a los usuarios usar 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 sensibles al contexto dentro de tu app. Estas acciones pueden cambiar entre los usos de tu app y mientras esta se encuentra en ejecución. Algunos usos recomendados para 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 combinaciones de teclas dinámicas para abrir una conversación.
La biblioteca ShortcutManagerCompat
de Jetpack es auxiliar para la API de ShortcutManager
, lo que te permite administrar atajos dinámicos en tu app. El uso de la biblioteca ShortcutManagerCompat
reduce el código estándar y ayuda a garantizar que los atajos funcionen de manera coherente en 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 atajos 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 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()
. Quita todos los accesos directos dinámicos conremoveAllDynamicShortcuts()
.
Si quieres obtener más información para realizar operaciones en accesos directos, consulta Cómo administrar accesos directos y la referencia ShortcutManagerCompat
.
Este es 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 en 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 que envíe 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 forma proactiva un atajo para "iniciar una carrera" cuando el usuario tome el teléfono en la mañana.
La Biblioteca de integración de atajos 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:
-
Actualiza el archivo
gradle.properties
para 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 yShortcutManagerCompat
:dependencies { implementation "androidx.core:core:1.6.0" implementation 'androidx.core:core-google-shortcuts:1.0.0' ... }
Con las dependencias de biblioteca 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 participantes de Google.
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, completa los siguientes pasos:
-
Usa
isRequestPinShortcutSupported()
para verificar que el selector predeterminado del dispositivo admita la fijación de accesos directos en la app. -
Crea un objeto
ShortcutInfo
de dos maneras según si existe el acceso directo:-
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. -
Si quieres fijar un nuevo acceso directo, crea un objeto
ShortcutInfo
que contenga un ID, un intent y una etiqueta breve para el nuevo acceso directo.
-
Si el acceso directo existe, crea un objeto
-
Fija el acceso directo al selector del dispositivo llamando a
requestPinShortcut()
. Durante este proceso, puedes pasar un objetoPendingIntent
, 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
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:
- 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 con el método
createShortcutResultIntent()
. Este método muestra unaIntent
, que tu app retransmite a la actividad que se estaba ejecutando con anterioridad mediantesetResult()
. -
Tu app llama a
finish()
en la actividad que se usa para crear el acceso directo personalizado.
Del mismo modo, tu 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 común.
Cómo probar combinaciones de teclas
Para probar los atajos de tu app, instálala en un dispositivo con un selector que los admita. Luego, realiza las siguientes acciones:
- Mantén presionado el ícono de selector de tu app para ver los accesos directos que definas para ella.
- Arrastra un acceso directo para fijarlo en el selector del dispositivo.