Les actions de conversation seront abandonnées le 13 juin 2023. Pour en savoir plus, consultez Abandon des actions de conversation.

Associations à l'Assistant

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Vous pouvez générer une URL qui renvoie directement à un intent spécifique de votre action. Les utilisateurs qui cliquent sur un lien de l'Assistant (auparavant appelé "lien d'action") dans un navigateur Web ou mobile sont redirigés vers l'Assistant sur leur appareil, où ils interagissent directement avec votre action.

Les liens de l'Assistant sont différents des liens Web de répertoire, qui dirigent l'utilisateur vers la page de votre action dans le répertoire de l'Assistant.

Voici quelques situations dans lesquelles les liens de l'Assistant peuvent être utiles:

  • Rediriger les utilisateurs vers des instructions vocales à partir d'un site Web
  • Rediriger les utilisateurs vers un service client à partir d'une page d'aide
  • Associer les utilisateurs à un intent de mise à jour afin qu'ils puissent accepter vos futures mises à jour

Vous pouvez générer des associations avec l'Assistant à partir de votre projet dans la console Actions. Les liens de l'Assistant sont disponibles via tous les canaux de déploiement (alpha, bêta et production). Par exemple, si votre lien Assistant est activé dans la version alpha de votre action, il est disponible pour les testeurs alpha.

Pour générer une URL pour une action, procédez comme suit:

  1. Dans la console Actions, accédez à Déployer > Associations à l'Assistant.
  2. Dans le champ Intent, sélectionnez l'intent pour lequel vous souhaitez générer un lien.
  3. Activez l'option Voulez-vous activer l'association pour intent_name ?.
  4. (Facultatif) Dans la section Paramètres de la campagne, saisissez les informations que vous souhaitez capturer en plus dans le lien en tant que paramètres d'URL.
  5. (Facultatif) Saisissez un titre de lien. Utilisez ce titre pour décrire ce que fait l'action. Par exemple, si votre action entraîne un flux de transactions pour acheter des billets pour un concert, le titre de votre lien peut être "acheter des billets de concert".

Après avoir saisi vos informations, vous pouvez afficher et copier l'URL ou l'extrait de code généré pour le lien de l'Assistant. Utilisez le lien de l'Assistant vers l'endroit où vous souhaitez rediriger les utilisateurs vers cette action.

Vous pouvez tester les liens de l'Assistant pour n'importe quel intent (principal ou personnalisé, avec ou sans paramètres) via le simulateur ou sur un appareil.

Pour tester le lien de l'Assistant sur un appareil, procédez comme suit:

  1. Générez le lien de l'Assistant dans la console Actions.
  2. Envoyez-vous le lien de l'Assistant en tant qu'URL dans un e-mail, un message de chat ou un autre format.
  3. Sur un appareil avec Assistant Google intégré, connectez-vous au compte avec lequel vous avez créé votre projet Actions.
  4. Sur le même appareil, cliquez sur le lien de l'Assistant que vous vous êtes envoyé.

Une fois que vous avez confirmé que l'Assistant fonctionne comme prévu, vous devez redéployer votre action pour que le lien soit disponible pour vos utilisateurs.

Les liens de l'Assistant peuvent éventuellement contenir un intent et des paramètres dans l'URL. Utilisez la section Paramètres de la campagne pour ajouter des paramètres de campagne.

Lorsqu'un lien Assistant ne contient aucun paramètre supplémentaire, l'Assistant Google associe l'intent MAIN (actions.intent.MAIN) de votre action avec le comportement suivant:

  • Si vous n'avez pas activé explicitement l'intent MAIN dans le lien Assistant, l'Assistant correspond à l'intent principal sans paramètre, comme pour "Talk to app_name".
  • Si vous avez explicitement activé l'intent MAIN, l'Assistant transmet les paramètres à vos actions.

Voici un exemple d'URL de lien avec l'Assistant utilisant l'intent MAIN sans paramètres supplémentaires:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

La syntaxe générale de l'URL d'un lien vers l'Assistant est la suivante:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Les paramètres d'URL que vous pouvez définir sont décrits dans le tableau suivant:

Paramètre d'URL Description
$action_id Identifiant numérique de l'action.
$intent Nom complet d'un intent intégré ou d'un utilisateur
$param Nom complet d'un paramètre d'intent spécifié dans le package "Action".
$value Valeur encodée en URL du type déclaré pour $param dans le package d'action.
$utm_param Liste d'un ou de plusieurs types de paramètres UTM. Les valeurs valides incluent : utm_source, utm_medium, utm_campaign, utm_term et utm_content.
$utm_value Valeur de chaîne du paramètre UTM.

Si le lien de l'Assistant contient un intent intégré (l'intent commence par actions.intent.), l'Assistant Google tente d'extraire les paramètres d'intent intégrés de l'URL et les transmet à votre action. Tous les paramètres que l'Assistant ne comprend pas comme étant des paramètres d'intent intégrés sont supprimés.

Pour les actions de conversation, l'Assistant envoie ces paramètres à votre traitement dans le message AppRequest.

L'exemple suivant montre comment spécifier une URL de lien de l'Assistant qui inclut un intent intégré avec un seul paramètre d'intent:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

