Criar uma ação de tela interativa para o Google Assistente com o Actions Builder

O Actions on Google é uma plataforma para desenvolvedores que permite criar softwares para ampliar a funcionalidade do Google Assistente, o assistente pessoal virtual do Google, em mais de um bilhão de dispositivos, incluindo alto-falantes inteligentes, smartphones, carros, TVs, fones de ouvido e muito mais. Os usuários interagem com o Google Assistente em conversas para realizar tarefas, como comprar produtos ou reservar uma viagem. Para ver a lista completa do que é possível fazer, consulte o diretório de ações. Como desenvolvedor, você pode usar o Actions on Google para criar e gerenciar experiências de conversação úteis e agradáveis entre o usuário e seu próprio serviço de atendimento terceirizado.

Este codelab é um módulo avançado destinado a leitores que já têm alguma experiência com o Actions no Google Assistente. Se você ainda não tem experiência com desenvolvimento no Actions on Google, recomendamos que consulte nossos codelabs de introdução para se familiarizar com a plataforma (Níveis 1 e 2). Esses módulos dão orientação em uma série de recursos que podem ajudar a expandir a funcionalidade da sua ação e aumentar seu público-alvo.

Neste codelab, você vai usar a Tela interativa, um framework criado com o Google Assistente, para adicionar um jogo em tela cheia a uma ação conversacional. O jogo é um app da Web interativo que o Google Assistente envia como resposta ao usuário em uma conversa. O usuário pode jogar com entrada de texto ou de voz em smart displays e dispositivos móveis Android.

Em vez de criar um jogo inteiro, implante um jogo parcialmente pré-criado chamado Snow Pal e adicione a lógica dele conforme avançar no codelab. O Snow Pal é uma variação do tradicional jogo Forca e apresenta vários espaços em branco que representam uma palavra. O objetivo é tentar adivinhar quais letras correspondem aos espaços. A cada tentativa incorreta, o Snow Pal derrete um pouco mais. Você ganha o jogo se adivinhar a palavra antes de o Snow Pal derreter totalmente.

af9931bb4d507e39.png

Figura 1. Jogo Snow Pal em andamento.

O que você criará

Neste codelab, você vai criar uma ação que usa uma tela interativa. Sua ação terá os seguintes recursos:

  • Um jogo de palavras em tela cheia que os usuários podem jogar usando a voz
  • Um botão que pode ser pressionado para iniciar o jogo
  • Um botão que pode ser pressionado para jogar novamente

Quando você terminar este codelab, a ação concluída terá o seguinte fluxo de conversa:

Assistente: Welcome to Snow Pal! Would you like to start playing the game?

Usuário: Yes

Assistente: Try guessing a letter in the word or guessing the word.

Usuário: I guess the letter E

Assistente: Let's see if your guess is there...E is right. Right on! Good guess.

O usuário continua a adivinhar as letras ou a palavra desconhecida até que o jogo termine.

O que você aprenderá

  • Como criar e implantar uma ação de tela interativa
  • Como atualizar o jogo de palavras com base na entrada por toque ou voz do usuário
  • Como transmitir dados ao app da Web usando diferentes métodos
  • Como depurar sua ação de tela interativa

Pré-requisitos

Os pré-requisitos deste codelab incluem:

  • Um navegador da Web, como o Chrome;
  • Um IDE/editor de texto de sua escolha;
  • NodeJS, NPM e git instalados no seu computador.

É recomendável que você conheça JavaScript (ES6) para entender o código usado neste codelab.

Opcional: veja o exemplo de código completo

Neste codelab, você vai usar uma versão incompleta para criar uma amostra passo a passo. Se preferir, você também pode pegar a amostra concluída no repositório do GitHub.

A tela interativa é um framework criado com base no Google Assistente que permite adicionar recursos visuais e animações em tela cheia à ação de conversa.

Uma ação que usa a tela interativa e funciona de forma semelhante a uma ação de conversa normal. No entanto, a ação de tela interativa também pode enviar uma resposta ao dispositivo que abre um app da Web em tela cheia.

O usuário fornece uma entrada para o app da Web por voz ou por toque até o fim da conversa.

fa63a599f215aa81.gif

Figura 2. Uma ação criada com a tela interativa.

