Les actions de conversation ont été abandonnées le 13 juin 2023. Pour en savoir plus, consultez Abandon de la fonctionnalité Conversation.

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

Requêtes Canvas

Pour relayer des informations à votre application Web, vous devez envoyer une réponse Canvas à partir de votre logique de conversation. Une réponse Canvas peut effectuer l'une des opérations suivantes:

Afficher l'application Web en plein écran sur l'appareil de l'utilisateur
Transmettre les données pour mettre à jour l'application Web

Les sections suivantes décrivent comment renvoyer une réponse Canvas pour chaque scénario.

Activer Interactive Canvas

Vous devez configurer votre action d'une manière spécifique pour utiliser Interactive Canvas. La création d'une action qui utilise Interactive Canvas nécessite une configuration supplémentaire dans la console Actions (et, pour le SDK Actions, des modifications de votre fichier settings.yaml). Pour découvrir la procédure complète de création et de configuration d'une action Interactive Canvas avec le SDK Actions, consultez la section Créer un projet.

Si vous utilisez Actions Builder, suivez ces étapes supplémentaires pour activer Interactive Canvas:

Si vous n'avez pas sélectionné la fiche Game (Jeu) sur l'écran What type of Action do you want to build? (Quel type d'action souhaitez-vous compiler ?), cliquez sur Deploy (Déployer) dans la barre de navigation supérieure. Sous Informations supplémentaires, sélectionnez la catégorie Jeux et divertissements. Cliquez sur Enregistrer.
Cliquez sur Develop (Développer) dans la barre de navigation supérieure de la console Actions.
Cliquez sur Interactive Canvas (Canevas interactif) dans le panneau de navigation de gauche.
Sous Do you want your Action to use Interactive Canvas? (Voulez-vous que votre action utilise Interactive Canvas ?), sélectionnez l'une des options suivantes :
- Activez Interactive Canvas avec le traitement du webhook de serveur. Cette option repose sur le webhook pour accéder à certaines fonctionnalités et utilise fréquemment onUpdate() pour transmettre des données à l'application Web. Lorsqu'elle est activée, les correspondances d'intent sont gérées dans des scènes, et vous pouvez choisir d'appeler le webhook avant de passer à une autre scène ou de terminer la conversation.
- Activez Interactive Canvas avec le traitement client. Cette option vous permet de déplacer la logique de traitement du webhook vers l'application Web et de limiter les appels de webhook aux seules fonctionnalités de conversation qui l'exigent, comme l'association de comptes. Lorsque cette option est activée, vous pouvez utiliser expect() pour enregistrer des gestionnaires d'intent côté client.
Facultatif: Saisissez l'URL de votre application Web dans le champ Définir l'URL de votre application Web par défaut. Cette action ajoute une réponse Canvas par défaut avec le champ d'URL à votre appel principal.
Cliquez sur Enregistrer.

Lorsque vous utilisez le SDK Actions, procédez comme suit pour activer Interactive Canvas:

Définissez le champ category de votre fichier settings.yaml sur GAMES_AND_TRIVIA pour décrire au mieux votre action et aider les utilisateurs à la découvrir.
Définissez le champ usesInteractiveCanvas de votre fichier settings.yaml sur true.

Vérifier la capacité de la surface

Le framework Interactive Canvas ne s'exécute que sur les appareils dotés de l'Assistant qui fournissent une interface visuelle. Votre action doit donc vérifier la fonctionnalité INTERACTIVE_CANVAS sur l'appareil de l'utilisateur. Lorsque vous définissez des requêtes dans Actions Builder, vous pouvez spécifier une liste de fonctionnalités de l'appareil dans le champ selector de l'objet candidates. Le sélecteur d'invite sélectionne l'invite la plus adaptée à la capacité de l'appareil de l'utilisateur.

Pour renvoyer une réponse Canvas, la logique de votre action doit procéder comme suit:

Vérifiez que l'appareil de l'utilisateur est compatible avec la fonctionnalité INTERACTIVE_CANVAS. Si c'est le cas, envoyez une réponse Canvas à l'utilisateur.
Si la fonctionnalité Interactive Canvas n'est pas disponible, vérifiez si l'appareil de l'utilisateur est compatible avec la fonctionnalité RICH_RESPONSE. Si c'est le cas, envoyez plutôt une réponse enrichie.
Si la fonctionnalité de réponse enrichie n'est pas disponible, envoyez à l'utilisateur une réponse simple.

Les extraits de code suivants renvoient la réponse appropriée en fonction des fonctionnalités de l'appareil de l'utilisateur:

YAML

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - INTERACTIVE_CANVAS
    canvas:
      url: 'https://example.web.app'
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    content:
      card:
        title: Card title
        text: Card Content
        image:
          url: 'https://example.com/image.png'
          alt: Alt text
        button:
          name: Link name
          open:
            url: 'https://example.com/'
  - first_simple:
      variants:
        - speech: Example simple response.

JSON

{
  "candidates": [
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "INTERACTIVE_CANVAS"
          ]
        }
      },
      "canvas": {
        "url": "https://example.web.app"
      }
    },
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "RICH_RESPONSE"
          ]
        }
      },
      "content": {
        "card": {
          "title": "Card title",
          "text": "Card Content",
          "image": {
            "url": "https://example.com/image.png",
            "alt": "Alt text"
          },
          "button": {
            "name": "Link name",
            "open": {
              "url": "https://example.com/"
            }
          }
        }
      }
    },
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Example simple response."
          }
        ]
      }
    }
  ]
}

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");
if (supportsInteractiveCanvas) {
  // Respond with a Canvas response
  conv.add(new Canvas({
    url: 'https://example.web.app',
  }));
} else if (supportsRichResponse) {
  // Respond with a rich response
  conv.add(new Card({
    title: 'Card title',
    image: new Image({
      url: 'https://example.com/image.png',
      alt: 'Alt text',
    }),
    button: new Link({
      name: 'Link name',
      open: {
        url: 'https://example.com/',
      },
    }),
  }));
} else {
  // Respond with a simple response
  conv.add('Example simple response.');
}

