Créer des raccourcis

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

La manière dont vous fournissez du contenu avec des raccourcis dépend de votre cas d'utilisation et de si le contexte du raccourci est basé sur l'application ou sur l'utilisateur. Bien que le contexte d'un raccourci statique ne change pas et que le contexte d'un raccourci dynamique change constamment, votre application gère le contexte dans les deux cas. Dans les cas où un utilisateur choisit la manière dont votre application lui envoie 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 recommandés pour les applications qui renvoient au contenu à l'aide d'une structure cohérente tout au long de la durée d'interaction d'un utilisateur avec l'application. La plupart des lanceurs n'affichent que quatre raccourcis à la fois. Ils sont donc utiles pour effectuer une tâche de routine de manière cohérente, par exemple si l'utilisateur souhaite consulter son agenda ou ses e-mails d'une manière spécifique.
• Les raccourcis dynamiques sont utilisés pour les actions dans les applications sensibles au contexte. 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 reprendre son niveau actuel au lancement, vous devez le mettre à jour fréquemment. L'utilisation d'un raccourci dynamique vous permet de le mettre à jour chaque fois que l'utilisateur efface un niveau.
• Les raccourcis épinglés sont utilisés pour des actions spécifiques dirigées par l'utilisateur. Par exemple, un utilisateur peut vouloir épingler un site Web spécifique dans le lanceur d'applications. Cette approche est utile, car elle permet à l'utilisateur d'effectuer une action personnalisée (par exemple, 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 bonnes options 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, 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 à cette activité un élément <meta-data> 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>
     

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

Personnaliser les valeurs des attributs

La liste suivante inclut des descriptions des différents attributs dans 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 qui représente le raccourci lorsqu'un objet ShortcutManager effectue des opérations sur celui-ci.

android:shortcutShortLabel

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

Pour en savoir plus, consultez setShortLabel().

android:shortcutLongLabel

Formule étendue décrivant l'objectif du raccourci. Si l'espace est suffisant, le lanceur affiche cette valeur au lieu de android:shortcutShortLabel. Si possible, limitez la description longue à 25 caractères.

Pour en savoir plus, consultez 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 à partir d'un lanceur d'applications compatible. La valeur par défaut de android:enabled est true. Si vous la définissez sur false, définissez une android:shortcutDisabledMessage qui explique pourquoi vous désactivez le raccourci. Si vous pensez que vous n'avez pas besoin de fournir un tel message, supprimez complètement le raccourci du fichier XML.

android:icon

Bitmap ou icône adaptative utilisé par le lanceur d'applications lors de l'affichage du raccourci auprès de l'utilisateur. Cette valeur peut être le chemin d'accès à une image ou le fichier de ressources qui la contient. Dans la mesure du possible, utilisez des icônes adaptatives pour améliorer les performances et la cohérence.

Configurer les éléments internes

Le fichier XML qui répertorie les raccourcis statiques d'une application est compatible avec 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.

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 sur la classe TaskStackBuilder.

categories

Fournit un regroupement des 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 compatibles, consultez la documentation de référence de la classe ShortcutInfo.

capability-binding

Déclare l'élément capability associé au raccourci.

Dans l'exemple précédent, le raccourci est associé à une fonctionnalité déclarée pour CREATE_MESSAGE, qui est un intent intégré Actions dans les applications. Cette liaison de fonctionnalités 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 sensibles au contexte dans votre application. Ces actions peuvent varier selon l'utilisation de votre application et pendant son exécution. Les raccourcis dynamiques sont utiles pour appeler une personne spécifique, naviguer vers un lieu spécifique et charger un jeu à partir du dernier point d'enregistrement de l'utilisateur. Vous pouvez également utiliser des raccourcis dynamiques pour ouvrir une conversation.

La bibliothèque Jetpack ShortcutManagerCompat est une aide de 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 garantir que vos raccourcis fonctionnent de manière cohérente sur toutes les versions d'Android. Cette bibliothèque est également nécessaire pour transmettre des raccourcis dynamiques afin qu'ils puissent apparaître sur les surfaces Google, telles que l'Assistant, à l'aide de la bibliothèque d'intégration de 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.
• Suppression:supprimez un ensemble de raccourcis dynamiques avec removeDynamicShortcuts(). Supprimez tous les raccourcis dynamiques avec removeAllDynamicShortcuts().

Pour en savoir plus sur l'exécution d'opérations sur les raccourcis, consultez la page 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)

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

Ajouter la bibliothèque d'intégration de 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 pouvant être affichés sur les surfaces Android, telles que le lanceur d'applications, et sur les surfaces Google, comme l'Assistant. Cette bibliothèque permet aux utilisateurs de découvrir vos raccourcis pour accéder rapidement à des contenus spécifiques ou des actions de rejeu dans votre application.

Par exemple, une application de chat peut envoyer un raccourci dynamique pour un contact nommé "Alex" après qu'un utilisateur a envoyé un message à cette personne. Une fois le raccourci dynamique envoyé, si l'utilisateur demande à l'Assistant "Hey Google, envoie un message à Alex sur ExempleApp", l'Assistant peut lancer ExampleApp et le configurer automatiquement pour envoyer un message à Alex.

Les raccourcis dynamiques transmis avec cette bibliothèque ne sont pas soumis aux limites de raccourcis appliquées à chaque appareil. Cela permet à votre application d'envoyer un raccourci chaque fois qu'un utilisateur effectue une action associée dans votre application. En déployant des raccourcis fréquents, vous permettez à Google de comprendre les habitudes d'utilisation de votre utilisateur et de lui suggérer des raccourcis pertinents d'un point de vue contextuel.

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

La bibliothèque d'intégration de raccourcis Google n'offre aucune fonctionnalité adressable. L'ajout de cette bibliothèque à votre application permet aux surfaces Google d'utiliser les raccourcis transmis par votre application à l'aide de ShortcutManagerCompat.

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

1. Mettez à jour votre fichier gradle.properties pour qu'il soit compatible avec les bibliothèques AndroidX:

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

2. Dans app/build.gradle, ajoutez des dépendances pour la bibliothèque d'intégration de 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 transférer des raccourcis dynamiques pouvant être affichés dans le lanceur d'applications et sur 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 s'affichent dans les lanceurs d'applications 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 est compatible avec l'épinglage des raccourcis dans l'application.

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

   1. Si le raccourci existe, créez un objet ShortcutInfo ne contenant que l'ID du raccourci existant. Le système trouve et épingle automatiquement toutes les autres informations liées au raccourci.
   2. Si vous épinglez un nouveau raccourci, créez un objet ShortcutInfo contenant un ID, un intent et un libellé abrégé pour le nouveau raccourci.

3. Épinglez le raccourci dans le lanceur d'applications de l'appareil en appelant requestPinShortcut(). Au cours de ce processus, vous pouvez transmettre un objet PendingIntent, qui avertit votre application uniquement lorsque le raccourci a bien été épinglé.

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

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

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

Créer une activité de raccourci 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 illustre 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 lance 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 relaie à l'activité en cours d'exécution précédente à 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 que l'application est lancée. Cette méthode est efficace, car elle aide vos utilisateurs à créer un raccourci dans le cadre de leur workflow ordinaire.

Tester les raccourcis

Pour tester les raccourcis de votre application, installez-la sur un appareil doté d'un lanceur d'applications compatible. 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 cette application.
• Faites glisser un raccourci pour l'épingler dans le lanceur d'applications de l'appareil.