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 fonctionnalité [actions.intent.GET_FOOD_OBSERVATION
][] dans votre application en
en demandant "Hey Google, demande ExempleApp qu'est-ce que j'ai mangé 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 indique 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 :
Dans le fichier manifeste de votre application (
AndroidManifest.xml
), recherchez une activité dont les filtres d'intent sont définis sur l'actionandroid.intent.action.MAIN
et la catégorieandroid.intent.category.LAUNCHER
.Ajoutez une référence à
shortcuts.xml
dansAndroidManifest.xml
en utilisant une balise<meta-data>
dans l'élémentActivity
qui contient des filtres d'intent pourMAIN
etLAUNCHER
. 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
etlongLabel
. 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 à unecapability
à 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'IDshortcutId
est transmis à l'intent à la place de la valeur de requête brute.Les raccourcis d'éléments
Entity
ne définissent pas d'attributsintent
,shortLabel
nilongLabel
. 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".
Balise shortcuts.xml | Contenue dans | Attributs |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
S'applique uniquement aux appels d'applications au premier plan |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
S'applique uniquement à l'inventaire intégré |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
S'applique uniquement aux segments d'applications Android |
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
: ID de l'action d'intent intégré (par exemple, [actions.intent.GET_FOOD_OBSERVATION
][]). Pour obtenir la liste des les intents intégrés, 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 estACTION_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 :
Modèle | Valeurs | Valeur développée |
---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} |
"foo": "123" |
https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} |
"foo": "123" |
myapp://example/123 |
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
. Pour les actions dans les applications, ce champ n'est utilisé que pour
activer [appel d'application au premier plan][] pour un 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 exempletext/*
. 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émentcapability
.
<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".
Balise shortcuts.xml | Contenue dans | Attributs |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
S'applique uniquement à la correspondance des paramètres d'énumération. |
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
: attributandroid:name
de lacapability
à laquelle ceshortcut
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émentcapability
auquel associer ce raccourci. Exemple :exercise.name
.android:value
: valeur pourentity
. Il peut s'agir d'un élémententity
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 estsameAs
android:value
: valeur de l'URLsameAs
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
ettargetPackage
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émentintent
. 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, commande un latte sur ExempleAppli", 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, commande un latte Exempled'Appli", 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.