Pour les intents utilisateur, l'Assistant Google extrait uniquement les paramètres définis par votre action dans l'intent et ignore tous les autres paramètres.

L'exemple suivant montre comment spécifier une URL de lien de l'Assistant qui inclut un intent utilisateur:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Pour l'exemple d'URL ci-dessus, dans AppRequest, l'Assistant ajoute un objet JSON comme suit:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

Les paramètres UTM sont des chaînes que l'Assistant Google envoie à votre action lorsque les utilisateurs cliquent sur un lien Assistant. Vous pourrez utiliser les informations contenues dans ces chaînes plus tard pour les analyses.

Les paramètres UTM que l'Assistant envoie à votre action sont les suivants:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

L'exemple suivant montre comment spécifier une URL de lien de l'Assistant qui inclut des paramètres UTM:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Pour l'exemple d'URL ci-dessus, l'Assistant ajoute les arguments suivants dans le message AppRequest:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Les liens enrichis de l'Assistant vous permettent d'améliorer la visibilité de votre action sur votre site Web grâce à assist.js. Les utilisateurs peuvent essayer votre action et associer leur compte Google à votre service à l'aide de l'association de comptes.

Lorsqu'un utilisateur visite votre site Web, un bouton "Essayer avec l'Assistant Google" s'affiche, ce qui déclenche le processus d'association de l'assistant enrichi.

Si vous activez l'association de comptes pour votre action, les utilisateurs pourront accéder à votre action sur tous leurs appareils avec Assistant Google intégré. De plus, les utilisateurs peuvent associer leur compte avec votre service à leur compte Google, ce qui leur permet de bénéficier d'une expérience plus personnalisée.

Lorsqu'elle est utilisée avec l'association de comptes, l'association enrichie utilise votre URL d'autorisation, définie dans votre projet dans la console Actions. Pour en savoir plus, consultez la documentation sur l'association de comptes.

Prérequis

Pour utiliser les liens enrichis de l'Assistant, vous avez besoin des éléments suivants:

Développement local

Pour inclure un lien enrichi avec l'Assistant sur votre site Web, procédez comme suit:

  1. Incluez la bibliothèque JavaScript suivante sur votre page, en remplaçant <PROJECT_ID> par l'ID de votre projet Actions:

    <script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
</script>

  2. Ajoutez la balise HTML suivante quelque part sur votre page. Le bouton "Essayer l'Assistant Google" intégré s'affiche:

    <google-assistant-link-group>
  <!-- One or more <google-assistant-link> tags -->
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>

Déclenchement proactif

Si vous souhaitez que le parcours d'association enrichi avec l'Assistant démarre automatiquement lorsque des utilisateurs visitent votre page pour la première fois, utilisez la balise <google-assistant-proactive-link>. Lorsque vous appliquez cette balise, le lien est activé sans que les utilisateurs n'aient sélectionné le bouton intégré la première fois qu'ils visitent l'application.

  1. Ajoutez un id à votre balise de groupe d'associations à l'Assistant:

    <google-assistant-link-group id="my-group">
  <!-- One or more <google-assistant-link> tags -->
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>

  2. Insérez une balise <google-assistant-proactive-action-link> sur votre page Web et définissez son attribut groupId sur id :

    <google-assistant-link-group id="my-group">
  <!-- One or more <google-assistant-link> tags -->
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>

<google-assistant-proactive-link
groupId="my-group">
</google-assistant-proactive-link>

Deployment

Les liens Assistant détaillés ne fonctionnent que pour les domaines que vous possédez et que vous avez validés avec Google. Lorsque vous développez en local, cette condition n'est pas requise. Vous devez avoir accès au projet Actions, être connecté à votre compte Google et définir le paramètre de requête dev=true dans votre tag de script.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Pour déployer votre action avec les liens enrichis de l'Assistant:

  1. Enregistrez votre domaine public dans la console Actions sous Deploy > Brand Verification > Connect Site.

  2. Supprimez le paramètre de requête dev=true du script:

    <script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
</script>

Restrictions et bonnes pratiques

Les restrictions et bonnes pratiques suivantes s'appliquent pour que l'URL du lien de l'Assistant puisse être distribuée et référencée en dehors de l'annuaire ou d'autres services Google:

  • Continuez à accepter tous vos liens avec l'Assistant. Si vous distribuez un lien Assistant qui ne fonctionne plus, votre projet Actions peut être signalé comme non opérationnel et supprimé.

  • La publication d'un lien signifie que vous acceptez le déclenchement depuis des sources non fiables. Pour toute action associée, vous devez explicitement le demander à l'utilisateur avant d'effectuer une action réelle. Par exemple, une action qui désactive un système de maison connectée doit demander à l'utilisateur : Voulez-vous vraiment désactiver $applianceName ?

    Dans ce contexte, une action réelle est une action qui affecte les services, données, appareils, réseaux, ordinateurs ou API de l'utilisateur. par exemple pour envoyer un e-mail, effectuer une transaction, modifier l'état d'un appareil électroménager connecté, créer un abonnement ou mettre à jour un contenu.