Neste codelab, seu projeto é organizado em três partes principais:

  • App da Web: os arquivos de apps da Web contêm o código dos recursos visuais e das animações desse app, bem como a lógica para atualizá-lo com base na entrada do usuário.
  • Ação de conversa: contém a lógica de conversa que reconhece, processa e responde à entrada do usuário.
  • Webhook: processa a lógica do jogo. Neste codelab, você funciona como um servidor de jogos.

Em cada seção deste codelab, você vai modificar o app da Web, a ação de conversa e o webhook para adicionar funcionalidades à ação da tela interativa.

Em um nível superior, a ação de conversa, o webhook e o app da Web da ação Snow Pal funcionam da seguinte maneira:

  1. A ação de conversa solicita que o usuário adivinhe toda a palavra ou uma letra dela.
  2. O usuário diz "Letra i" ao app da Web do Snow Pal em um smart display.
  3. A entrada do usuário é roteada para a ação de conversa, definida no projeto do Actions Builder e/ou do SDK do Actions.
  4. A ação de conversa processa a entrada do usuário e, dependendo do que for, aciona a lógica no webhook que atualiza o app da Web ou envia metadados para atualizar esse app diretamente.
  5. O app da Web é atualizado para mostrar onde a letra aparece na palavra, e o usuário recebe a solicitação para dizer outra letra.

Você verá mais sobre como a tela interativa funciona na seção "Entenda a infraestrutura da tela interativa". Agora que você já sabe o básico, pode começar a configurar seu ambiente para este codelab.

Verificar as configurações de permissão do Google

Para testar a ação criada para este codelab, é preciso ativar as permissões necessárias para que o simulador do Console do Actions possa acessá-la. Para ativar as permissões, siga estas etapas:

  1. Acesse a página Controles de atividade.
  2. Se necessário, faça login com sua Conta do Google.
  3. Ative as seguintes permissões:
  • Atividade na Web e de apps
  • Em Atividade na Web e de apps, marque a caixa ao lado de Incluir o histórico do Chrome e a atividade em sites, apps e dispositivos que usam serviços do Google.

Instalar a interface de linha de comando dos gactions

Neste codelab, você vai usar a ferramenta de interface de linha de comando (CLI) do gactions para sincronizar seu projeto do Console do Actions e do sistema de arquivos local.

Para instalar a CLI do gactions, siga as instruções na seção Instalar a ferramenta de linha de comando dos gactions.

Instalar a interface de linha de comando do Firebase

A interface de linha de comando (CLI) do Firebase permite implantar seu projeto do Actions no Cloud Functions e hospedar seu app da Web.

Este codelab usa o NPM para instalar a CLI do Firebase. Instale o NPM, que geralmente vem com o Node.js.

Para instalar ou fazer upgrade da CLI, abra um terminal e execute o seguinte comando npm:

npm install -g firebase-tools

Para verificar se a CLI foi instalada corretamente, execute o seguinte comando:

firebase --version

Verifique se a versão da CLI do Firebase é a 8 ou outra mais recente para que tenha todos os recursos necessários para o Cloud Functions. Se não for, execute npm install -g firebase-tools para atualizar.

Para fazer login no Firebase, execute o seguinte comando:

firebase login

Ao fazer login no Firebase, selecione a mesma Conta do Google usada para criar seu projeto do Actions.

Clonar o repositório

Nesta seção, você vai clonar os arquivos necessários para este codelab. Para acessar esses arquivos, siga estas etapas:

  1. Abra um terminal e selecione o diretório em que você costuma armazenar projetos de programação. Se não tiver um, use o diretório principal.
  2. Para clonar o repositório, execute o seguinte comando no seu terminal:
git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Abra o diretório start/. Ele contém estes importantes diretórios, que você usará para trabalhar:

  • public/: contém o código HTML, CSS e JavaScript do app da Web.
  • sdk/custom/: contém a lógica para sua ação de conversa (cenas, intents e tipos).
  • sdk/webhooks/: é o webhook que contém a lógica do jogo.

4864e8047bb2c8f6.png

Figura 3. A estrutura do código do diretório start.

Nesta seção, você vai criar e configurar seu projeto do Actions, enviar o código do repositório clonado ao Console do Actions com a CLI do gactions e implantar o app da Web e o webhook.

Criar um projeto do Actions

Seu projeto do Actions é um contêiner da sua ação. Para criar um projeto do Actions neste codelab, siga estas etapas:

  1. Abra o Console do Actions.
  2. Clique em Novo projeto.
  3. Digite um Nome de projeto, como canvas-codelab. O nome serve apenas para sua própria referência. Você pode definir um nome externo para o projeto mais tarde.

