Créer un fichier shortcuts.xml

Après avoir identifié la fonctionnalité de votre application ainsi que l'intent intégré à mettre en œuvre, déclarez les intents intégrés compatibles en définissant un élément capability dans un fichier de ressources shortcuts.xml. La déclaration d'un intent intégré en tant que capability permet d'enregistrer la compatibilité de cet intent sémantique dans votre application. Par ailleurs, cette démarche active le traitement des requêtes vocales de l'intent à l'aide de l'Assistant Google.

L'Assistant utilise le traitement du langage naturel pour extraire les paramètres d'une requête utilisateur. Le document de référence sur les intents intégrés recense les champs que chaque intent intégré peut extraire à partir d'une requête utilisateur associée. Par exemple, si un utilisateur appelle la capacité [actions.intent.GET_FOOD_OBSERVATION][] de votre application en disant "Hey Google, demande à ExampleApp ce que j'ai mangé pour déjeuner vendredi dernier", l'Assistant extrait les paramètres d'intent intégré suivants de la requête de l'utilisateur:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

L'Assistant transmet les paramètres d'intent intégré à l'intent de traitement défini dans capability. Un ou plusieurs éléments intent peuvent être définis dans une capacité afin de prendre en compte les différentes manières dont un utilisateur peut appeler un intent intégré. Par exemple, vous pouvez définir un intent de traitement qui nécessite les deux paramètres d'intent intégré de l'exemple précédent. Vous pouvez ensuite définir un deuxième intent exigeant un seul paramètre d'intent intégré (foodObservation.forMeal), qui génère des rapports sur tous les repas d'un jour donné (par exemple : "Hey Google, demande à ExempleApp ce que j'ai mangé pour le déjeuner").

Présentation

Pour configurer les actions dans les applications, vous devez utiliser un fichier shortcuts.xml placé dans le répertoire res/xml de votre projet d'application, puis créer une référence à shortcuts.xml dans le fichier manifeste de votre application. Voici comment procéder :

1. Dans le fichier manifeste de votre application (AndroidManifest.xml), recherchez une 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 une référence à shortcuts.xml dans AndroidManifest.xml en utilisant une balise <meta-data> dans l'élément Activity qui contient des filtres d'intent pour MAIN et LAUNCHER. Voici comment :

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

L'exemple ci-dessus déclare une ressource XML pour le fichier xml/shortcuts.xml dans l'APK. Pour en savoir plus sur la configuration des raccourcis, consultez la page Créer des raccourcis statiques dans la documentation destinée aux développeurs Android.

La bibliothèque Jetpack androidx.core:core:1.6.0 (ou toute version ultérieure) est requise dans votre projet Android pour éviter les erreurs de compilation lorsque vous définissez les capacités d'actions dans l'application dans le fichier shortcuts.xml. Pour en savoir plus, consultez Premiers pas avec Android Jetpack.

Raccourcis statiques

Lorsque vous définissez votre élément capability, vous pouvez en étendre la fonctionnalité en déclarant des éléments shortcut statiques dans shortcuts.xml. Les raccourcis statiques sont ingérés par l'Assistant lorsque vous importez une version dans la Google Play Console. Les raccourcis statiques ne peuvent être créés et mis à jour qu'à partir de nouvelles versions. Ce faisant, ils sont particulièrement utiles pour mettre en avant des activités et des contenus courants dans votre application.

Vous pouvez activer les fonctionnalités d'Actions dans les applications suivantes à l'aide de raccourcis statiques :

• Raccourcis de capacité. Créez des raccourcis pour lancer une instance de votre élément capability contenant des valeurs de paramètres d'intent prédéfinies. Par exemple, vous pouvez déclarer un raccourci d'application "Démarrer une course à pied" qui appelle la capacité d'intent intégré START_EXERCISE dans votre application de fitness.

  Ces raccourcis contiennent les attributs intent, shortLabel et longLabel. Ils peuvent donc être suggérés et traités sous forme de chips sur des surfaces proactives telles que l'Assistant, ou en appuyant de manière prolongée sur l'icône d'une appli dans les lanceurs d'applications Android. Un raccourci d'action peut également servir de raccourci d'entité (voir ci-dessous) en l'associant à une capability à l'aide d'une balise <capability-binding>.

