Jogo de prática de ortografia usando o Google Assistente e o Cloud Firestore

1. Visão geral

Com a plataforma para desenvolvedores do Google Assistente, é possível criar softwares para ampliar a funcionalidade desse assistente pessoal virtual em mais de 1 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 na conversa para realizar tarefas, como fazer compras ou reservar uma viagem. Como desenvolvedor, você pode usar a plataforma para desenvolvedores do Google Assistente para criar e gerenciar experiências de conversação eficazes e agradáveis entre os usuários e seu próprio serviço de atendimento de pedidos terceirizado.

Este codelab abrange conceitos de nível intermediário para desenvolvimento com o Google Assistente, o Cloud Functions e o Cloud Firestore. Neste codelab, você vai criar um jogo chamado "Ortografia" que usa o Google Assistente para pedir que os usuários digitem palavras.

O que você vai criar

Neste codelab, você criará um jogo sofisticado com as seguintes funcionalidades:

• Recebe respostas ortográficas do usuário e, dependendo do valor, modifica os comandos de conversação
• Responde com dicas relacionadas à ortografia da palavra, como a definição dela ou a repetição da palavra
• cria um loop de jogo para que o usuário possa interagir com o Google Assistente novamente depois de soletrar a palavra.

Antes de começar a criar, você pode interagir com a ação ativa no dispositivo com Google Assistente dizendo "Ok Google, fale com a prática de ortografia". O caminho padrão dessa ação para um usuário recorrente é semelhante à seguinte interação:

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

O que você aprenderá

• Como interagir com o Cloud Firestore
• Como usar slots para coletar dados do usuário.
• Como processar a entrada de um usuário e retornar uma resposta.
• Como usar condições para adicionar lógica a uma cena
• Como adicionar um loop de jogo

O que é necessário

Os pré-requisitos para este codelab incluem:

• Um navegador da Web, como o Google Chrome
• Um ambiente de desenvolvimento integrado para gravar funções do Cloud.
• Uma forma de pagamento. Este codelab usa o Cloud Functions para Firebase, o que exige que seu projeto esteja no plano de preços do Firebase Blaze. Saiba mais.
• Um terminal para executar comandos do shell
• Node.js 10 ou mais recente

2. Acessar o código das funções

Clone o repositório do GitHub (link em inglês) da linha de comando:

$ git clone https://github.com/FirebaseExtended/codelab-actions-firestore

3. Criar um projeto do Firebase e configurar o app

criar um projeto do Firebase

1. Faça login no Firebase.
2. No Console do Firebase, clique em Adicionar projeto (ou Criar um projeto) e nomeie seu projeto como Spelling-Practice.

3. Clique nas opções de criação do projeto. Se solicitado, aceite os termos do Firebase. Pular a configuração do Google Analytics, porque ele não vai ser usado neste app.

Para saber mais sobre os projetos do Firebase, consulte Noções básicas sobre os projetos do Firebase.

Fazer upgrade para o plano de preços Blaze

Para usar o Cloud Functions para Firebase, faça upgrade do seu projeto do Firebase para o plano de preços Blaze, ou seja, você anexará uma conta do Google Cloud Billing ao projeto. Para isso, você precisa informar um cartão de crédito ou outra forma de pagamento.

Todos os projetos do Firebase, incluindo aqueles no plano Blaze, ainda têm acesso às cotas de uso sem custos financeiros do Cloud Functions. As etapas descritas neste codelab estão dentro dos limites de uso sem custos financeiros. No entanto, você vai receber pequenas cobranças ( cerca de US $0, 03) do Cloud Storage usado para hospedar suas imagens de build do Cloud Functions.

4. instalar a CLI do Firebase

A CLI do Firebase (interface de linha de comando) permite implantar o Cloud Functions.

Há várias opções de instalação da CLI do Firebase, dependendo do sistema operacional e do caso de uso. As etapas a seguir descrevem a opção mais comum se você também estiver usando o Cloud Functions.

1. Confira se você instalou o npm, que normalmente vem com o Node.js.
2. Instale ou faça upgrade da CLI executando o seguinte comando npm:

$ npm -g install firebase-tools

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

$ firebase --version

Verifique se a versão da CLI do Firebase é 9.0.0 ou mais recente para que ela tenha todos os recursos mais recentes necessários para o Cloud Functions. Caso contrário, execute npm install -g firebase-tools para fazer a atualização conforme mostrado acima.

4. Autorize a CLI do Firebase executando:

$ firebase login

5. No diretório letter-functions-start, configure a CLI do Firebase para usar seu projeto. Execute o comando a seguir, selecione o ID do projeto e siga as instruções. Quando solicitado, escolha qualquer alias, como codelab, por exemplo.

$ firebase use --add

5. O diretório de funções

Agora você adicionará uma funcionalidade usando o SDK do Firebase para Cloud Functions a fim de criar o back-end do jogo: Ortografia.

Com o Cloud Functions, é possível executar o código na nuvem sem configurar um servidor. Este codelab mostra como criar funções que reagem a eventos do Firebase Authentication, Cloud Storage e Firebase Realtime Database. Vamos começar com o Authentication.

Ao usar o SDK do Firebase para Cloud Functions, seu código de funções fica no diretório functions (por padrão). Para facilitar, já criamos o arquivo functions/index.js onde seu código será armazenado. Fique à vontade para inspecionar o diretório functions antes de prosseguir.