7ea69f1990c14ed1.png

  1. Clique em Criar projeto.
  2. Na tela Que tipo de ação você quer criar?, selecione o card Jogo.
  3. Clique em Próxima.
  4. Selecione o card Projeto em branco e clique em Começar a criar.

Salvar o ID do projeto da sua ação

O ID do projeto é um identificador exclusivo para sua ação. Você vai precisar dele em várias etapas deste codelab.

Para recuperar esse ID, siga estas etapas:

  1. No Console do Actions, clique nos três pontos verticais no canto superior direito da tela.
  2. Clique em Configurações do projeto.

6f59050b85943073.png

  1. Copie o ID do projeto.

Associar uma conta de faturamento

Se mais tarde você quiser implantar o fulfillment com o Cloud Functions neste codelab, é preciso associar uma conta de faturamento ao seu projeto no Google Cloud. Se você já tem uma conta desse tipo, ignore as etapas a seguir.

Para associar uma conta de faturamento ao projeto, siga estas etapas:

  1. Acesse a página de faturamento do Google Cloud Platform.
  2. Clique em Adicionar conta de faturamento.
  3. Preencha suas informações de pagamento e clique em Iniciar meu teste gratuito ou Enviar e ativar o faturamento.
  4. Clique na guia Meus projetos na parte superior da página.
  5. Clique nos três pontos em Actions, ao lado do projeto do Actions para o codelab.
  6. Clique em Mudar faturamento.
  7. No menu suspenso, selecione a conta de faturamento configurado. Clique em Definir conta.

Para evitar cobranças, siga as etapas da seção "Como limpar o projeto", na página "Próximas etapas", no final deste codelab.

Implantar app da Web

Nesta seção, você vai implantar seu app da Web (o jogo Snow Pal) com a CLI do Firebase. Depois da implantação, você pode recuperar o URL do app da Web e ver como o jogo aparece em um navegador.

Para implantar o app da Web, siga estas etapas:

  1. No terminal, acesse o diretório start/.
  2. Execute o seguinte comando, substituindo {PROJECT_ID} pelo seu ID do projeto:
firebase deploy --project {PROJECT_ID} --only hosting

Após alguns minutos, quando você já tiver implantado o app da Web do Snow Pal, aparecerá a mensagem "Implantação concluída!".

Para ver o jogo Snow Pal em um navegador, siga estas etapas:

  1. Recupere o URL de hospedagem fornecido na saída do seu terminal. O URL precisa estar no seguinte formato: https://{PROJECT_ID}.web.app
  1. Cole o URL em um navegador. Você verá a tela de início de jogo com o botão Start Game:

68429faae5141ed0.png

Adicionar o URL do app da Web e o ID ao projeto do Actions

Em seguida, adicione o URL do app da Web e o ID do projeto ao arquivo actions.intent.MAIN.yaml. Após adicionar esse URL, a ação de conversa poderá identificar para qual URL enviar os dados. Adicionar o ID do projeto em settings.yaml permitirá enviar os arquivos transferidos por download para o projeto correto no Console do Actions.

Para adicionar o URL do app da Web e o ID do projeto, siga estas etapas:

  1. Abra o arquivo start/sdk/custom/global/actions.intent.MAIN.yaml no editor de texto.
  2. No campo url, substitua a string do marcador pelo URL do seu app da Web.
  3. Abra o arquivo start/sdk/settings/settings.yaml no editor de texto.
  4. No campo projectId, substitua a string do marcador pelo ID do projeto.

Enviar o projeto para o Console do Actions

Para atualizar o Console do Actions com seu projeto local, envie seu projeto para o Console do Actions. Para fazer isso, siga estas etapas:

  1. Use o diretório sdk:
cd sdk/
  1. Para copiar a configuração do sistema de arquivos local para o Console do Actions, execute o seguinte comando:
gactions push

Implantar webhook

Ao executar gactions push, você importou o código do webhook inicial para o Console do Actions. No restante deste codelab, você pode editar o código do webhook no Console do Actions. Agora, basta implantar o webhook no Console do Actions.

Para fazer isso, siga estas etapas:

  1. No Console do Actions, clique em Desenvolver na navegação.
  2. Clique na guia Webhook na navegação.
  3. Clique em Implantar fulfillment.

O Cloud Functions pode levar alguns minutos para provisionar e implantar o fulfillment. Você verá a mensagem Implantação do Cloud Function em andamento... acima do editor de código. Quando o código for implantado, a mensagem será atualizada para A implantação da função do Cloud foi atualizada.