• Raccourcis d'entité. Les raccourcis d'entité fournissent une liste de valeurs de paramètres pris en charge avec le traitement des requêtes vocales pour les éléments capability. Prenons l'exemple d'un raccourci d'entité contenant plusieurs types d'activités ("randonnée", "course", etc.) lié au paramètre d'intent intégré exercise.name de la capacité START_EXERCISE. Lorsqu'un énoncé d'utilisateur correspond à une entité, l'ID shortcutId est transmis à l'intent à la place de la valeur de requête brute.

  Les raccourcis d'éléments Entity ne définissent pas d'attributs intent, shortLabel ni longLabel. Par conséquent, ils ne sont pas suggérés sur les surfaces proactives. Pour en savoir plus, consultez la section Inventaire intégré pour les actions dans les applications.

Schéma de capacité

Le tableau suivant décrit le schéma d'Actions dans les applications pour les éléments capability dans shortcuts.xml. Lorsque vous ajoutez une balise, tous ses attributs sont obligatoires, sauf s'ils sont marqués comme "facultatifs".

Description du schéma de capacité

Cette section décrit les éléments de schéma capability.

<capability>

Élément capability qui définit l'intent d'action dans l'application que votre appli prend en charge. Chaque balise <capability> de votre fichier shortcuts.xml doit fournir au moins un élément <intent> pour gérer l'exécution de l'action.

Attributs :

• android:name: identifiant de l'action d'intent intégré (par exemple, [actions.intent.GET_FOOD_OBSERVATION][]). Pour obtenir la liste des intents intégrés pris en charge, consultez la documentation de référence sur les intents intégrés.
• app:queryPatterns : ressource de tableau de chaînes de requêtes attendues de la part de l'utilisateur pour cet intent. Cet attribut ne s'applique qu'aux intents personnalisés, puisque les intents intégrés incluent déjà des modèles d'expressions courantes employées par les utilisateurs pour décrire les tâches qu'ils tentent d'effectuer ou les informations qu'ils recherchent.

<intent>

Élément intent Android qui définit le mode de traitement d'une requête utilisateur à l'aide de fonctionnalités intégrées à l'application. Les développeurs peuvent inclure plusieurs balises <intent> dans un élément capability. L'Assistant tente d'exécuter une requête utilisateur en s'appuyant sur le premier <intent> d'une capability pour laquelle tous les paramètres requis sont fournis.

Attributs :

• android:action : type d'Action de l'intent. La valeur par défaut est ACTION_VIEW.
• android:targetClass : classe d'activité cible, par exemple "com.example.exercise.ExerciseActivity"
• android:targetPackage : package contenant la classe d'activité cible, par exemple "com.example.exercise
• android:data : ce champ est remplacé par <url-template> lorsque cette balise est déclarée dans l'intent.

<url-template>

Modèle permettant de créer un URI de lien profond à ouvrir sur l'appareil. Celui-ci peut être développé avec des paramètres d'intent intégrés si tous les paramètres requis sont disponibles. Des exemples de modèle d'URL HTTP sont disponibles dans l'article Wikipédia sur les modèles d'URL. Le format utilisé respecte la spécification de modèle d'URI RFC6570.

Voici quelques exemples de valeurs de modèles d'URL :

Pour en savoir plus sur la configuration des modèles d'URL, consultez la section Modèles d'URL dans le traitement.

<extra>