$ cd functions
$ ls

O código de funções também é um app Node.js e, portanto, precisa de um package.json que forneça algumas informações sobre o app e liste as dependências.

Se você não tiver familiaridade com o Node.js, será útil saber mais sobre ele antes de continuar o codelab.

O arquivo package.json já lista duas dependências obrigatórias: o SDK do Firebase para Cloud Functions e o SDK Admin do Firebase. Para instalá-los localmente, execute npm install no diretório functions:

$ npm install

Agora, vamos dar uma olhada no arquivo index.js:

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */
// TODO(DEVELOPER): Import the Cloud Functions for Firebase and Firebase Admin modules here. Also import the Actions SDK here.
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

Primeiro, você importará os módulos necessários e, em seguida, escreverá quatro funções no lugar dos TODOs. Siga para a próxima etapa do codelab para importar os módulos.

6. Importar os módulos necessários

Este codelab requer três módulos.

• O módulo firebase-functions permite escrever os gatilhos do Cloud Functions.
• O módulo firebase-admin permite usar a plataforma do Firebase em um servidor com acesso de administrador, por exemplo, para gravar no Cloud Firestore.
• A biblioteca Fulfillment do SDK do Actions para Node.js atende aos gerenciadores do SDK do Actions no Google Assistente.

1. Instale o SDK do Actions executando o seguinte comando npm:

$ npm install @assistant/conversation

2. No arquivo index.js, substitua o primeiro TODO pelo seguinte.

Essas mudanças importam cada um dos módulos necessários.

Além disso, o SDK Admin do Firebase pode ser configurado automaticamente quando implantado em um ambiente do Cloud Functions ou em outro contêiner do Google Cloud. É isso que acontece quando chamamos admin.initializeApp(); nas mudanças abaixo.

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */

// Import the Actions SDK
const {conversation} = require('@assistant/conversation');
const https = require('https');
const app = conversation();
const cors = require('cors')({origin: true});

// Import the Firebase SDK for Cloud Functions.
const functions = require('firebase-functions');
// Import and initialize the Firebase Admin SDK.
const admin = require('firebase-admin');
admin.initializeApp();
// To access Cloud Firestore
const db = admin.firestore();
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the shuffleWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

Agora, vamos adicionar uma lógica de negócios usando funções compatíveis com as ações do Google Assistente.

7. Criar funções

Conseguir as definições das palavras e gravá-las no Cloud Firestore

Você vai usar a API pública dictionaryapi.dev para conferir as definições das palavras.

No arquivo index.js, substitua o TODO por getWordDetailsFromDictionaryAPI pelo seguinte:

index.js

// Retrieves word definition and audio pronunciation from api.dictionaryapi.dev service
// Function uses service provided by https://dictionaryapi.dev/
async function getWordDetailsFromDictionaryAPI(word) {
  let responseData="";
  let req = https.request({
    host: 'api.dictionaryapi.dev',
    port: 443,
    path:'/api/v2/entries/en/' + word,
    method:'GET'
  }, (res) => {
    res.setEncoding('utf8');
    res.on('data', d => {
        responseData+=d;
    })
    res.on('end',function(){
        let object = JSON.parse(responseData)
        const wordListRef = db.collection('wordlist');
        wordListRef.doc(object[0].word).set(
          object[0]
        );
       return responseData;
     });
  });
  req.end();
}

Adicionar um gatilho do Cloud Firestore

Em seguida, você vai criar uma função do Cloud que é acionada sempre que um novo documento é criado no Cloud Firestore. Ele vai chamar a API dictionaryapi.dev para receber definições de palavras usando a função getWordDetailsFromDictionaryAPI que escrevemos acima.

No arquivo index.js, substitua o TODO por createSpellingPracticeWord pelo seguinte:

index.js

// Gatilho do Firestore que busca definições de palavras por meio da getWordDetailsFromDictionaryAPI para cada novo documento do Firestore

exports.createSpellingPracticeWord = functions.firestore
  .document('wordlist/{word}')
  .onCreate((snap, context) => {
    const newValue = snap.data();
    const word = newValue.word;
    getWordDetailsFromDictionaryAPI(word);
});

Receber uma lista de palavras do jogo

É possível criar uma função do Cloud que recupera uma lista de palavras da prática de ortografia do Cloud Firestore para o Google Assistente. Para isso, usamos o gerenciador de apps.

No arquivo index.js, substitua o TODO por getSpellingWordList pelo seguinte.

A adição dessa função ao app.handle especial é uma forma de torná-la acessível pelo Google Assistente.

index.js