Testar no simulador

A ação será vinculada ao app da Web. Assim, é possível usar o simulador do Console do Actions para que o app da Web apareça ao invocar sua ação.

Para testar a ação, siga estas etapas:

  1. Na barra de navegação do Console do Actions, clique em Testar.
  2. Digite Talk to Snow Pal sample no campo Entrada e pressione Enter.
  3. Digite Yes no campo Entrada e pressione Enter. Ou então, clique no botão Iniciar jogo no meio da tela.

37f7bc4e550d817c.png

Você ainda não configurou a lógica para adivinhar uma letra ou a palavra. Portanto, se isso acontecer, receberá a resposta "Incorreto. Continue tentando! Parece que precisamos adicionar mais funcionalidades para que esse recurso funcione."

Para esse projeto, a funcionalidade é organizada em três componentes principais: ação de conversa, app da Web e webhook. Essa organização do modelo de configuração das ações destaca a funcionalidade principal da tela interativa.

As seções a seguir abordam mais detalhes sobre como a ação de conversa, o webhook e o app da Web funcionam juntos, além de outros elementos importantes da tela interativa.

Ação de conversa

O componente de conversa da sua ação identifica e processa a entrada do usuário e, depois, envia para a cena apropriada, onde é criada uma resposta. Por exemplo, se um usuário disser "Letra e" no jogo Snow Pal, sua ação de conversa extrai a letra como um parâmetro de intent e passa para a lógica apropriada do jogo, que determina se a resposta está correta e atualiza o app da Web de acordo com isso. Você pode ver e modificar essa lógica de conversa no Actions Builder, um IDE baseado na Web no Console do Actions. Veja parte da ação de conversa no Actions Builder na captura de tela abaixo:

91d1c5300f015ff9.png

Figura 4. Uma representação da Main invocation no Actions Builder.

Essa captura de tela mostra a Main invocation para sua ação, que é acionada quando o usuário diz algo como "Ok Google, falar com o exemplo de Snow Pal". Quando o usuário invoca sua ação, a Main invocation envia uma solicitação com uma resposta de canvas, que contém o URL do seu app da Web.

A primeira resposta canvas na sua ação precisa incluir o URL do app da Web. Essa resposta instrui o Google Assistente a renderizar o app da Web nesse endereço no dispositivo do usuário. Respostas canvas adicionais no Actions Builder podem incluir um campo, send_state_data_to_canvas_app, definido como true. Esse campo envia o nome da intent e os valores de parâmetro ao app da Web quando ela é correspondida. O app da Web é atualizado com base nesses dados a partir da entrada do usuário.

Webhook

Neste codelab, seu webhook contém a lógica do jogo (como se fosse um servidor de jogos). Ela inclui elementos como determinar se a suposição de um usuário está correta ou incorreta e se o usuário ganhou ou perdeu, além da criação de uma resposta baseada no resultado. É possível modificar o webhook no Actions Builder.

Quando a ação precisa executar a lógica do jogo, o Actions Builder faz uma chamada para o webhook. Por exemplo, a intent guess na cena Game faz uma chamada de webhook para o gerenciador guess, que executa a lógica para determinar se a suposição do usuário está correta ou não. O webhook pode incluir respostas Canvas nos gerenciadores que mapeiam para arquivos de app da Web e atualizam a Web corretamente.

App da Web

ca564ef59e1003d4.png

Figura 5. Uma representação visual da interação entre a ação conversacional, o webhook e o app da Web em uma ação de tela interativa.

Os arquivos do app da Web contêm o código dos elementos visuais e das animações desse app, bem como a lógica para atualizá-lo com base na entrada do usuário. Você pode modificar os arquivos do app da Web no seu editor de texto e implantar essas alterações usando a CLI do Firebase.

Comunicação entre app de conversa e app da Web

Para que seu app da Web possa ser atualizado com base nas entradas do usuário, você precisa ativar a comunicação entre a ação de conversa e esse app. Por exemplo, um usuário diz "Letra F".

A ação de conversa precisa fornecer ao app da Web a letra "F" para atualizá-lo de forma adequada. Para passar a entrada do usuário da ação de conversa para o app da Web, é preciso carregar na API de Tela interativa.

