Créer des raccourcis

Les raccourcis permettent de proposer des types de contenus spécifiques à vos utilisateurs en les aidant à accéder rapidement à des sections de votre application.

La façon dont vous fournissez du contenu avec des raccourcis dépend de votre cas d'utilisation et du contexte du raccourci (piloté par l'application ou par l'utilisateur). Bien que le contexte d'un raccourci statique ne change pas et que celui d'un raccourci dynamique change constamment, votre application détermine le contexte dans les deux cas. Dans les cas où un utilisateur choisit la façon dont votre application lui fournit du contenu, par exemple avec un raccourci épinglé, le contexte est défini par l'utilisateur. Les scénarios suivants décrivent quelques cas d'utilisation pour chaque type de raccourci :

• Les raccourcis statiques sont idéaux pour les applications qui renvoient vers du contenu à l'aide d'une structure cohérente tout au long de l'interaction de l'utilisateur avec l'application. Étant donné que la plupart des lanceurs d'applications n'affichent que quatre raccourcis à la fois, les raccourcis statiques sont utiles pour effectuer une tâche de routine de manière cohérente, par exemple si l'utilisateur souhaite afficher son agenda ou ses e-mails d'une manière spécifique.
• Les raccourcis dynamiques sont utilisés pour les actions contextuelles dans les applications. Les raccourcis contextuels sont adaptés aux actions que les utilisateurs effectuent dans une application. Par exemple, si vous créez un jeu qui permet à l'utilisateur de commencer à son niveau actuel au lancement, vous devez mettre à jour le raccourci fréquemment. L'utilisation d'un raccourci dynamique vous permet de le mettre à jour chaque fois que l'utilisateur termine un niveau.
• Les raccourcis épinglés sont utilisés pour des actions spécifiques déclenchées par l'utilisateur. Par exemple, un utilisateur peut vouloir épingler un site Web spécifique au lanceur. Cela est avantageux, car cela permet à l'utilisateur d'effectuer une action personnalisée, comme accéder au site Web en une seule étape, plus rapidement qu'en utilisant une instance de navigateur par défaut.

Créer des raccourcis statiques

Les raccourcis statiques fournissent des liens vers des actions génériques dans votre application. Ces actions doivent rester cohérentes tout au long du cycle de vie de la version actuelle de votre application. Les options intéressantes pour les raccourcis statiques incluent l'affichage des messages envoyés, la définition d'une alarme et l'affichage de l'activité physique d'un utilisateur pour la journée.

Pour créer un raccourci statique :

1. Dans le fichier AndroidManifest.xml de votre application, recherchez l'activité dont les filtres d'intent sont définis sur l'action android.intent.action.MAIN et la catégorie android.intent.category.LAUNCHER.

2. Ajoutez un élément <meta-data> à cette activité, qui fait référence au fichier de ressources où sont définis les raccourcis de l'application :

   <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. Créez un fichier de ressources nommé res/xml/shortcuts.xml.

4. Dans le nouveau fichier de ressources, ajoutez un élément racine <shortcuts> contenant une liste d'éléments <shortcut>. Dans chaque élément <shortcut>, incluez des informations sur un raccourci statique, y compris son icône, ses libellés de description et les intents qu'il lance dans l'application :

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

Personnaliser les valeurs d'attribut

La liste suivante inclut des descriptions des différents attributs d'un raccourci statique. Indiquez une valeur pour android:shortcutId et android:shortcutShortLabel. Toutes les autres valeurs sont facultatives.

android:shortcutId

Littéral de chaîne représentant le raccourci lorsqu'un objet ShortcutManager effectue des opérations sur celui-ci.

android:shortcutShortLabel

Expression concise décrivant l'objectif du raccourci. Si possible, limitez cette brève description à 10 caractères.

Pour en savoir plus, consultez la page setShortLabel().

android:shortcutLongLabel

Phrase longue décrivant l'objectif du raccourci. S'il y a suffisamment d'espace, le lanceur affiche cette valeur au lieu de android:shortcutShortLabel. Si possible, limitez cette description longue à 25 caractères.

Pour en savoir plus, consultez la page setLongLabel().

android:shortcutDisabledMessage

Message qui s'affiche dans un lanceur d'applications compatible lorsque l'utilisateur tente de lancer un raccourci désactivé. Le message doit expliquer à l'utilisateur pourquoi le raccourci est désactivé. La valeur de cet attribut n'a aucun effet si android:enabled est défini sur true.

android:enabled

