Comandos do Canvas

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:

  1. 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.
  2. Clique em Desenvolver na navegação da parte de cima do Console do Actions.
  3. Clique em Tela interativa na navegação à esquerda.
  4. 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.
  5. 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.
  6. Clique em Salvar.

Ao usar o SDK do Actions, siga estas outras etapas para ativar a tela interativa:

  1. Defina o campo category no arquivo settings.yaml como GAMES_AND_TRIVIA para descrever melhor e ajudar os usuários a descobrir sua ação.
  2. Defina o campo usesInteractiveCanvas no arquivo settings.yaml como true.

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:

  1. Verifique se o dispositivo do usuário é compatível com o recurso INTERACTIVE_CANVAS. Em caso afirmativo, envie uma resposta Canvas ao usuário.
  2. 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.
  3. 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:

  1. Quando a intent é correspondida em um cenário, ela aciona um evento, e uma resposta Canvas contendo um campo data com um payload JSON é enviada de volta como resposta.
  2. O campo data é transmitido para um callback onUpdate e usado para atualizar o app da Web.
  3. Sua ação de conversa pode enviar uma nova resposta Canvas e fornecer informações no campo data 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 resposta Canvas 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 incluir Canvas, 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.