O script dessa API está incluído em /public/index.html, que é o principal arquivo HTML do jogo Snow Pal. Esse arquivo define como a IU é exibida e carrega em vários scripts:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Para atualizar o app da Web com base na entrada do usuário, você também precisa registrar e configurar callbacks no arquivo do app da Web. Os callbacks permitem que esse app responda a informações ou solicitações da ação de conversa.

Em /public/js/action.js, há uma classe pré-configurada chamada Action para declarar e registrar callbacks. A classe Action é um wrapper da API de Tela interativa. Quando o app da Web é criado com a função create() em scene.js, uma nova instância de Action é criada e o elemento setCallbacks() é chamado, conforme mostrado no snippet a seguir:

scene.js

// Set assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register assistant action callbacks.
this.assistant.setCallbacks();

A função setCallbacks() é definida na classe Action de /public/js/action.js. Essa função declara callbacks e os registra com a API de Tela interativa na criação do jogo:

  setCallbacks() {
    // Declare the Interactive Canvas action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

A função setCallbacks() declara o callback onUpdate(), que é chamado sempre que você envia uma resposta Canvas.

A próxima seção mostra como o código específico desse projeto é configurado para passar dados da ação de conversa para o app da Web.

Como atualizar o app da Web com base na entrada do usuário

Neste codelab, você vai usar um mapa de comando para atualizar o app da Web com base na entrada de um usuário. Por exemplo, quando a intent start_game é correspondida na cena Welcome, a resposta canvas incluída na solicitação é enviada ao app da Web. onUpdate() analisa os metadados da resposta canvas e chama o comando START_GAME, que, por sua vez, chama a função start() em scene.js e atualiza o app da Web para iniciar um novo jogo.

A função start() em scene.js também chama uma função, updateCanvasState(), que usa um método chamado setCanvasState() para adicionar dados de estado que podem ser acessados pelo webhook.

O método updateCanvasState() é chamado no final de cada comando (que você adicionará ao codelab) e atualiza o estado do app da Web. Cada vez que updateCanvasState() é chamado, os valores para displayedWord e incorrectGuesses são atualizados com base no estado atual:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

O estado atualizado é disponibilizado para a próxima fala. É possível acessar esse estado no webhook usando conv.context.canvas.state, conforme mostrado no snippet de código a seguir:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

Nesta seção, você vai adicionar a funcionalidade guess à sua ação, o que permite ao usuário adivinhar a palavra ou algumas letras dela.

Ação de conversa

Na seção "Testar no simulador", você recebeu uma resposta com a mensagem: "Parece que precisamos adicionar mais funcionalidades para que esse recurso funcione." Agora, é possível excluir a solicitação no Console do Actions para chamar apenas o webhook. Na cena Game, a intent guess já está configurada para fazer uma chamada de webhook quando há correspondência.

Para remover a solicitação estática quando a intent guess for correspondida, siga estas etapas:

  1. No Console do Actions, clique em Cenas na navegação.
  2. Clique em Jogo para acessar a cena Game.
  3. Clique em Quando houver correspondência para a suposição em Gerenciamento de intent personalizada. Desmarque Enviar solicitações para remover a solicitação.
  4. Clique em Salvar.

Webhook

Nesta seção, você atualizará seu webhook com uma lógica que mapeia a suposição correta ou incorreta de usuários em um arquivo de app da Web, que atualiza o app da Web conforme necessário. O gerenciador de intent guess já está configurado para você no webhook. Portanto, basta adicionar respostas Canvas a essa intent para acionar a lógica que atualiza o app da Web.

Para atualizar seu webhook, siga estas etapas:

  1. No Console do Actions, clique em Webhook na navegação.
  2. Adicione o seguinte código ao index.js abaixo do gerenciador guess:

index.js (Seção A):

// Add SECTION A `conv.add(new Canvas({` content here
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (Seção B):

// Add SECTION B `conv.add(new Canvas({` content here
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));
  1. Clique em Salvar fulfillment.
  2. Clique em Implantar fulfillment. Quando a implantação estiver concluída, aparecerá esta mensagem acima do editor: A implantação da função do Cloud foi atualizada.

App da Web

Agora é possível configurar seu app da Web para processar os comandos CORRECT_ANSWER e INCORRECT_ANSWER.

  1. Abra public/js/action.js no seu editor de texto.
  2. Atualize o app da Web para processar os comandos CORRECT_ANSWER e INCORRECT_ANSWER:

action.js (Seção C):

// Add SECTION C `CORRECT_ANSWER: (params) => {` content here
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },
  1. Execute o seguinte comando para atualizar o app da Web:
firebase deploy --project {PROJECT_ID} --only hosting

Testar ação no simulador

Agora, a ação pode reconhecer se a suposição está correta ou incorreta e atualizar o app da Web adequadamente.

Para testar a ação, siga estas etapas:

  1. Na barra de navegação, clique em Testar.
  2. Digite Talk to Snow Pal sample no campo Entrada e pressione Enter.
  3. Digite "Sim" no campo Entrada e pressione Enter. Se preferir, clique no botão Sim.
  4. Digite a letra desejada no campo de entrada e pressione Enter.

1c2c2d59a418642b.png

Entender o código

Na seção anterior, você adicionou um código para que os usuários adivinhassem letras no seu jogo e vissem o resultado dessas suposições na palavra ou no Snow Pal. Em um nível superior, você faz uma chamada do webhook no Actions Builder quando a intent guess é correspondida, o que passa dados para o app da Web para a atualização necessária. Por exemplo, no jogo Snow Pal, se o usuário indicar uma letra que a palavra tem, o app da Web será atualizado e mostrará essa letra na posição correta.

Para ações que usam tela interativa, o fluxo geral para a transmissão de dados do webhook para o app da Web é o seguinte:

  1. A entrada do usuário corresponde a uma intent que inclui uma resposta Canvas.
  2. A ação de conversa ou o webhook envia a resposta Canvas, que aciona o callback onUpdate().
  3. O callback onUpdate() é mapeado para uma lógica personalizada que atualiza o app da Web conforme necessário.

Nesse projeto específico, o código funciona da seguinte maneira:

  1. Quando o usuário gera uma correspondência com a intent guess, o Actions Builder extrai a letra da entrada como um parâmetro.
  2. O Actions Builder chama o gerenciador guess no webhook, que contém uma lógica para determinar se a letra que o usuário sugeriu aparece na palavra.
  3. O gerenciador do guess tem duas respostas Canvas: uma é executada quando a letra está correta, e a outra, quando está incorreta. Cada resposta Canvas transmite os dados apropriados (o comando CORRECT_ANSWER ou INCORRECT_ANSWER) para o app da Web.
  4. Os dados no campo data da resposta Canvas são transmitidos ao método onUpdate() em action.js. onUpdate() chama o comando apropriado no mapa, em scene.js.
  5. O mapa de comando envia às funções correctAnswer() e incorrectAnswer() em scene.js. Essas funções atualizam o app da Web conforme a suposição do usuário e chamam setCanvasState() para enviar dados de estado desse app para o webhook.

Nesta seção, você vai adicionar a funcionalidade de ganhar e perder à ação. Esse recurso inclui uma lógica que determina se o usuário ganhou ou perdeu e outra que atualiza a imagem do app da Web com base no resultado.

Ação de conversa

A funcionalidade que processa a vitória ou a derrota do usuário é configurada na intent guess. Assim, não é preciso fazer outras configurações no Actions Builder.

Webhook

Nesta seção, você vai atualizar o webhook com uma lógica que processa a vitória ou a derrota do usuário, além de mapear para uma lógica do app da Web que atualiza o jogo com a tela apropriada.

Para atualizar seu webhook, siga estas etapas:

  1. No Console do Actions, clique em Webhook na navegação.
  2. Adicione o seguinte código ao index.js abaixo do gerenciador guess:

index.js (Seção D):

// Add SECTION D `if (userHasWon)` content here
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Seção E):

// Add SECTION E `}` here
}

index.js (Seção F):

// Add SECTION F `Check if the user has exceeded the maximum` content here
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Seção G):

// Add SECTION G `}` here
}
  1. Clique em Salvar fulfillment.
  2. Clique em Implantar fulfillment. Quando a implantação estiver concluída, aparecerá esta mensagem acima do editor: A implantação da função do Cloud foi atualizada.

Aqui, você adicionou duas respostas Canvas com os comandos WIN_GAME e LOSE_GAME para processar a vitória ou a derrota no jogo. Na próxima seção, você vai adicionar funcionalidades que atualizam o app da Web nesses dois casos.

App da Web

Agora, você poderá configurar seu app da Web para atualizar quando o usuário ganhar ou perder o jogo. Para atualizar esse app, siga estas etapas:

  1. Abra public/js/action.js no seu editor de texto.
  2. Atualize seu app da Web para processar os comandos WIN_GAME e LOSE_GAME:

action.js (Seção H):

