Para redirecionar informações para seu app da Web, você precisa enviar uma resposta Canvas
da sua lógica de conversa. Uma resposta Canvas
pode realizar uma das seguintes ações:
- 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 do Canvas para cada diferente.
Ativar tela interativa
É preciso configurar sua ação de uma maneira específica para usar a tela interativa.
Para criar uma ação que usa a tela interativa, é preciso ter
no Console do Actions (e, no caso do SDK, as modificações no
seu arquivo settings.yaml
). Para ver o procedimento completo para criar e
como configurar uma ação de tela interativa com o SDK do Actions, consulte
Criar um projeto.
Ao usar o Actions Builder, siga estas etapas adicionais para ativar as opções Tela:
- Se você não selecionou o card Jogo em Que tipo de ação que você quer criar?, clique em Implantar na barra de navegação superior. Em Informações adicionais, selecione a caixa de seleção Jogos e divertida. 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
o seguinte:
- Ativar a tela interativa com o fulfillment do webhook do servidor Esta opção
depende do webhook para acessar determinados recursos e usa com frequência
onUpdate()
para transmitir dados ao app da Web. Quando ativadas, as correspondências de intents são em cenas. Você pode chamar o webhook antes de fazer a 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
chamadas de webhook apenas para os recursos de conversação que precisam dele,
como vinculação de contas. Quando esse recurso está ativado, você pode usar
expect()
para registre gerenciadores de intents no lado do cliente.
- Ativar a tela interativa com o fulfillment do webhook do servidor Esta opção
depende do webhook para acessar determinados recursos e usa com frequência
- Opcional: insira o URL do app da Web em Definir o URL padrão do app da Web.
. Essa ação adiciona uma resposta
Canvas
padrão com o campo de URL ao arquivo na invocação principal. - Clique em Salvar.
Ao usar o SDK do Actions, siga estas outras etapas para ativar os recursos Tela:
- Defina o campo
category
no arquivosettings.yaml
comoGAMES_AND_TRIVIA
para melhor descrever 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 Assistente que oferecem
uma interface visual, então a ação precisa procurar o INTERACTIVE_CANVAS
.
capability no dispositivo do usuário. Ao definir comandos no Actions Builder,
especifique uma lista de recursos do dispositivo no campo selector
do
objeto candidates
. O seletor de comandos seleciona o candidato mais adequado
adequado à 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
. Se faça isso, envie ao usuário uma respostaCanvas
. - Se o recurso "Tela interativa" não estiver disponível, verifique se o
dispositivo oferece suporte ao recurso
RICH_RESPONSE
. Se tiver, envie ao usuário resposta avançada. - Se o recurso de resposta avançada não estiver disponível, envie ao usuário um resposta simples.
Os snippets a seguir retornam a resposta apropriada 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 imagens recursos visuais que você envia aos usuários como resposta. Quando o app da Web é renderizado, os usuários continuar interagindo com ele por voz, texto ou toque até que conversa.
Sua primeira resposta Canvas
precisa conter o URL do app da Web. Esse tipo de
A resposta do dispositivo Canvas
pede para o Google Assistente 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 aplicativo da Web é carregado, o
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 nas captura de tela a seguir:
Se você criar um comando que inclua uma resposta Canvas
depois de especificar o
URL do app da Web, o Actions Builder vai preencher automaticamente o campo de URL da resposta Canvas
. Para mais
informações sobre como configurar o URL do app da Web no console, consulte a
Seção Ativar a tela interativa.
Os snippets a seguir mostram como criar respostas Canvas
que são renderizadas
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 outros Canvas
respostas para fornecer atualizações para data
, que a lógica personalizada do seu app da Web usa
para fazer alterações no seu app da Web. Quando você envia uma resposta Canvas
aprovada
dados para o app da Web, as seguintes etapas ocorrem:
- Quando há correspondência com a intent em uma cena, ela aciona um evento e uma resposta
Canvas
. que contém um campodata
com um payload JSON é enviado 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 em o campodata
para enviar novas atualizações ou carregar novos estados.
Você pode transmitir dados para seu app da Web de duas maneiras:
- Com o Actions Builder. O Actions Builder preenche automaticamente o campo
data
em a respostaCanvas
com os metadados necessários para atualizar o app da Web. - Com um webhook. Se você tiver um webhook, poderá configurar um bucket
payload para atualizar o app da Web na sua resposta
Canvas
.
As seções a seguir descrevem como transmitir dados pelo Actions Builder e pelo um webhook.
Usar o Actions Builder para transmitir dados
Com o Actions Builder, você não precisa definir um webhook para gerenciar os metadados.
que é enviado ao seu app da Web. Em vez disso, ao configurar o gerenciador de intents no
interface do Actions Builder, é possível incluir uma resposta Canvas
. Um
O campo data
é preenchido automaticamente com os metadados necessários para atualização.
seu app da Web, como o nome da intent, todos os parâmetros capturados da entrada do usuário
e a cena atual.
Por exemplo, o gerenciador de intent Guess
a seguir indica que você quer incluir um Canvas
.
resposta:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
Como opção, é possível anexar o seguinte snippet ao gerenciador de intent para enviar uma Mensagem TTS:
...
- first_simple:
variants:
- speech: Optional message.
O Actions Builder estende automaticamente a resposta Canvas
com metadados para
atualize 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 } } ] }
Essa resposta atualiza seu app da Web com a resposta do usuário e faz a transição para a no cenário apropriado.
Usar o webhook para transmitir dados
É possível configurar manualmente o campo data
de respostas Canvas
no webhook
com as informações de estado necessárias para atualizar seu app da Web. Essa abordagem é
recomendado se você precisar incluir um payload data
personalizado em uma resposta Canvas
em vez de apenas transmitir os metadados típicos necessários para atualizar o app da Web.
Os snippets a seguir mostram como transmitir dados em uma resposta Canvas
na sua
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 de Canvas
ao criar sua ação:
- Cada gerenciador de webhook no seu fulfillment precisa incluir
Canvas
. Se o webhook não incluirCanvas
, seu app da Web será fechado. - É necessário incluir o URL do seu app da Web apenas na primeira resposta
Canvas
que você envia ao usuário. - O URL de resposta
Canvas
precisa ser válido e o protocolo precisa ser https. - A resposta
Canvas
precisa ter até 50 KB.