// Store the list of spelling words in Assistant session
app.handle('getSpellingWordList', conv => {
  const wordListRef = db.collection('wordlist').limit(50);
  const snapshot = wordListRef;

  if (snapshot.empty) {
    console.log('No matching documents.');
    return;
  }
  VocabularyList = []

  return snapshot.get().then(snapshot => {
    snapshot.forEach(doc => {
      if (doc.data().word) {
          let definition = 'unknown';
          let audio = 'unknown';
          try {
            if(doc.data().hasOwnProperty('meanings')) {
              if(doc.data().meanings[0].hasOwnProperty('definitions')) {
                  definition = doc.data().meanings[0].definitions[0].definition;
              }
            }
            if(doc.data().hasOwnProperty('phonetics')) {
              if(doc.data().phonetics.length > 0)
                audio = doc.data().phonetics[0].audio;
            }
          } catch (error) {
            console.log(error);
          }

          let obj = {
            word: doc.data().word,
            answer: doc.data().word.split("").join(" "),
            definition: definition,
            audio: audio
          }
          VocabularyList.push(obj);
      }
      // Shuffle the array
      let currentIndex = VocabularyList.length, temporaryValue, randomIndex;
      while (0 !== currentIndex) {
        randomIndex = Math.floor(Math.random() * currentIndex);
        currentIndex -= 1;
        temporaryValue = VocabularyList[currentIndex];
        VocabularyList[currentIndex] = VocabularyList[randomIndex];
        VocabularyList[randomIndex] = temporaryValue;
      }
      conv.session.params.vocabWord = VocabularyList;
      conv.session.params.vocabWordIndex = 0;
    });
  });
})

Receber uma palavra da sessão do Google Assistente

É possível escrever uma função do Cloud que retorna a próxima ortografia da lista de palavras.

No arquivo index.js, substitua o TODO por getSpellingWord pelo seguinte:

index.js

