Cette page a été traduite par l'API Cloud Translation.

Intents personnalisés

Chaque application est différente, et toutes leurs fonctionnalités ne sont pas liées à un intent intégré d'actions dans l'application disponible. Si aucun intent intégré n'est disponible pour le fonctionnement de votre application, vous pouvez utiliser un intent personnalisé afin d'ajouter des actions dans votre application.

Comme les intents intégrés, les intents personnalisés suivent le schéma shortcuts.xml et servent de relais entre l'Assistant et les traitements que vous avez définis. Les intents personnalisés comportent également des paramètres d'intent que vous pouvez mapper à des paramètres de votre traitement correspondant.

Contrairement aux intents intégrés, les intents personnalisés requièrent des formats de requête pour décrire des exemples de requêtes susceptibles d'être formulées par un utilisateur. Cette approche diffère des intents intégrés, qui correspondent tous à des moyens d'expression habituels des intents par les utilisateurs.

Limites

Les restrictions suivantes s'appliquent aux intents personnalisés :

Le nom d'un intent personnalisé ne peut pas commencer par actions.intent.
Le nom d'un intent personnalisé ne peut pas être déjà utilisé par d'autres intents personnalisés de votre application.
Seuls certains types de données sont disponibles pour l'extraction des paramètres par l'Assistant Google (consultez la section Types compatibles).
Les intents personnalisés doivent contenir des exemples de formats de requête utilisables (consultez la section Formats de requête).
Chaque requête accepte un maximum de deux paramètres de texte. Cette limite ne s'applique pas aux autres types de données.
Les intents personnalisés ne sont compatibles qu'avec les paramètres régionaux en-US. De plus, les paramètres de langue de l'appareil et de l'Assistant doivent correspondre.

Types pris en charge

Les intents personnalisés acceptent les types schema.org suivants pour l'extraction des paramètres :

https://schema.org/Text
https://schema.org/Date
https://schema.org/Time
https://schema.org/Number

Définir des actions dans l'application avec des intents personnalisés

Comme pour les autres actions dans l'application qui utilisent des intents intégrés, vous devez définir un intent personnalisé dans l'élément <capability> du fichier shortcuts.xml.

Les fonctionnalités sont définies dans l'élément racine <shortcuts>. Au moment de définir votre élément <shortcuts>, veillez à inclure les espaces de noms des attributs auxquels vous souhaitez accéder, comme illustré dans l'exemple suivant :

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Précisez le nom de l'intent personnalisé dans l'attribut android:name et indiquez un fichier de ressources de formats de requête dans l'attribut queryPatterns.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Les noms d'intent personnalisés ne peuvent pas commencer par actions.intent, car cet espace de noms est réservé aux intents intégrés. À la place, lorsque vous nommez des intents personnalisés, utilisez le préfixe custom.actions.intent pour les distinguer des intents intégrés et des intents Android, qui fonctionnent différemment.

Indiquez pour chaque paramètre le type schema.org compatible qui définit le mieux le sens du paramètre. Par exemple, vous pouvez utiliser https://schema.org/Date pour définir la date à laquelle vous prévoyez de recevoir :

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

Définissez les raccourcis des intents personnalisés dans le fichier shortcuts.xml en utilisant le même format que les raccourcis des intents intégrés.

Le code suivant décrit une action dans l'application qui suit les formats de requête définis pour déclencher l'intent personnalisé SCHEDULE_APPOINTMENT et qui utilise un ensemble de valeurs défini, DRIVERS_LICENSE et VEHICLE_REGISTRATION, pour le paramètre apptType.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

Vous pouvez configurer des paramètres d'intent personnalisé à l'aide d'un inventaire intégré dont vous pouvez vous servir pour guider l'extraction d'entités vers un ensemble d'entités compatibles spécifiées dans shortcuts.xml.

Formats de requête

Chaque intent personnalisé que vous utilisez requiert un ensemble de requêtes de la part de l'utilisateur. Cette approche diffère des intents intégrés, pour lesquels les requêtes correspondent déjà à des moyens couramment employés par les utilisateurs pour exprimer des tâches qu'ils veulent accomplir ou des informations qu'ils recherchent.

Dans un fichier de ressources Android (en général /res/values/strings.xml), définissez des formats de requête en tant qu'éléments dans un tableau de chaînes. Lorsque votre action dans l'application est appelée, l'Assistant Google compare la requête de l'utilisateur à vos formats de requête afin de l'adapter à l'intent de traitement de l'utilisateur. Chaque format de requête que vous fournissez représente une expression que vous estimez valide pour l'intent personnalisé correspondant.

Si vous définissez des formats de requête pour des intents personnalisés, attendez-vous à ce que chaque modèle suive un appel explicite comme "ouvre l'appli XXX et" ou "lance l'appli XXX et". Prenons l'exemple des requêtes utilisateur suivantes :

"Hey Google, ouvre l'application de jeu XXX et commence à préparer un gâteau."
"Hey Google, ouvre l'application de jeu XXX et commence à préparer une tarte aux pommes."
"Hey Google, lance l'application de jeu XXX et prépare cinq gâteaux."
"Hey Google, utilise l'application de jeu XXX pour préparer cinq fois un gâteau."

Pour répondre aux requêtes utilisateur, définissez des formats de requête contenant la partie de la requête qui suit l'appel. En ce qui concerne les informations que vous souhaitez extraire de la requête (comme du texte ou un nombre fourni par l'utilisateur), attribuez des valeurs au paramètre d'intent correspondant avec des espaces réservés dans le format de requête.

Pour définir un paramètre dans un format de requête, ajoutez $ au nom du paramètre dans le format. Par exemple, pour créer une valeur d'espace réservé pour un paramètre tel que <parameter name="date1" ... (dans actions.xml) ou <parameter android:name="date1" ... (dans shortcuts.xml), utilisez $date1.

Le code suivant décrit les formats de requête correspondant aux requêtes utilisateur précédentes, et extrait les valeurs des noms d'éléments et le nombre d'éléments à créer :

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Les formats de requête sont compatibles avec les conditions (par exemple, set (an)? appointment $date $time). Dans ce cas, les requêtes "fixer le rendez-vous aujourd'hui à midi" et "fixer un rendez-vous aujourd'hui à midi" sont toutes deux valides.