Détermine si l'utilisateur peut interagir avec le raccourci depuis un lanceur d'applications compatible. La valeur par défaut de android:enabled est true. Si vous le définissez sur false, définissez un android:shortcutDisabledMessage qui explique pourquoi vous désactivez le raccourci. Si vous pensez qu'il n'est pas nécessaire de fournir un tel message, supprimez complètement le raccourci du fichier XML.

android:icon

L'icône bitmap ou l'icône adaptative que le lanceur d'applications utilise lorsqu'il affiche le raccourci à l'utilisateur. Cette valeur peut correspondre au chemin d'accès à une image ou au fichier de ressources contenant l'image. Utilisez des icônes adaptatives chaque fois que possible pour améliorer les performances et la cohérence.

Configurer les éléments internes

Le fichier XML qui liste les raccourcis statiques d'une application est compatible avec les éléments suivants à l'intérieur de chaque élément <shortcut>. Vous devez inclure un élément interne intent pour chaque raccourci statique que vous définissez.

intent

Action lancée par le système lorsque l'utilisateur sélectionne le raccourci. Cette intention doit fournir une valeur pour l'attribut android:action.

Vous pouvez fournir plusieurs intents pour un même raccourci. Pour en savoir plus, consultez Gérer plusieurs intents et activités, Définir un intent et la référence de la classe TaskStackBuilder.

categories

Fournit un regroupement pour les types d'actions effectuées par les raccourcis de votre application, comme la création de messages de chat.

Pour obtenir la liste des catégories de raccourcis acceptées, consultez la référence de la classe ShortcutInfo.

capability-binding

Déclare la capacité associée au raccourci.

Dans l'exemple précédent, le raccourci est associé à une capacité déclarée pour CREATE_MESSAGE, qui est un intent intégré Actions dans les applications. Cette liaison de capacité permet aux utilisateurs d'utiliser des commandes vocales avec l'Assistant Google pour appeler un raccourci.

Créer des raccourcis dynamiques

Les raccourcis dynamiques fournissent des liens vers des actions spécifiques et contextuelles dans votre application. Ces actions peuvent changer entre les utilisations de votre application et pendant son exécution. Les raccourcis dynamiques sont utiles pour appeler une personne spécifique, accéder à un lieu précis ou charger un jeu à partir du dernier point de sauvegarde de l'utilisateur. Vous pouvez également utiliser des raccourcis dynamiques pour ouvrir une conversation.

La bibliothèque Jetpack ShortcutManagerCompat est une aide pour l'API ShortcutManager, qui vous permet de gérer les raccourcis dynamiques dans votre application. L'utilisation de la bibliothèque ShortcutManagerCompat réduit le code récurrent et permet de s'assurer que vos raccourcis fonctionnent de manière cohérente sur toutes les versions d'Android. Cette bibliothèque est également requise pour envoyer des raccourcis dynamiques afin qu'ils puissent apparaître sur les surfaces Google, comme l'Assistant, avec la bibliothèque d'intégration des raccourcis Google.

L'API ShortcutManagerCompat permet à votre application d'effectuer les opérations suivantes avec des raccourcis dynamiques :

• Transférer et mettre à jour : utilisez pushDynamicShortcut() pour publier et mettre à jour vos raccourcis dynamiques. S'il existe déjà des raccourcis dynamiques ou épinglés avec le même ID, chaque raccourci mutable est mis à jour.
• Remove : supprimez un ensemble de raccourcis dynamiques à l'aide de removeDynamicShortcuts(). Supprimez tous les raccourcis dynamiques à l'aide de removeAllDynamicShortcuts().

Pour en savoir plus sur les opérations à effectuer sur les raccourcis, consultez Gérer les raccourcis et la référence ShortcutManagerCompat.

Voici un exemple de création d'un raccourci dynamique et de son association à votre application :

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)

Ajouter la bibliothèque d'intégration des raccourcis Google

La bibliothèque d'intégration de raccourcis Google est une bibliothèque Jetpack facultative. Il vous permet d'envoyer des raccourcis dynamiques qui peuvent être affichés sur les surfaces Android, telles que le lanceur d'applications, et les surfaces Google. Cette bibliothèque aide les utilisateurs à découvrir vos raccourcis pour accéder rapidement à des contenus spécifiques ou rejouer des actions dans votre application.

Les raccourcis dynamiques envoyés avec cette bibliothèque ne sont pas soumis aux limites de raccourcis appliquées par appareil. Cela permet à votre application d'envoyer un raccourci chaque fois qu'un utilisateur effectue une action associée dans votre application. L'envoi fréquent de raccourcis de cette manière permet à Google de comprendre les habitudes d'utilisation de vos utilisateurs et de leur suggérer des raccourcis contextuellement pertinents.

