Comandos do Canvas

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:

  1. 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.
  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 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.
  5. 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.
  6. Clique em Salvar.

Ao usar o SDK do Actions, siga estas outras etapas para ativar os recursos Tela:

  1. Defina o campo category no arquivo settings.yaml como GAMES_AND_TRIVIA para melhor descrever 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 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:

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

  1. Quando há correspondência com a intent em uma cena, ela aciona um evento e uma resposta Canvas. que contém um campo data com um payload JSON é enviado 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 em o campo data 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 resposta Canvas 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 incluir Canvas, 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.