Associations à l'Assistant

Vous pouvez générer une URL qui renvoie directement vers un intent spécifique de votre action. Les utilisateurs qui cliquent sur un lien Assistant (anciennement 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 redirigent l'utilisateur vers la page de votre action dans le répertoire de l'Assistant.

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

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

Vous pouvez générer des liens vers l'Assistant depuis votre projet dans la console Actions. Les liens vers 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 > Liens de 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 dans le lien en tant que paramètres d'URL.
  5. (Facultatif) Saisissez le titre du lien. Utilisez ce titre pour décrire ce que fait l'action. Par exemple, si votre action redirige l'utilisateur vers un flux de transactions pour l'achat de billets pour un concert, le titre de votre lien peut être "acheter des places de concert".

Une fois que vous avez saisi vos informations, vous pouvez afficher et copier l'URL ou l'extrait de code générés pour le lien vers l'Assistant. Utilisez le lien de l'Assistant chaque fois que vous souhaitez rediriger les utilisateurs vers cette action spécifique.

Vous pouvez tester les associations à 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 vers l'Assistant sur un appareil, procédez comme suit:

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

Une fois que vous avez confirmé que le lien Assistant fonctionne comme prévu, vous devez redéployer votre action pour que vos utilisateurs puissent y accéder.

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 est associé à l'intent MAIN (actions.intent.MAIN) de votre action avec le comportement suivant:

  • Si vous n'avez pas explicitement activé l'intent MAIN dans le lien vers l'Assistant, celui-ci établit une correspondance avec l'intent principal sans aucun paramètre, comme pour "Parler à app_name".
  • Si vous avez explicitement activé l'intent MAIN, l'Assistant transmet les paramètres à vos actions.

Voici un exemple d'URL d'un lien Assistant utilisant l'intent MAIN sans paramètre supplémentaire:

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 d'actions.
$value Valeur encodée au format URL du type déclaré pour $param dans le package d'actions.
$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 Assistant contient un intent intégré (dont l'intent commence par actions.intent.), l'Assistant Google tente d'extraire tous les paramètres d'intent intégrés dans l'URL et les transmet à votre action. Tous les paramètres que l'Assistant ne comprend pas comme des paramètres d'intent intégré 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 vers l'Assistant incluant 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 n'extrait que 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 vers l'Assistant incluant 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 de l'Assistant. Vous pouvez utiliser les informations contenues dans ces chaînes ultérieurement à des fins d'analyse.

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

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

L'exemple suivant montre comment spécifier une URL de lien vers l'Assistant incluant 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 vers l'Assistant vous permettent d'améliorer la visibilité de votre action sur votre site Web, en utilisant assist.js. Les utilisateurs peuvent tester votre action et associer leur compte Google à votre service à l'aide de l'association de comptes.

Lorsqu'un utilisateur visite votre site Web, il voit un bouton "Essayer avec l'Assistant Google" qui déclenche le flux de liens de l'Assistant riche.

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

En cas d'association de comptes, les liens Rich Assistant utilisent 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.

Conditions préalables

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

Développement local

Pour inclure un lien Assistant enrichi 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 intégré "Essayer avec l'Assistant Google" se charge:

    <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 flux enrichi du lien vers l'Assistant se lance automatiquement lorsque les utilisateurs accèdent à votre page pour la première fois, utilisez la balise <google-assistant-proactive-link>. Lorsque vous appliquez cette balise, le lien s'active sans que les utilisateurs aient cliqué sur le bouton intégré lors de leur première visite.

  1. Ajoutez un id à la balise de votre groupe de liens 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>
    

Déploiement

Les liens Rich Assistant ne fonctionnent que pour les domaines dont vous êtes le propriétaire et que vous avez validés auprès de Google. Pour le développement en local, vous pouvez contourner cette exigence en accédant au projet Actions, en étant connecté à votre compte Google et en définissant 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 vers l'Assistant:

  1. Enregistrez votre domaine public dans la console Actions sous Déployer > Validation de la marque > Associer le 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 bonnes pratiques et restrictions suivantes s'appliquent afin que l'URL du lien Assistant puisse être distribuée et référencée en dehors de l'annuaire ou d'autres services Google:

  • Continuez pour assurer la compatibilité avec tous les liens vers l'Assistant. Si vous distribuez un lien vers l'Assistant qui ne fonctionne plus par la suite, votre projet Actions peut être signalé comme non opérationnel et retiré.
  • En publiant un lien, vous acceptez le déclenchement à partir de sources non fiables. Pour toutes les actions associées, vous devez confirmer explicitement auprès de l'utilisateur avant d'effectuer toute action dans le monde réel. Par exemple, une action qui éteint un appareil de la maison connectée doit inviter l'utilisateur à dire 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, vous pouvez envoyer un e-mail, effectuer une transaction, modifier l'état d'un appareil connecté, créer un abonnement ou mettre à jour un contenu.