// Add SECTION H `WIN_GAME: (params) => {` content here
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },
  1. Execute o seguinte comando para atualizar o app da Web:
firebase deploy --project {PROJECT_ID} --only hosting

Testar ação no simulador

Nesse ponto, a ação pode processar a vitória ou a derrota do usuário no jogo e apresentar a tela conforme o resultado.

Para testar a ação, siga estas etapas:

  1. Na barra de navegação do Console do Actions, clique em Testar.
  2. Digite Talk to Snow Pal sample no campo Entrada e pressione Enter.
  3. Digite "Sim" no campo Entrada e pressione Enter. Ou então, clique no botão Iniciar jogo.
  4. Adivinhe letras e palavras até ganhar ou perder.

ee572870f9a7df36.png

Se pedir para jogar de novo, você vai receber uma mensagem indicando que a funcionalidade necessária para abrir novamente ainda não foi adicionada. Você poderá adicionar essa funcionalidade na próxima seção.

Entender o código

A funcionalidade para vitórias ou derrotas funciona como a de suposição: o usuário gera uma correspondência para a intent guess, e o webhook avalia a suposição do usuário. Se estiver correta, o código vai verificar se o usuário venceu. Se for esse o caso, o comando WIN_GAME é enviado ao app da Web. Se estiver errada, o código vai verificar se ele perdeu. Caso tenha perdido, o comando LOSE_GAME será enviado ao app da Web. Esses comandos acionam as funções winGame() e loseGame() em scene.js, que atualizam o app da Web para apresentar a tela de vitória ou derrota e atualizam o estado do jogo.

Nesta seção, você vai adicionar uma funcionalidade que permite ao usuário dizer "Jogar novamente" ou clicar no botão Play Again no app da Web para começar um novo jogo. Você pode modificar a intent play_again no Actions Builder para enviar uma resposta canvas que atualiza o app da Web e adiciona a lógica que aciona a intent play_again quando o usuário clica no botão Play Again.

Ação de conversa

Ao testar a ação na seção anterior, você recebeu o seguinte aviso ao tentar jogar novamente: "Seria ótimo, mas essa funcionalidade será criada em uma seção futura. Por enquanto, redefina a ação." Agora você pode excluir essa solicitação e substituí-la por outra que responda ao usuário quando ele solicitar outro jogo ("Ok, aqui está outro jogo!") e inclui uma resposta canvas para acionar o app da Web para começar um novo jogo.

Para atualizar a solicitação quando o usuário quiser jogar novamente, siga estas etapas:

  1. No Console do Actions, clique na lista suspensa Cena.
  2. Clique na cena Game.
  3. Clique em When play_again is matched em Processamento de intent personalizada.
  4. Substitua a solicitação pelo seguinte:
candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here's another game!'
    canvas:
      sendStateDataToCanvasApp: true
  1. Clique em Salvar.

Webhook

Neste codelab, o webhook gerencia a lógica de jogo. Como o recurso "jogar novamente" não exige nenhum tipo de validação de lógica, você não precisa chamar o webhook. Basta enviar uma resposta canvas diretamente do Actions Builder para transmitir os dados necessários ao app da Web (que você configurou na seção anterior).

App da Web

Agora, é possível modificar os arquivos do app da Web para atualizar adequadamente quando o usuário pedir para jogar novamente. Para adicionar essa funcionalidade, siga estas etapas:

  1. Abra public/js/action.js no seu editor de texto.
  2. Atualize o app da Web para processar o comando PLAY_AGAIN:

action.js (Seção I):

// Add SECTION I `PLAY_AGAIN: (params) => {` content here
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },
  1. Abra public/js/scene.js no seu editor de texto.
  2. Atualize o app da Web para iniciar um novo jogo quando o usuário clicar no botão "Jogar novamente":

scene.js (Seção J):

// Add SECTION J `sendTextQuery` content here
     window.interactiveCanvas.sendTextQuery('Play again');
  1. Execute o seguinte comando para atualizar o app da Web:
firebase deploy --project {PROJECT_ID} --only hosting

Testar ação no simulador

Sua ação agora pode iniciar um novo jogo quando o usuário disser Jogar novamente ou pressionar o botão "Jogar novamente".

Para testar a ação, siga estas etapas:

  1. Na barra de navegação, clique em Testar.
  2. Digite Talk to Snow Pal sample no campo Entrada e pressione Enter.
  3. Digite "Sim" no campo Entrada e pressione Enter. Ou então, clique no botão Iniciar jogo.
  4. Adivinhe letras e palavras até ganhar ou perder.
  5. Digite "Jogar novamente" no campo Entrada e pressione Enter. Ou então, clique no botão Jogar novamente.