Définit les données supplémentaires d'un intent. En ce qui concerne les Actions dans les applications, ce champ sert uniquement à activer l'[appel de l'application au premier plan][] pour un élément capability.

<parameter>

Mappe un paramètre d'intent intégré avec des valeurs des paramètres d'intent. Pour en savoir plus, consultez la section Données et correspondance des paramètres.

Attributs :

• android:name : nom du paramètre d'intent intégré à associer à ce paramètre d'intent. Ce nom doit être un champ feuille du paramètre d'intent intégré (par exemple, foodObservation.aboutFood.name).
• android:key : clé définie par les développeurs pour une valeur de paramètre d'intent intégré (par exemple : contact_name pour le paramètre d'intent intégré message.recipient.name).
• android:mimeType : type MIME du paramètre, par exemple text/*. Ce champ n'est obligatoire que pour les paramètres d'intents personnalisés.
• android:required : indique si la requête de l'utilisateur doit inclure ce paramètre pour que cet intent soit utilisé aux fins de traitement. Lorsque le paramètre est indisponible, l'Assistant tente de répondre à la requête utilisateur à l'aide de l'intent suivant défini pour l'élément capability.

<shortcut-fulfillment>

Spécifie qu'un intent défini dans un raccourci d'inventaire intégré pour un paramètre donné doit être utilisé pour le traitement. Pour en savoir plus, consultez Traitement à l'aide d'intents de raccourcis.

<parameter> (pour <shortcut-fulfillment>)

Attribut facultatif mappant un seul paramètre d'intent intégré au traitement du raccourci d'inventaire intégré. Pour en savoir plus, consultez Traitement à l'aide d'intents de raccourcis.

Attribut :

• android:name : nom du paramètre d'intent intégré à associer au traitement de raccourci d'inventaire intégré. Ce nom doit être un champ feuille du paramètre d'intent intégré (par exemple, menuItem.name).

<slice>

Permet à l'Assistant d'intégrer le résultat d'une requête correspondant à cet élément capability en tant que segment d'application Android. Pour en savoir plus, consultez la rubrique Intégrer les actions dans les applications avec les segments d'application Android.

Schéma de raccourci

Le tableau suivant décrit les attributs des éléments shortcut utilisés pour activer les fonctionnalités des Actions dans les applications. Lorsque vous ajoutez une balise, tous ses attributs sont obligatoires, sauf s'ils sont marqués comme "facultatifs".

Description du schéma de raccourci

Cette section décrit les éléments de schéma shortcut.

<shortcut>

Balise <shortcut> Android définie dans shortcuts.xml avec certains attributs pertinents pour les actions dans les applications. Les valeurs de chaîne des champs shortcutShortLabel et shortcutLongLabel sont référencées via les ressources de chaîne de l'APK.

Attributs :

• android:shortcutId : identifiant de ce raccourci.
• android:shortcutShortLabel : ressource de chaîne représentant une brève expression de raccourci. Par exemple, "@string/callDavidShort" représentant la valeur "Appelle David".
• android:shortcutLongLabel : ressource de chaîne représentant une longue expression de raccourci. Par exemple, "@string/callDavidLong" représentant la valeur "Passe un appel audio à David".

<intent>

Intent Android associé à ce raccourci. Cet intent s'exécute lorsqu'un utilisateur lance ce raccourci par commande vocale ou tactile.

Les attributs d'intent pour shortcut sont identiques aux attributs d'intent pour capability.

<capability-binding>

Associe un élément shortcut à un élément capability d'Actions dans les applications. L'ajout de celui-ci à un élément shortcut permet son exécution vocale à l'aide de l'Assistant.

Attributs :

• android:key : attribut android:name de la capability à laquelle ce shortcut est lié. Exemple : actions.intent.START_EXERCISE.

<parameter-binding>

Attribut facultatif qui associe un élément shortcut à un paramètre unique d'un élément capability d'Actions dans les applications. Lorsqu'un élément parameter-binding est défini pour un élément shortcut, le raccourci peut être utilisé en vue de fournir une entité d'inventaire intégré à un paramètre d'intent intégré. Pour en savoir plus, consultez la section Inventaire intégré pour les actions dans les applications.

Attributs :

• android:key : nom du paramètre d'intent intégré d'élément capability auquel associer ce raccourci. Exemple : exercise.name.
• android:value : valeur pour entity. Il peut s'agir d'un élément entity unique ou d'une liste de ressources.

<extra>

Données du bundle extra pour le raccourci. sameAs est la seule donnée pertinente pour les éléments shortcut des actions dans les applications. L'URL sameAs se rapporte à une page Web de référence, qui identifie l'entité sans aucune ambiguïté. Permet de spécifier une valeur d'énumération si et seulement si le type de paramètre d'intent est un sous-type de schema.org/Enumeration. Ceci est obligatoire pour les champs de paramètre dont les types sont des sous-types de schema.org/Enumeration (par exemple : MealTypeBreakfast).

Attributs :

• android:key : la valeur prise en charge pour Actions dans les applications est sameAs
• android:value : valeur de l'URL sameAs

Pour en savoir plus, consultez la section Mettre en correspondance des valeurs de paramètres énumérées.

Options de traitement des intents

Vous devez définir des éléments intent dans une balise <capability> pour déclarer la manière dont l'Assistant répond aux commandes vocales de l'utilisateur qui correspondent à cette capacité (c'est-à-dire comment il les traite). Il existe plusieurs façons de configurer la manière dont un intent lance une destination de traitement dans votre application, en fonction de la structure de navigation de votre application.

Les options de traitement suivantes sont disponibles :

• Intents explicites : lancez un composant d'application spécifique en définissant les attributs targetClass et targetPackage pour l'intent. Cette méthode est recommandée pour le traitement des actions dans les applications.

• Liens profonds : lancez des destinations d'application à l'aide de liens profonds Android en définissant une balise <url-template> dans l'élément intent. Cette méthode est utile si la navigation dans votre application repose déjà sur des liens profonds.

• Données d'intent : vous pouvez fournir un URI de traitement dans l'attribut intent android:data. Ce champ est écrasé par les données <url-template> si cette balise est également définie dans l'intent.

Données et correspondance des paramètres

Par défaut, l'Assistant envoie à votre application les paramètres d'intent intégré extraits de la requête de l'utilisateur en tant que données extra de l'intent Android défini dans l'élément capability.

Vous pouvez également déclarer une balise <url-template> dans l'élément capability contenant des espaces réservés pour les paramètres dynamiques. Ce modèle est mappé vers l'une de vos activités Android, à l'aide d'une URL de liens vers une application, d'un schéma personnalisé ou d'une URL basée sur l'intent.

Utiliser des extras d'intent

L'exemple suivant illustre un intent explicite défini pour le traitement d'un élément capability :

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dans cet exemple, pour une requête utilisateur telle que "Hey Google, commence mon footing", l'application en question reçoit un intent qui appelle le composant : targetPackage, targetClass. Celui-ci reçoit un Extra avec key = "exercise", value = "Running".

Utiliser un modèle d'URL pour les liens profonds Android

Si votre application gère déjà les URL liées aux applications, vous pouvez utiliser des paramètres dynamiques pour définir une balise <url-template> dans l'intent, ce qui vous permet de générer des liens profonds Android aux fins de traitement. L'exemple suivant définit une balise <url-template> :

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dans l'exemple ci-dessus, pour une requête utilisateur telle que "Hey Google, commence mon footing", l'application reçoit l'URL générée: "myapp://start?exercise=Running".

Pour mapper le paramètre d'intent intégré à une position dans votre URL, utilisez l'attribut android:name de la balise <parameter>. Il correspond à la valeur android:key du modèle d'URL que vous souhaitez remplacer par les informations de l'utilisateur. La valeur android:key doit être présente dans votre <url-template> et entourée d'accolades ({}).

Assurer la correspondance des valeurs de paramètres énumérées

Certains paramètres d'intent intégré fournissent des valeurs énumérées à votre intent de traitement, à l'image des valeurs textuelles prises en charge de l'intent intégré RECORD_FOOD_OBSERVATION. Pour ces paramètres, l'Assistant associe la requête de l'utilisateur ("petit déjeuner") à une entité dont la valeur sameAs correspond à l'URL du schéma d'énumération (https://schema.googleapis.com/MealTypeBreakfast). de Google. Afin d'associer des valeurs énumérées pour une entity compatible, vous devez déclarer une association sameAs dans votre élément shortcut. L'exemple suivant illustre une association sameAs pour un raccourci d'entité intégrée :

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

Dans notre exemple, lorsque la capacité RECORD_FOOD_OBSERVATION déclenche une correspondance pour le type de repas "petit déjeuner", les éléments Extra suivants sont envoyés avec l'intent de traitement :

• key = "for_meal"
• value = "meal_breakfast"

Fonctionnalités

Les fonctionnalités d'Actions dans les applications suivantes sont disponibles dans shortcuts.xml.

Inventaire intégré pour les actions dans les applications

Pour certains paramètres d'intent intégré, les raccourcis peuvent servir à guider l'extraction d'entités vers un ensemble d'entités prises en charge (l'inventaire intégré) spécifiées dans shortcuts.xml. Pour en savoir plus, consultez la page dédiée à l'Inventaire intégré.

Intents personnalisés

Vous pouvez déclarer des intents personnalisés dans shortcuts.xml pour activer par commande vocale des fonctionnalités applicatives qui ne correspondent pas aux intents intégrés disponibles. Les intents personnalisés, qui présente pourtant des fonctions similaires à celles d'une définition d'intent intégré, nécessitent deux attributs supplémentaires dans shortcuts.xml :

• app:queryPatterns : ressource de tableau qui déclare les différents modèles de requête pour un intent personnalisé.

• android:mimeType : type de paramètre d'un intent personnalisé. Ce champ n'est pas obligatoire pour les intents intégrés, où le type de paramètre est connu. En ce qui concerne les paramètres d'intent personnalisés, un type sémantique pris en charge doit être déclaré.

Pour en savoir plus, consultez la section Intents personnalisés.