Afficher l'application Web

Une action qui utilise Interactive Canvas inclut une application Web avec des visuels personnalisés que vous envoyez aux utilisateurs en tant que réponse. Une fois l'application Web affichée, les utilisateurs continuent d'interagir avec elle par commande vocale, textuelle ou tactile jusqu'à la fin de la conversation.

Votre première réponse Canvas doit contenir l'URL de l'application Web. Ce type de réponse Canvas indique à l'Assistant Google d'afficher l'application Web à cette adresse sur l'appareil de l'utilisateur. En règle générale, vous envoyez la première réponse Canvas immédiatement après que l'utilisateur a appelé votre action. Une fois l'application Web chargée, la bibliothèque Interactive Canvas se charge, et l'application Web enregistre un gestionnaire de rappel avec l'API Interactive Canvas.

Vous pouvez spécifier l'URL de votre application Web dans Actions Builder, comme illustré dans la capture d'écran suivante:

Si vous créez une invite qui inclut une réponse Canvas après avoir spécifié l'URL de l'application Web, Actions Builder remplit automatiquement le champ d'URL de la réponse Canvas. Pour en savoir plus sur la définition de l'URL de l'application Web dans la console, consultez la section Activer Interactive Canvas.

Les extraits de code suivants montrent comment créer des réponses Canvas qui affichent l'application Web à la fois dans Actions Builder et dans votre webhook:

YAML

candidates:
  - first_simple:
       variants:
         - speech: >-
             Welcome! Do you want me to change color or pause spinning? You can
             also tell me to ask you later.
     canvas:
       url: 'https://your-web-app.com'

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
          }
        ]
      },
      "canvas": {
        "url": "https://your-web-app.com"
      }
    }
  ]
}

Node.js

app.handle('welcome', (conv) => {
  conv.add('Welcome! Do you want me to change color or pause spinning? ' +
    'You can also tell me to ask you later.');
  conv.add(new Canvas({
    url: `https://your-web-app.com`,
  }));
});

JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.",
      "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
    },
    "canvas": {
      "data": [],
      "suppressMic": false,
      "url": "https://your-web-app.com"
    }
  }
}

Transmettre les données pour mettre à jour l'application Web

Après avoir envoyé la réponse Canvas initiale, vous pouvez utiliser des réponses Canvas supplémentaires pour fournir des mises à jour à data, que la logique personnalisée de votre application Web utilise pour apporter des modifications à votre application Web. Lorsque vous envoyez une réponse Canvas qui transmet des données à l'application Web, voici ce qui se produit:

Lorsque l'intent est mis en correspondance dans une scène, il déclenche un événement, et une réponse Canvas contenant un champ data avec une charge utile JSON est ensuite renvoyée en tant que réponse.
Le champ data est transmis à un rappel onUpdate et utilisé pour mettre à jour l'application Web.
Votre action de conversation peut envoyer une nouvelle réponse Canvas et fournir des informations dans le champ data pour envoyer de nouvelles mises à jour ou charger de nouveaux états.

Remarque :Si la valeur du champ url change dans les réponses de traitement suivantes, l'application Web est actualisée. Si la même valeur pour url est fournie ou si url est exclu dans une réponse ultérieure, l'application Web existante est conservée sur l'appareil.

Vous pouvez transmettre des données à votre application Web de deux manières:

Avec Actions Builder Actions Builder remplit automatiquement le champ data de la réponse Canvas avec les métadonnées nécessaires pour mettre à jour l'application Web.
Avec un webhook Si vous disposez d'un webhook, vous pouvez configurer une charge utile de données personnalisée pour mettre à jour l'application Web dans votre réponse Canvas.

Les sections suivantes décrivent comment transmettre des données via Actions Builder et un webhook.

Utiliser Actions Builder pour transmettre des données

Avec Actions Builder, vous n'avez pas besoin de définir un webhook pour gérer les métadonnées envoyées à votre application Web. À la place, lorsque vous configurez votre gestionnaire d'intents dans l'interface utilisateur d'Actions Builder, vous pouvez inclure une réponse Canvas. Un champ data est automatiquement renseigné avec les métadonnées nécessaires pour mettre à jour votre application Web, comme le nom de l'intent, les paramètres capturés à partir de l'entrée utilisateur et la scène actuelle.

Par exemple, le gestionnaire d'intent Guess suivant indique que vous souhaitez inclure une réponse Canvas:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}

Vous pouvez éventuellement ajouter l'extrait suivant au gestionnaire d'intents pour envoyer un message de synthèse vocale:

...
  - first_simple:
      variants:
        - speech: Optional message.

Actions Builder étend automatiquement la réponse Canvas avec des métadonnées pour mettre à jour l'application Web, comme indiqué dans les extraits suivants. Dans ce cas, l'utilisateur a deviné la lettre "a" dans un jeu d'énigme de mots:

YAML

candidates:
  - canvas:
      data:
        - google:
            intent:
              params:
                letter:
                  resolved: a
                  original: a
              name: guess
            scene: Game
      sendStateDataToCanvasApp: true

JSON

{
  "candidates": [
    {
      "canvas": {
        "data": [
          {
            "google": {
              "intent": {
                "params": {
                  "letter": {
                    "resolved": "a",
                    "original": "a"
                  }
                },
                "name": "guess"
              },
              "scene": "Game"
            }
          }
        ],
        "sendStateDataToCanvasApp": true
      }
    }
  ]
}

Cette réponse met à jour votre application Web avec la réponse de l'utilisateur et passe à la scène appropriée.

Utiliser votre webhook pour transmettre des données

Vous pouvez configurer manuellement le champ data des réponses Canvas dans votre webhook avec les informations d'état nécessaires pour mettre à jour votre application Web. Cette approche est recommandée si vous devez inclure une charge utile data personnalisée dans une réponse Canvas au lieu de ne transmettre que les métadonnées typiques nécessaires à la mise à jour de l'application Web.

Les extraits de code suivants montrent comment transmettre des données dans une réponse Canvas de votre webhook:

Node.js

app.handle('start_spin', (conv) => {
  conv.add(`Ok, I'm spinning. What else?`);
  conv.add(new Canvas({
    data: {
      command: 'SPIN',
      spin: true,
    },
  }));
});

JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Ok, I'm spinning. What else?",
      "text": "Ok, I'm spinning. What else?"
    },
    "canvas": {
      "data": {
        "command": "SPIN",
        "spin": true
      },
      "suppressMic": false,
      "url": ""
    }
  }
}

Consignes et restrictions

Lorsque vous créez votre action, tenez compte des consignes et restrictions suivantes pour les réponses Canvas:

Chaque gestionnaire de webhook de votre traitement doit inclure Canvas. Si la réponse du webhook n'inclut pas Canvas, votre application Web se ferme.
Il vous suffit d'inclure l'URL de votre application Web dans la première réponse Canvas que vous envoyez à l'utilisateur.
L'URL de réponse Canvas doit être valide et son protocole doit être https.
La taille de la réponse Canvas ne doit pas dépasser 50 Ko.