// Returns a spelling practice word to Google Assistant and uses Speech Synthesis Markup Language (SSML) to format the response
app.handle('getSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    conv.session.params.vocabWordIndex+=1;
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word.</audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Ativar o jogo para repetir a palavra

Crie uma função do Cloud que repita a palavra atual do jogo.

No arquivo index.js, substitua o TODO por repeatSpellingWord pelo seguinte:

index.js

// Returns current spelling word
app.handle('repeatSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word. </audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Ver a definição da palavra

É possível escrever uma função do Cloud que fornece a definição da palavra atual para o jogo.

No arquivo index.js, substitua o TODO por definitionOfSpellingWord pelo seguinte:

index.js

// Returns spelling word definition from Assistant session parameter
app.handle('definitionOfSpellingWord',  conv => {
  conv.add( 'It means ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].definition);
});

Verificar a resposta ortográfica do usuário

É possível criar uma função do Cloud que verifica a resposta do usuário sobre a ortografia da palavra atual do jogo.

No arquivo index.js, substitua o TODO por verifySpellingWord pelo seguinte:

index.js

// Verifies user spelling response
app.handle('verifySpellingWord', conv => {
  try {
    userResponse = conv.intent.params.userresponse.resolved.join("");
    if (userResponse.toLowerCase() === conv.session.params.vocabWord[conv.session.params.vocabWordIndex].word.toLowerCase()) {
      conv.add('You are correct. Say next to continue.');
    }
    else {
      conv.add('Sorry, wrong answer. The correct answer is ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].answer + ' . Say next to continue.');
    }
  } catch (error) {
    conv.add('Sorry. I did not understand your response' );
  }
});
exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Implantar todas as suas funções

O Cloud Functions só estará ativo depois de ser implantado no Firebase.

Na raiz do diretório spelling-functions-start, execute o seguinte comando:

$ firebase deploy --only functions

Esta é a resposta do console que você deverá ver:

i  deploying functions
i  functions: ensuring necessary APIs are enabled...
⚠  functions: missing necessary APIs. Enabling now...
i  env: ensuring necessary APIs are enabled...
⚠  env: missing necessary APIs. Enabling now...
i  functions: waiting for APIs to activate...
i  env: waiting for APIs to activate...
✔  env: all necessary APIs are enabled
✔  functions: all necessary APIs are enabled
i  functions: preparing functions directory for uploading...
i  functions: packaged functions (X.XX KB) for uploading
✔  functions: functions folder uploaded successfully
i  starting release process (may take several minutes)...
i  functions: creating function createSpellingPracticeWord(us-central1)...
✔  functions[createSpellingPracticeWord(us-central1)]: Successful create operation.
i  functions: creating function ActionsOnGoogleFulfillment(us-central1)...
✔  functions[ActionsOnGoogleFulfillment(us-central1)]: Successful create operation.

✔  Deploy complete!
Project Console: https://console.firebase.google.com/project/spelling-practice-1234/overview

Anote o URL do endpoint HTTP da função ActionsOnGoogleFulfillment para uso posterior. Para acessar o endpoint, abra o Console do Firebase e clique no projeto spsell-Practice. Abra o painel do Functions para visualizar o endpoint das funções.

Você concluiu a adição de todas as funções necessárias. Agora vamos configurar o Cloud Firestore.

8. Ativar o Cloud Firestore

Será necessário ativar o Cloud Firestore.

Na seção Build do Console do Firebase, clique em Firestore. Em seguida, clique em Criar banco de dados.

O acesso aos dados no Cloud Firestore é controlado por regras de segurança. Primeiro, você precisa definir algumas regras básicas para os dados. Clique em Firestore e, na guia "Regras" do Console do Firebase, adicione as regras a seguir e clique em Publicar.

As regras abaixo restringem o acesso aos dados aos usuários que fizeram login, o que impede que usuários não autenticados leiam ou gravem algo.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      //
      // WARNING: These rules are insecure! We will replace them with
      // more secure rules later in the codelab
      //
      allow read, write: if request.auth != null;
    }
  }
}

9. Adicionar dados de palavras ortográficas ao Cloud Firestore

Nesta etapa, você vai gravar dados de palavras ortográficas no Cloud Firestore para gerar uma lista de palavras para o Google Assistente e para o jogo.

Os dados do Cloud Firestore são estruturados em coleções, documentos, campos e subcoleções. Cada palavra do jogo será armazenada como um documento próprio em uma coleção de nível superior chamada wordlist. Para cada novo documento na coleção do Firestore, a função createMaskingPracticeWord será acionada para acessar os detalhes da palavra no serviço da API Dictionary.

Criar uma coleção do Cloud Firestore

1. No Console do Firebase, navegue até a seção do Cloud Firestore.
2. Clique em + Iniciar coleção.
3. Na caixa de texto ID da coleção, digite wordlist e clique em Próxima.

Em seguida, vamos criar um documento para uma palavra: agreement

4. Na caixa de texto ID do documento, digite agreement.
5. Na caixa de texto Campo, insira word e agreement na caixa de texto Valor.
6. Clique em Salvar.

Quando você adiciona este documento ao Cloud Firestore, ele aciona a função creategrafiaPracticeWord para buscar os detalhes de definição da palavra. Adicione mais palavras (por exemplo: maravilha, carro, verdadeiro, contar, melhor, deslocamento diário...) criando um novo documento para cada palavra.

10. Configurar o Google Assistente

As seções a seguir descrevem como configurar o ambiente de desenvolvimento do Google Assistente e criar seu projeto do Actions.

Verifique suas configurações de permissão do Google

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

1. Acesse a página Controles de atividade.
2. Faça login com sua Conta do Google, caso ainda não tenha feito isso.
3. Ative as seguintes permissões:

• Atividade na Web e de apps
• Em Atividade na Web e de apps, marque a caixa de seleção ao lado de Incluir o histórico do Chrome e a atividade em sites, apps e dispositivos que usam serviços do Google.

Crie um projeto do Actions

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

1. Abra o Console do Actions.
2. Clique em Novo projeto.
3. Aceitar os Termos de Serviço

4. Digite ou selecione o spelling-practice-codelab que você criou com o console do Firebase. O nome serve para referência interna. Depois, você pode definir um nome externo para o projeto.

5. Clique em Importar projeto.
6. Na tela Que tipo de ação você quer criar?, selecione o card Personalizado.
7. Clique em Próxima.
8. Selecione o card Projeto em branco.
9. Clique em Começar a criar.
10. Digite Ortografia para o nome de exibição e clique em "Salvar".

Os usuários iniciam a conversa com sua ação usando uma invocação. Por exemplo, os usuários podem invocar sua Ação dizendo uma frase como "Ok Google, fale com a prática de ortografia", em que Prática de ortografia é o nome de exibição.

Sua Ação precisa ter um nome de exibição se quiser implantá-la para produção. No entanto, para testá-la, não é necessário defini-lo. Em vez disso, você pode usar a frase "Falar com meu app de teste" no simulador para invocar sua ação.

Configurar fulfillment

Você precisa conectar ao Assistente os manipuladores de eventos das funções do Cloud que você escreveu e implantou anteriormente neste codelab.

Para configurar o fulfillment, siga estas etapas:

1. Clique em Webhook na navegação lateral.
2. Selecione Endpoint HTTP como opção de fulfillment:

3. Digite o URL do endpoint da função na caixa de texto Endpoint HTTPs e clique em Salvar.

Na próxima seção, você vai personalizar a solicitação da invocação principal no Console do Actions.

Configurar a invocação principal

Edite a invocação principal para definir o que acontece depois que um usuário invoca a ação.

Por padrão, o Actions Builder fornece uma solicitação genérica quando a invocação é acionada ("Comece a criar sua ação definindo a invocação principal").

Para modificar a solicitação que a Ação envia de volta ao usuário quando ele a invoca, siga estas etapas:

1. Clique em Invocação principal na navegação.

2. Marque Call your webhook e adicione o nome do manipulador de eventos getSpellingWordList na caixa de texto.
3. No editor de código, substitua o texto no campo speech pela seguinte mensagem de boas-vindas: Welcome to Spelling Practice

Observação:é possível usar a formatação YAML ou JSON para editar os comandos.

4. Clique em Salvar.

Testar a invocação principal no simulador

O Console do Actions tem uma ferramenta da Web para testar sua ação chamada simulador. A interface simula dispositivos de hardware e as configurações deles. Assim, é possível conversar com a ação como se ela estivesse sendo executada em um smart display, smartphone, alto-falante ou KaiOS.

Para testar a invocação principal da sua ação no simulador, siga estas etapas:

1. Na barra de navegação superior, clique em Testar para acessar o simulador.
2. Para invocar sua Ação no simulador, digite Talk to Spelling Practice no campo de entrada no canto superior esquerdo e pressione Enter no teclado.

Quando você aciona a invocação principal da Ação, o Google Assistente responde com sua mensagem de boas-vindas personalizada. Nesse momento, a conversa termina depois que o Google Assistente responde com uma saudação.

Acessar logs de eventos

Na guia Teste, o painel à direita mostra os logs de eventos, que mostram o histórico de conversas como logs de eventos. Cada log de eventos exibe os eventos que aconteceram durante aquele turno da conversa. Para visualizar o log de eventos, clique no ícone cinza antes do evento.

No momento, sua Ação tem um log de eventos, que mostra a entrada do usuário ("Falar com a prática de ortografia) e a resposta da Ação. A captura de tela a seguir mostra o log de eventos da Ação:

11. Prepare a conversa para a prática de ortografia

Agora que você definiu o que acontece depois que um usuário invoca sua ação, pode desenvolver o restante da conversa. A Ortografia tem quatro cenas, e você precisa ativar cada uma delas antes da execução. A maneira mais comum de ativar uma cena é configurar sua ação para que, quando um usuário corresponder a uma intent de usuário em uma cena, essa intent acione a transição para outra cena e a ative.

Transição da invocação principal para o início da cena

Nesta seção, você vai criar uma nova cena chamada Start, que envia uma solicitação ao usuário perguntando se ele quer começar a jogar a Ortografia. Você também adiciona uma transição da invocação principal para a nova cena Start.

Para criar essa cena e adicionar uma transição, siga estas etapas:

1. Clique em Desenvolver na navegação da parte de cima. Em seguida, clique em Invocação principal no painel de navegação à esquerda.
2. Na seção Transição à direita, clique no menu suspenso e digite Start no campo de texto.

3. Clique em Adicionar. Isso cria uma cena chamada Start e instrui a ação a fazer a transição para a cena Start após enviar a solicitação de boas-vindas ao usuário.
4. Clique em Cenas na navegação à esquerda para mostrar a lista de cenas.
5. Em Cenas, clique em Iniciar para conferir a cena Start.
6. Clique em + na seção Ao inserir da cena Start.
7. Selecione Enviar solicitações.
8. Substitua a frase no campo speech (Enter the response that users will see or hear...) por uma pergunta para fazer ao usuário: Use phonetic alphabet to spell the word. For example alpha for a, bravo for b, charlie for c etc. Do you want to continue?

Os ícones de sugestão oferecem sugestões clicáveis para o usuário que sua Ação processa como entrada do usuário. Nesta seção, você vai adicionar ícones de sugestão que aparecem abaixo da solicitação que acabou de configurar (Do you want to play)

Spelling Practice

?) para oferecer suporte aos usuários em dispositivos com telas.

Para adicionar ícones de sugestão ao comando de cena Start, siga estas etapas:

9. Na cena Start, clique em "Sugestões" abaixo do editor de código. Esta ação adiciona um único ícone de sugestão.
10. No campo title, substitua Suggested Response por 'Yes'.
11. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'No' e 'Help with Phonetics'. O código vai ficar parecido com este snippet:
12. Clique em Salvar.

Testar sua ação no simulador

Nesse ponto, a ação precisa fazer a transição da invocação principal para a cena Start e perguntar ao usuário se ele quer continuar. Os ícones de sugestão também devem aparecer na tela simulada.

Para testar sua ação no simulador, siga estas etapas:

1. Na barra de navegação, clique em Testar para acessar o simulador.
2. Para testar sua ação no simulador, digite Talk to Spelling Practice no campo de entrada.
3. Pressione Enter. Sua Ação precisa responder com o comando Main invocation e a solicitação de cena Start adicionada, Bem-vindo à prática de ortografia. Use o alfabeto fonético para escrever a palavra. Por exemplo, "alfa" para a, "bravo" para b, "charlie" para "c" etc. Você quer continuar?".

A captura de tela a seguir mostra essa interação:

4. Clique no ícone de sugestão Yes, No ou Help with Phonetics para responder à solicitação. Você também pode dizer "Sim", "Não" ou "Ajuda com fonética" ou digitar Yes, No ou Help with Phonetics no campo Entrada.

Quando você responde à solicitação, sua Ação responde com uma mensagem indicando que não entendeu sua entrada: "Não entendi. Pode tentar de novo?" Como você ainda não configurou a ação para entender e responder à entrada "Sim" ou "Não", a ação vai fazer a correspondência da entrada com uma intent NO_MATCH.

Por padrão, a intent do sistema NO_MATCH fornece respostas genéricas, mas elas podem ser personalizadas para indicar ao usuário que você não entendeu a entrada. O Google Assistente encerra a conversa do usuário com sua ação quando não consegue associar a entrada do usuário três vezes.

Adicionar intents fonéticas

Agora que os usuários podem responder à pergunta que a Ação faz, é possível configurá-la para entender as respostas deles ("Sim", "Não" ou "Ajuda com fonética"). Nas seções a seguir, você vai criar intents que são correspondidas quando o usuário diz "Yes" ou "No" ou "Help with Phonetics" e as adiciona à cena Start. Vamos usar a intent do sistema yes e criar outras intents.

Criar intent no

Agora, você precisa criar a intent no para entender e responder ao usuário quando ele não quiser jogar. Para criar essa intent, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Clique em Intents personalizadas na navegação para abrir a lista de intents.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent no e pressione Enter.
4. Clique em não para abrir a página da intent no.
5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as seguintes frases:

• No
• N
• I don't want
• nope

6. Clique em Salvar.

Adicionar a intent no à cena Start

Agora, a ação consegue entender quando um usuário está expressando "não" ou algo semelhante a "não", como "não". Você precisa adicionar a intent de usuário no à cena Start porque o usuário está respondendo ao comando Start ("Esta é a prática de ortografia. Use o alfabeto fonético para escrever a palavra. Por exemplo, "alfa" para a, "bravo" para "b", "charlie" para "c" etc. Você quer continuar?").

Para adicionar essa intent à cena Start, siga estas etapas:

1. Clique na cena Iniciar na navegação.
2. Clique em + (sinal de adição) na cena Start ao lado de "Processamento da intent do usuário".
3. Na seção Intent, selecione não no menu suspenso.

4. Clique em Enviar solicitações e atualize o campo speech com o seguinte texto: Good Bye.

O código no seu editor vai ficar parecido com este snippet:

candidates:
  - first_simple:
      variants:
        - speech: >-
             Goodbye.

5. Na seção Transição, selecione Encerrar conversa no menu suspenso.
6. Clique em Salvar.

Testar a intent no no simulador

Nesse ponto, sua ação entende quando o usuário não quer jogar e retorna a resposta adequada.

Para testar essa intent no simulador, siga estas etapas:

1. Na barra de navegação, clique em Testar.
2. Digite Talk to Spelling Practice no campo de entrada e pressione Enter.
3. Digite No no campo Entrada e pressione Enter. Você também pode clicar no ícone "Nenhuma sugestão".

Adicionar a intent YES do sistema à cena Start

Agora, vamos adicionar a intent SYSTEM "YES" à cena Start, já que o usuário está respondendo "sim" ao comando Start ("Welcome to Corretoing Practice. Use o alfabeto fonético para escrever a palavra. Por exemplo, "alfa" para a, "bravo" para "b", "charlie" para "c" etc. Você quer continuar?").

Para adicionar essa intent de usuário à cena Start, siga estas etapas:

1. Clique na cena Iniciar na navegação.
2. Clique em + (sinal de adição) na cena Start ao lado de Processamento da intent do usuário.
3. Em "Todas as intents do sistema", selecione SIM no menu suspenso de intents.

4. Clique em Call your webhook e atualize a caixa de texto event handler com a função que você criou anteriormente: getSpellingWordList
5. Na seção Transição, clique no menu suspenso e selecione Encerrar conversa.
6. Clique em Salvar.

Testar a intent YES no simulador

Nesse ponto, sua Ação entende quando o usuário quer jogar e retorna a resposta adequada.

Para testar essa intent no simulador, siga estas etapas:

1. Na barra de navegação, clique em Testar.
2. Para testar sua ação no simulador, digite Talk to Spelling Practice no campo Entrada e pressione Enter.
3. Digite Yes no campo Entrada e pressione Enter. Ou clique no ícone de sugestão Yes.

Sua Ação busca uma lista de todas as palavras de prática de ortografia e as armazena na sessão. Sua Ação encerra a sessão porque você selecionou a transição End conversation para a intent YES.

Criar intent Phonetics

Para criar a intent Phonetics, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Clique em Intents personalizadas na navegação para abrir a lista de intents.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent phonetics e pressione Enter.
4. Clique na intent phonetics para abrir a página da intent phonetics.
5. Na seção "Adicionar frases de treinamento", clique na caixa de texto Inserir frase e digite as seguintes frases:

• how do I spell words
• phonetics
• help me with phonetics
• phonetic alphabet

6. Clique em Salvar.

Adicionar a intent phonetics à cena Start

Agora, a ação pode entender quando um usuário está expressando uma intent "fonética". Você pode adicionar a intent de usuário phonetics à cena Start, já que o usuário está respondendo ao comando Start ("Esta é a prática de ortografia. Use o alfabeto fonético para escrever a palavra. Por exemplo, "alfa" para a, "bravo" para "b", "charlie" para "c" etc. Você quer continuar?").

Para adicionar essa intent de usuário à cena Start, siga estas etapas:

1. Clique na cena Iniciar na navegação.
2. Clique em + (sinal de adição) na cena Start ao lado de "Processamento da intent do usuário".
3. Selecione fonética no menu suspenso de intents.

4. Na seção Transição, clique no menu suspenso e selecione Encerrar conversa.
5. Clique em Salvar.

Transição da cena inicial para a cena de ortografia

Nesta seção, você vai criar uma nova cena chamada Ortografia, que envia uma solicitação para o usuário soletrar a palavra usando o alfabeto fonético.

Para criar essa cena e adicionar uma transição, siga estas etapas:

1. Clique em Desenvolver na navegação da parte de cima. Em seguida, clique em Iniciar cena no painel de navegação à esquerda.
2. Na seção Processamento da intent do usuário, clique em when actions.intent.YES is matched e, à direita da seção de transição, clique no menu suspenso e digite Spelling no campo de texto.
3. Clique em Adicionar. Isso cria uma cena chamada Spelling e instrui a ação a fazer a transição para a cena Spelling após a correspondência com a intent YES.
4. Expanda Scenes na navegação à esquerda para mostrar a lista de cenas.
5. Em Cenas, clique em "Ortografia" para ver a cena Spelling.
6. Clique em + na seção Ao inserir da cena Spelling.
7. Clique em Chamar seu webhook e digite getProofingWord na caixa de texto do manipulador de eventos.
8. Selecione Enviar solicitações.
9. Substitua a frase no campo speech (Enter the response that users will see or hear...) por {}. A solicitação real será preenchida pelo webhook.

Os ícones de sugestão oferecem sugestões clicáveis para o usuário que sua Ação processa como entrada do usuário.

Para adicionar ícones de sugestão ao comando de cena Spelling, siga estas etapas:

10. Na cena Spelling, clique em "Sugestões" abaixo do editor de código. Esta ação adiciona três ícones de sugestão.
11. No campo title, substitua Suggested Response por 'Repeat'.
12. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Skip'.
13. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'. O código vai ficar parecido com este snippet:
14. Clique em Salvar.

suggestions:
      - title: 'Repeat'
      - title: 'Skip'
      - title: 'Quit'

Criar intent Repeat

Para criar a intent repeat, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Clique em Intents personalizadas na navegação para abrir a lista de intents.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent repeat e pressione Enter.
4. Clique na intent repeat para abrir a página da intent definition.
5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as seguintes frases:

• one more time please
• say the word again
• repeat the word
• tell me again
• repeat

6. Clique em Salvar.

Adicionar a intent repeat à cena Spelling

Agora, a ação pode entender quando um usuário está expressando uma intent "repeat". É possível adicionar a intent de usuário repeat à cena Spelling, já que o usuário está respondendo ao comando Spelling ("Soletrar a palavra usando alfabeto fonético").

Para adicionar essa intent de usuário à cena Spelling, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique em + (sinal de adição) na cena Spelling ao lado de Processamento da intent do usuário.
3. Selecione repeat no menu suspenso de intents.

4. Marque a caixa Chamar seu webhook e digite repeatritaWord na caixa de texto do manipulador de eventos para ver a definição da palavra.
5. Marque a opção Enviar solicitações.
6. Substitua a frase no campo speech (Enter the response that users will see or hear...) por "". A solicitação real será preenchida pelo webhook.

Adicionar ícones de sugestão a "Quando a repetição for atendida"

7. Em Quando a repetição for correspondida, em "Processamento da intenção do usuário", clique em sugestões abaixo do editor de código. Esta ação adiciona três ícones de sugestão.
8. No campo title, substitua Suggested Response por 'Skip'.
9. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código vai ficar parecido com este snippet:

suggestions:
      - title: 'Skip'
      - title: 'Quit'

10. Clique em Salvar.

Criar intent definition

Para criar a intent definition, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Clique em Intents personalizadas na navegação para abrir a lista de intents.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent definition e pressione Enter.
4. Clique na intent definition para abrir a página da intent definition.
5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as seguintes frases:

• I would like to know the definition
• tell me the definition
• what does it mean
• meaning
• definition
• what is the definition?

6. Clique em Salvar.

Adicionar a intent definition à cena Spelling

Agora, a ação pode entender quando um usuário está expressando uma intent de "definição". É possível adicionar a intent de usuário definition à cena Spelling, já que o usuário está respondendo ao comando Spelling ("Soletrar a palavra usando alfabeto fonético").

Para adicionar essa intent de usuário à cena Spelling, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique em + (sinal de adição) na cena Spelling ao lado de Processamento da intent do usuário.
3. Selecione definition no menu suspenso da intent.

4. Marque Call your webhook e digite definitionOf filtros de palavras na caixa de texto do manipulador de eventos para ver a definição da palavra.
5. Marque a opção Enviar solicitações.
6. Substitua a frase no campo speech (Enter the response that users will see or hear...) por "‘". O prompt real será preenchido pelo webhook.

Adicionar ícones de sugestão à resposta do webhook

7. Na cena Start, clique em sugestões abaixo do editor de código. Esta ação adiciona três ícones de sugestão.
8. No campo title, substitua Suggested Response por 'Skip'.
9. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código vai ficar parecido com este snippet:

suggestions:
      - title: 'Skip'
      - title: 'Quit'

10. Clique em Salvar.

Criar intent skip

Para criar a intent skip, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Para abrir a lista, clique em Intents na navegação.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent skip e pressione Enter.
4. Clique na intent skip para abrir a página da intent skip.
5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as seguintes frases:

• next word
• go next
• next
• skip
• skip word

6. Clique em Salvar.

Adicionar a intent Skip à cena Spelling

Agora, a ação pode entender quando um usuário está expressando uma intent "skip". É possível adicionar a intent de usuário skip à cena Spelling, já que o usuário está respondendo ao comando Spelling ("Soletrar a palavra usando alfabeto fonético").

Para adicionar essa intent de usuário à cena Spelling, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique no + (sinal de adição) na cena Spelling ao lado de Manual da intent do usuário.
3. Selecione skip no menu suspenso da intent.

4. Na seção Transição à direita, clique no menu suspenso e selecione Spelling .

5. Clique em Salvar.

Criar intent quit

Para criar a intent Quit, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Para abrir a lista, clique em Intents na navegação.
3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent Quit e pressione Enter.
4. Clique na intent Quit para abrir a página da intent de definição.
5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as seguintes frases:

• I quit
• Goodbye
• Cancel
• Exit
• Quit

6. Clique em Salvar.

Adicionar a intent Quit à cena Spelling

Agora, a ação pode entender quando um usuário está expressando uma intent "quit". É possível adicionar a intent de usuário quit à cena Spelling, já que o usuário está respondendo ao comando Spelling ("Soletrar a palavra usando alfabeto fonético").

Para adicionar essa intent de usuário à cena Spelling, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique em + (sinal de adição) na cena Spelling ao lado de Processamento da intent do usuário.
3. Selecione quit no menu suspenso da intent.

4. Na seção Transição à direita, clique no menu suspenso e selecione End conversation .
5. Clique em Salvar.

Criar tipo phonetic_alphabet

Nesta seção, você vai criar um novo tipo chamado phonetic_alphabet, que especifica as opções do alfabeto fonético que os usuários podem escolher para escrever a palavra. Você também pode definir alguns sinônimos para essas opções caso um usuário diga algo semelhante. Em uma seção posterior, você vai adicionar o tipo phonetic_alphabet a um slot para especificar que quer acessar a resposta do usuário.

Para criar o tipo phonetic_alphabet, siga estas etapas:

1. Clique em Desenvolver na navegação.
2. Em Tipos, clique no + (sinal de adição).
3. Digite phonetic_alphabet e pressione Enter.
4. Clique em phonetic_alphabet para abrir as opções.
5. Na seção Que tipo de valores este Tipo suporta?, selecione a opção Palavras e sinônimos
6. Digite as entradas e os valores correspondentes abaixo na seção Adicionar entradas:

A tabela de chave-valor será semelhante a esta:

8. Clique em Salvar.

Configurar o preenchimento de slot

Em seguida, você precisa configurar o preenchimento de slot na cena de ortografia. Para configurar a lógica de preenchimento de slot, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique em + (sinal de adição) na cena Spelling para Preenchimento de slot.
3. No campo Inserir o nome do slot, adicione userresponse como o nome do slot.
4. No menu suspenso Selecionar tipo, escolha phonetic_alphabet como o tipo de slot.
5. Marque a opção Este slot aceita uma lista de valores.
6. Marque a opção Este slot é obrigatório.
7. Selecione a opção Personalizar gravação de valor do slot e digite a resposta do usuário na caixa de texto do parâmetro da sessão.

8. Clique em Salvar.

Adicionar condição à tela Spelling

Para adicionar a condição à cena Spelling, siga estas etapas:

1. Clique na cena Ortografia na navegação.
2. Clique em + (sinal de adição) na cena Spelling ao lado de "Condição".
3. Insira scene.slots.status == "FINAL" como condição
4. Marque a opção Chamar seu webhook e digite verifyProofingWord na caixa de texto do manipulador de eventos para verificar a resposta do usuário.
5. Marque a opção Enviar solicitações.
6. Substitua a frase no campo speech (Enter the response that users will see or hear...) por {}. O prompt real será preenchido pelo webhook.

Adicionar ícones de sugestão à resposta do webhook

7. Na cena Start, clique em sugestões abaixo do editor de código. Esta ação adiciona três ícones de sugestão.
8. No campo title, substitua Suggested Response por 'Next'.
9. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código vai ficar parecido com este snippet:

suggestions:
      - title: 'Next'
      - title: 'Quit'

10. Clique em Salvar.

12. Teste a prática de ortografia no simulador

Para testar sua ação no simulador, siga estas etapas:

1. Na barra de navegação, clique em Testar para acessar o simulador.
2. Para testar sua ação no simulador, digite Talk to Spelling Practice no campo de entrada.
3. Pressione Enter. Sua Ação precisa responder com o comando Main invocation e a solicitação de cena Start adicionada, Bem-vindo à prática de ortografia. Use o alfabeto fonético para escrever a palavra. Por exemplo, "alfa" para a, "bravo" para b, "charlie" para "c" etc. Você quer continuar?".
4. Diga Sim para continuar
5. O simulador vai emitir um som de palavras para soletrar
6. Você pode soletrar a palavra usando alfabetos fonéticos. Por exemplo, para melhor, diga ou digite "bravo eco tango tango eco romeo".
7. O simulador vai responder com a resposta correta ou incorreta.
8. Diga próximo para continuar para a próxima palavra ou diga sair para sair do loop de jogo.

13. Parabéns

Parabéns! Você criou o jogo Ortografia.

Agora você sabe as principais etapas necessárias para criar um jogo usando o Cloud Firestore, o Cloud Functions e o Google Assistente Action Builder.

O que você aprendeu

• Como interagir com o Cloud Firestore
• Como usar slots para coletar dados do usuário.
• Como processar a entrada de um usuário e retornar uma resposta.
• Como usar condições para adicionar lógica a uma cena
• Como adicionar um loop de jogo

Outros recursos de aprendizado

Confira estes recursos para aprender a criar ações para o Google Assistente:

• Documentação para desenvolver ações para o Google Assistente
• Página do Actions on Google no GitHub com exemplos de código e bibliotecas
• A comunidade oficial do Reddit para desenvolvedores que trabalham com o Google Assistente
• Diretrizes de design de conversa: práticas recomendadas e orientações sobre ações de conversa
• Introdução ao Cloud Firestore

Limpar seu 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 Firebase, conclua as etapas listadas na seção Como encerrar (excluir) projetos.

Cuidado: selecione o projeto correto para exclusão na página Configurações do console do Google Cloud.

2. Opcional: para remover seu projeto imediatamente do Console do Actions, conclua as etapas da seção Como excluir um projeto. Se você não concluir esta etapa, seu projeto será removido automaticamente após aproximadamente 30 dias.

Siga @ActionsOnGoogle e @Firebase no Twitter para ficar por dentro dos nossos comunicados mais recentes e envie um tweet para o #GoogleIO para mostrar o que você criou.