Para redirecionar informações ao seu app da Web, é necessário enviar uma resposta Canvas
a partir da sua lógica de conversa. Uma resposta Canvas
pode:
- Renderizar o app da Web em tela cheia no dispositivo do usuário
- Transmitir dados para atualizar o app da Web
As seções a seguir descrevem como retornar uma resposta de Canvas para cada cenário.
Ativar tela interativa
É preciso configurar sua ação de uma maneira específica para usar a tela interativa.
A criação de uma ação que usa a tela interativa exige outra configuração
no Console do Actions e, para o SDK do Actions, modificações no
arquivo settings.yaml
. Para ver o procedimento completo para criar e
configurar uma ação de tela interativa com o SDK do Actions, consulte
Criar um projeto.
Ao usar o Actions Builder, siga estas outras etapas para ativar a tela interativa:
- Se você não tiver selecionado o card Jogo na tela Que tipo de ação você quer criar?, clique em Implantar na navegação superior. Em Informações adicionais, selecione a categoria Jogos e diversão. Clique em Salvar.
- Clique em Desenvolver na navegação da parte de cima do Console do Actions.
- Clique em Tela interativa na navegação à esquerda.
- Em Você quer que sua ação use a tela interativa?, selecione uma
das seguintes opções:
- Ativar a tela interativa com o fulfillment do webhook do servidor. Essa opção
depende do webhook para acessar determinados recursos e geralmente usa
onUpdate()
para transmitir dados ao app da Web. Quando ativada, as correspondências de intent são processadas em cenas, e é possível optar por chamar o webhook antes da transição para outra cena ou encerrar a conversa. - Ative a tela interativa com o fulfillment do cliente. Essa opção permite mover a lógica de fulfillment do webhook para o app da Web e limitar as chamadas de webhook apenas aos recursos de conversação que precisam dele, como a vinculação de contas. Quando ativada, você pode usar
expect()
para registrar gerenciadores de intent no lado do cliente.
- Ativar a tela interativa com o fulfillment do webhook do servidor. Essa opção
depende do webhook para acessar determinados recursos e geralmente usa
- Opcional: digite o URL do seu app da Web no campo Definir o URL padrão do seu app da Web. Essa ação adiciona uma resposta
Canvas
padrão com o campo de URL à invocação Main. - Clique em Salvar.
Ao usar o SDK do Actions, siga estas outras etapas para ativar a tela interativa:
- Defina o campo
category
no arquivosettings.yaml
comoGAMES_AND_TRIVIA
para descrever melhor e ajudar os usuários a descobrir sua ação. - Defina o campo
usesInteractiveCanvas
no arquivosettings.yaml
comotrue
.
Verificar a capacidade da superfície
O framework de tela interativa é executado apenas em dispositivos com o Google Assistente que oferecem
uma interface visual. Portanto, a ação precisa verificar o
recurso INTERACTIVE_CANVAS
no dispositivo do usuário. Ao definir comandos no Actions Builder,
você pode especificar uma lista de recursos do dispositivo no campo selector
do
objeto candidates
. O seletor de solicitações escolhe a opção mais
apropriada para a capacidade do dispositivo do usuário.
Para retornar uma resposta Canvas
, a lógica da sua ação precisa fazer o seguinte:
- Verifique se o dispositivo do usuário é compatível com o recurso
INTERACTIVE_CANVAS
. Em caso afirmativo, envie uma respostaCanvas
ao usuário. - Se o recurso de tela interativa não estiver disponível, confira se o dispositivo
do usuário oferece suporte ao recurso
RICH_RESPONSE
. Se isso acontecer, envie ao usuário uma resposta avançada. - Se o recurso de resposta avançada não estiver disponível, envie ao usuário uma resposta simples.
Os snippets a seguir retornam a resposta adequada com base nos recursos do dispositivo do usuário:
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.'); }
Renderizar o app da Web
Uma ação que usa a tela interativa inclui um app da Web com recursos visuais personalizados que você envia aos usuários como resposta. Depois que o app da Web é renderizado, os usuários continuam interagindo com ele por voz, texto ou toque até que a conversa termine.
Sua primeira resposta Canvas
precisa conter o URL do app da Web. Esse tipo de resposta
Canvas
instrui o Google Assistente a renderizar o app da Web nesse endereço
no dispositivo do usuário. Normalmente, você envia a primeira resposta Canvas
imediatamente após o usuário invocar sua ação. Quando o app da Web é carregado, a
biblioteca de tela interativa é carregada, e o app da Web registra um gerenciador de callback
com a API de tela interativa.
Você pode especificar o URL do seu app da Web no Actions Builder, conforme mostrado na captura de tela a seguir:
Se você criar uma solicitação que inclua uma resposta Canvas
depois de especificar o
URL do app da Web, o Actions Builder preencherá automaticamente o campo de URL da resposta Canvas
. Para saber
mais sobre como definir o URL do app da Web no console, consulte a seção
Ativar tela interativa.
Os snippets a seguir mostram como criar respostas Canvas
que renderizam
o app da Web no Actions Builder e no 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" } } }
Transmitir dados para atualizar o app da Web
Depois de enviar a resposta Canvas
inicial, é possível usar outras respostas Canvas
para fornecer atualizações a data
, que a lógica personalizada do app da Web usa
para fazer mudanças nele. Quando você envia uma resposta Canvas
que transmite
dados ao app da Web, as seguintes etapas ocorrem:
- Quando a intent é correspondida em um cenário, ela aciona um evento, e uma resposta
Canvas
contendo um campodata
com um payload JSON é enviada de volta como resposta. - O campo
data
é transmitido para um callbackonUpdate
e usado para atualizar o app da Web. Sua ação de conversa pode enviar uma nova resposta
Canvas
e fornecer informações no campodata
para enviar novas atualizações ou carregar novos estados.
É possível transmitir dados para seu app da Web de duas maneiras:
- Com o Actions Builder. O Actions Builder preenche automaticamente o campo
data
na respostaCanvas
com os metadados necessários para atualizar o app da Web. - Com um webhook. Se você tiver um webhook, poderá configurar um payload de dados
personalizado para atualizar o app da Web na resposta
Canvas
.
As seções a seguir descrevem como transmitir dados pelo Actions Builder e por um webhook.
Usar o Actions Builder para transmitir dados
Com o Actions Builder, não é necessário definir um webhook para gerenciar os metadados
enviados ao app da Web. Em vez disso, ao configurar o gerenciador de intents na
interface do Actions Builder, é possível incluir uma resposta Canvas
. Um
campo data
é preenchido automaticamente com os metadados necessários para atualizar
seu app da Web, como o nome da intent, todos os parâmetros capturados da entrada do usuário
e o cenário atual.
Por exemplo, o seguinte gerenciador de intent Guess
indica que você quer incluir uma resposta
Canvas
:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
Opcionalmente, é possível anexar o seguinte snippet ao gerenciador de intents para enviar uma mensagem TTS:
...
- first_simple:
variants:
- speech: Optional message.
O Actions Builder estende automaticamente a resposta Canvas
com metadados para
atualizar o app da Web, conforme mostrado nos snippets a seguir. Nesse caso, o usuário
adivinhou a letra "a" em um jogo de adivinhação de palavras:
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 } } ] }
Ela atualiza o app da Web com a resposta do usuário e faz a transição para a cena adequada.
Usar o webhook para transmitir dados
É possível configurar manualmente o campo data
das respostas Canvas
no webhook
com as informações de estado necessárias para atualizar o app da Web. Essa abordagem é
recomendada se você precisar incluir um payload data
personalizado em uma resposta Canvas
em vez de transmitir apenas os metadados típicos necessários para atualizar o app da Web.
Os snippets a seguir mostram como transmitir dados em uma resposta Canvas
no 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": "" } } }
Diretrizes e restrições
Lembre-se das seguintes diretrizes e restrições para respostas Canvas
ao criar sua ação:
- Cada gerenciador de webhook no fulfillment precisa incluir
Canvas
. Se a resposta do webhook não incluirCanvas
, o app da Web será fechado. - Você só precisa incluir o URL do seu app da Web na primeira resposta
Canvas
enviada ao usuário. - O URL de resposta
Canvas
precisa ser válido, e o protocolo precisa ser https. - A resposta
Canvas
precisa ter 50 KB ou menos.