Par exemple, l'Assistant peut apprendre des raccourcis transmis par votre application de suivi de la forme physique qu'un utilisateur exécute généralement chaque matin et suggérer de manière proactive un raccourci "Démarrer une course" lorsque l'utilisateur prend son téléphone le matin.

La bibliothèque d'intégration de raccourcis Google ne propose aucune fonctionnalité adressable en soi. L'ajout de cette bibliothèque à votre application permet aux surfaces Google d'intégrer les raccourcis que votre application envoie à l'aide de ShortcutManagerCompat.

Pour utiliser cette bibliothèque dans votre application, procédez comme suit :

1. Mettez à jour votre fichier gradle.properties pour prendre en charge les bibliothèques AndroidX :

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

2. Dans app/build.gradle, ajoutez les dépendances pour la bibliothèque d'intégration des raccourcis Google et ShortcutManagerCompat :

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

Une fois les dépendances de bibliothèque ajoutées à votre projet Android, votre application peut utiliser la méthode pushDynamicShortcut() de ShortcutManagerCompat pour envoyer des raccourcis dynamiques éligibles à l'affichage sur le lanceur d'applications et les surfaces Google participantes.

Créer des raccourcis épinglés

Sur Android 8.0 (niveau d'API 26) ou version ultérieure, vous pouvez créer des raccourcis épinglés. Contrairement aux raccourcis statiques et dynamiques, les raccourcis épinglés apparaissent dans les lanceurs d'applications compatibles sous forme d'icônes distinctes. La figure 1 montre la distinction entre ces deux types de raccourcis.

Pour épingler un raccourci à un lanceur d'applications compatible à l'aide de votre application, procédez comme suit :

1. Utilisez isRequestPinShortcutSupported() pour vérifier que le lanceur d'applications par défaut de l'appareil prend en charge l'épinglage de raccourcis dans l'application.

2. Créez un objet ShortcutInfo de deux manières, selon que le raccourci existe ou non :

   1. Si le raccourci existe, créez un objet ShortcutInfo qui ne contient que l'ID du raccourci existant. Le système trouve et épingle automatiquement toutes les autres informations associées au raccourci.
   2. Si vous épinglez un nouveau raccourci, créez un objet ShortcutInfo qui contient un ID, une intention et un libellé court pour le nouveau raccourci.

3. Épinglez le raccourci au lanceur d'applications de l'appareil en appelant requestPinShortcut(). Pendant ce processus, vous pouvez transmettre un objet PendingIntent, qui avertit votre application uniquement lorsque le raccourci est épinglé.

   Une fois le raccourci épinglé, votre application peut mettre à jour son contenu à l'aide de la méthode updateShortcuts(). Pour en savoir plus, consultez Mettre à jour les raccourcis.

L'extrait de code suivant montre comment créer un raccourci épinglé.

val shortcutManager = getSystemService<ShortcutManager>()

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

Créer une activité de raccourci personnalisée

Vous pouvez également créer une activité spécialisée qui aide les utilisateurs à créer des raccourcis, avec des options personnalisées et un bouton de confirmation. La figure 2 montre un exemple de ce type d'activité dans l'application Gmail.

Dans le fichier manifeste de votre application, ajoutez ACTION_CREATE_SHORTCUT à l'élément <intent-filter> de l'activité. Cette déclaration définit le comportement suivant lorsque l'utilisateur tente de créer un raccourci :

1. Le système démarre l'activité spécialisée de votre application.
2. L'utilisateur définit les options du raccourci.
3. L'utilisateur sélectionne le bouton de confirmation.
4. Votre application crée le raccourci à l'aide de la méthode createShortcutResultIntent(). Cette méthode renvoie un Intent que votre application transmet à l'activité précédemment exécutée à l'aide de setResult().
5. Votre application appelle finish() sur l'activité utilisée pour créer le raccourci personnalisé.

De même, votre application peut inviter les utilisateurs à ajouter des raccourcis épinglés à l'écran d'accueil après l'installation ou la première fois qu'ils lancent l'application. Cette méthode est efficace, car elle aide vos utilisateurs à créer un raccourci dans le cadre de leur workflow habituel.

Raccourcis de test

Pour tester les raccourcis de votre application, installez-la sur un appareil doté d'un lanceur d'applications compatible avec les raccourcis. Ensuite, effectuez les actions suivantes :

• Appuyez de manière prolongée sur l'icône de lanceur de votre application pour afficher les raccourcis que vous avez définis pour votre application.
• Faites glisser un raccourci pour l'épingler au lanceur d'applications de l'appareil.