Créer des raccourcis

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

Figure 1. Raccourcis d'application et raccourcis épinglés.

La façon dont vous diffusez du contenu avec des raccourcis dépend de votre cas d'utilisation et du fait que le contexte du raccourci est 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 gère le contexte dans les deux cas. Lorsque l'utilisateur choisit la manière 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 particulièrement adaptés aux 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 effectuées par les utilisateurs dans une application. Par exemple, si vous créez un jeu qui permet à l'utilisateur de commencer à partir de son niveau actuel au lancement, vous devez mettre à jour le raccourci fréquemment. L'utilisation d'un raccourci dynamique vous permet de mettre à jour le raccourci 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 d'applications. Cela est utile, car l'utilisateur peut effectuer une action personnalisée, comme accéder au site Web en une seule étape, plus rapidement qu'en utilisant une instance par défaut d'un navigateur.

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 pendant toute la durée de vie de la version actuelle de votre application. Les raccourcis statiques sont par exemple utiles pour afficher les messages envoyés, définir une alarme et afficher l'activité physique d'un utilisateur pour la journée.

Pour créer un raccourci statique, procédez comme suit :

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 référence le fichier de ressources dans lequel les raccourcis de l'application sont définis :

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

   Remarque : Si vous utilisez un activity-alias, définissez les métadonnées dans l'alias d'activité plutôt que dans l'activité qu'il cible à l'aide de l'attribut targetActivity.

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

Personnaliser les valeurs d'attributs

La liste suivante inclut les 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

Chaîne littérale représentant le raccourci lorsqu'un objet ShortcutManager effectue des opérations dessus.

Remarque : Vous ne pouvez pas définir la valeur de cet attribut sur une chaîne de ressources, telle que @string/shortcut_id.

android:shortcutShortLabel

Une expression concise qui décrit l'objectif du raccourci. Dans la mesure du possible, limitez cette description courte à 10 caractères.

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

Remarque : La valeur de cet attribut doit être une chaîne de ressources, telle que @string/shortcut_short_label.

android:shortcutLongLabel

Expression étendue décrivant l'objectif du raccourci. Si l'espace est suffisant, le lanceur d'applications 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().

Remarque : La valeur de cet attribut doit être une chaîne de ressources, telle que @string/shortcut_long_label.

android:shortcutDisabledMessage

Message qui s'affiche dans un lanceur d'application 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.

Remarque : La valeur de cet attribut doit être une chaîne de ressources, telle que @string/shortcut_disabled_message.

android:enabled

Détermine si l'utilisateur peut interagir avec le raccourci à partir d'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 ne pensez pas avoir besoin de fournir un tel message, supprimez complètement le raccourci du fichier XML.

android:icon

Bitmap ou icône adaptative que le lanceur d'applications utilise lorsqu'il affiche le raccourci pour l'utilisateur. Cette valeur peut être le chemin d'accès à une image ou au fichier de ressources qui contient l'image. Utilisez des icônes adaptatives dans la mesure du possible pour améliorer les performances et la cohérence.

Remarque : Les icônes de raccourci ne peuvent pas inclure de teintes.

Configurer les éléments internes

Le fichier XML qui liste les raccourcis statiques d'une application accepte les éléments suivants dans 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. Cet intent doit fournir une valeur pour l'attribut android:action.

Remarque : Cet élément intent ne peut pas inclure de ressources de chaîne.

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 documentation de référence de la classe TaskStackBuilder.

categories

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

Pour obtenir la liste des catégories de raccourcis compatibles, consultez la documentation de 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é d'actions dans l'application. Cette liaison de fonctionnalité 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 emplacement spécifique et 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 un outil d'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 modifiable est mis à jour.
• Supprimer : 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 sur les raccourcis, consultez Gérer les raccourcis et la documentation de référence sur 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)
ShortcutsSnippets.kt

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

La bibliothèque d'intégration des raccourcis Google est une bibliothèque Jetpack facultative. Elle vous permet de transmettre des raccourcis dynamiques qui peuvent s'afficher sur les surfaces Android, comme le lanceur d'applications, et sur 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. En envoyant fréquemment des raccourcis de cette manière, Google peut comprendre les habitudes d'utilisation de l'utilisateur et lui suggérer des raccourcis pertinents en fonction du contexte.

Par exemple, l'Assistant peut apprendre, à partir des raccourcis transmis par votre application de suivi de l'activité physique, qu'un utilisateur court généralement tous les matins et lui suggérer de manière proactive un raccourci "Démarrer une course à pied" lorsqu'il prend son téléphone le matin.

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

Pour utiliser cette bibliothèque dans votre application, ajoutez des dépendances pour la bibliothèque d'intégration des raccourcis Google et ShortcutManagerCompat à votre fichier app/build.gradle ou app/build.gradle.kts :

Remarque : Pour obtenir les dernières versions de ces bibliothèques, consultez la page Versions d'AndroidX Core.

Kotlin

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

Groovy

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 pouvant être affichés dans le lanceur d'applications et sur les surfaces Google participantes.

Remarque : Nous vous recommandons d'utiliser pushDynamicShortcut pour envoyer des raccourcis dynamiques à l'aide de la bibliothèque d'intégration de raccourcis Google. Votre application peut utiliser d'autres méthodes pour publier des raccourcis, mais elles peuvent échouer si elles atteignent la limite maximale de raccourcis.

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 s'affichent dans les lanceurs compatibles sous forme d'icônes distinctes. La figure 1 illustre la distinction entre ces deux types de raccourcis.

Remarque : Lorsque vous tentez d'épingler un raccourci sur un lanceur compatible, l'utilisateur reçoit une boîte de dialogue de confirmation lui demandant l'autorisation d'épingler le raccourci. Si l'utilisateur n'autorise pas l'épinglage du raccourci, le lanceur d'applications annule la demande.

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 est compatible avec l'épinglage des raccourcis dans l'application.

2. Créez un objet ShortcutInfoCompat contenant un ID, un intent et un libellé court pour le raccourci. Si le raccourci existe, utilisez l'ID du raccourci existant. Le système recherche et épingle automatiquement toutes les autres informations liées au raccourci.

   Remarque : ShortcutInfoCompat.Builder nécessite un libellé court et un intent, même lorsque vous utilisez l'ID d'un raccourci existant. Si vous ne les définissez pas, build() génère une exception IllegalArgumentException.
   Remarque : Étant donné que le système effectue automatiquement la sauvegarde et la restauration des raccourcis épinglés, les ID de ces raccourcis doivent contenir des chaînes stables et constantes ou des identifiants côté serveur, plutôt que des identifiants générés localement qui n'auraient pas de sens sur d'autres appareils.

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

   Remarque : Si l'utilisateur n'autorise pas l'épinglage du raccourci au lanceur d'applications, votre application ne reçoit pas de rappel.

   Une fois qu'un raccourci est é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é :

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

Remarque : Sur Android 7.1 (niveau d'API 25) ou version antérieure, ShortcutManagerCompat utilise l'extra EXTRA_SHORTCUT_INTENT obsolète pour tenter d'épingler l'élément.

Créer une activité de raccourci personnalisé

Figure 2 : Exemple d'activité de boîte de dialogue de raccourci d'application personnalisé.

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 configure 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 lors du premier lancement de 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.