1fbc7193f7a9d0f5.png

Entender o código

Ao testar sua ação, você pode iniciar um novo jogo com a entrada de texto por voz ("Jogar novamente") ou a entrada por toque (clicando no botão "Jogar novamente").

Para a opção de entrada de texto por voz, quando o usuário disser "Jogar novamente" ou alguma variação disso, isso vai gerar uma correspondência com a intent play_again e adicionar à fila uma solicitação ("Ok, aqui está outro jogo!"). A resposta canvas da solicitação envia o nome da intent e outros metadados para o app da Web. O nome da intent é transmitido para o callback onUpdate(), que envia o comando correspondente, PLAY_AGAIN, para o mapa de comandos em action.js. O comando PLAY_AGAIN aciona a função start() em scene.js e atualiza o app da Web com um novo jogo.

Para a opção de entrada por toque, use sendTextQuery(),, uma API de tela interativa que permite acionar uma intent por meio da entrada por toque para que o botão funcione.

Neste codelab, você usará sendTextQuery() para invocar a intent play_again quando um usuário clicar no botão "Jogar novamente". O argumento Play again corresponde a uma frase de treinamento na intent play_again, que é acionada da mesma forma quando o usuário diz "Jogar novamente". Em seguida, a intent play_again aciona a lógica que atualiza o app da Web e inicia um novo jogo.

Nesta seção, você vai atualizar a invocação implícita PLAY_GAME.

A invocação implícita PLAY_GAME permite que os usuários invoquem sua ação quando fazem uma solicitação geral, como "Quero jogar".

O código-fonte contém a intent global PLAY_GAME, localizada em /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Isso aparece no console em Invocação como PLAY_GAME, conforme a captura de tela a seguir:

b4a73c0ddd88f6d5.png

Para permitir que os usuários invoquem sua ação usando essa invocação implícita, é necessário adicionar uma resposta canvas com o URL do app da Web à invocação implícita PLAY_GAME. Para fazer isso, siga estas etapas:

  1. No Console do Actions, clique em PLAY_GAME na navegação.
  2. Atualize a solicitação para incluir o URL do seu app da Web, conforme o snippet a seguir:
candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'
  1. Clique em Salvar.

Testar ação no simulador

Sua ação agora é compatível com a invocação implícita PLAY_GAME.

Para testar a ação, siga estas etapas:

  1. Na barra de navegação, clique em Testar.
  2. Clique em Testar o fulfillment para intents do sistema.
  3. Clique em Invocar ação.

1a4f647e17ebab53.png

A ação deve ser invocada no simulador.

Nesta seção, você vai aprender como depurar a ação de tela interativa quando ela não estiver funcionando corretamente. O projeto Snow Pal já vem com uma sobreposição de depuração que pode ser ativada. A sobreposição exibe todas as saídas console.log() e console.error() no canto inferior direito da tela, conforme a captura de tela a seguir:

4c8531d24366b5df.png

Para ativar essa sobreposição, abra o arquivo /public/css/main.css e comente a linha display: none !important;, conforme o snippet a seguir:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Parabéns!

Você concluiu o codelab introdutório sobre a tela interativa e agora tem as habilidades necessárias para criar sua própria ação de tela interativa.

O que você aprendeu

  • Como criar, implantar e testar uma ação de tela interativa
  • Como usar respostas Canvas para atualizar o app da Web
  • Como usar métodos diferentes para melhorar sua ação, como sendTextQuery() e setCanvasState()
  • Como depurar a ação

Recursos de aprendizado adicionais

Confira os seguintes recursos para saber mais sobre a tela interativa:

Como limpar o projeto [recomendado]

Para evitar possíveis cobranças, é recomendável remover os projetos que você não pretende usar. Para excluir os projetos criados neste codelab, siga estas etapas:

  1. Para excluir o projeto e os recursos do Cloud, conclua as etapas da seção Como encerrar (excluir) projetos.
  1. Opcional: para remover seu projeto do Console do Actions imediatamente, conclua as etapas da seção Como excluir um projeto. Caso contrário, seu projeto será removido automaticamente após cerca de 30 dias.

Pesquisa de feedback

Antes de sair, preencha esta breve pesquisa sobre sua experiência.