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

1. Visão geral

A plataforma de desenvolvedores do Google Assistente permite criar softwares para ampliar a funcionalidade desse assistente pessoal virtual 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 Assistente em conversas para realizar tarefas, como fazer compras de mercado 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 entre o usuário e seu próprio serviço de atendimento terceirizado.

Este codelab aborda 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 "Spelling Practice" que usa o Google Assistente para pedir que os usuários soletrem 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 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 digitar a palavra;

Antes de começar a criar, você pode interagir com a ação ativa no dispositivo com o Google Assistente. Basta dizer "Ok Google, falar com Spelling Practice (Treino 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 o seguinte:

• 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, 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 de funções

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

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

3. Criar um projeto do Firebase e configurar seu 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 o projeto do Firebase como Spelling-Practice.

3. Clique nas opções de criação do projeto. Se for solicitado, aceite os termos do Firebase. Ignore a configuração do Google Analytics, porque você não vai usá-lo para este app.

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

Fazer upgrade para o plano de preços Blaze

Para usar o Cloud Functions para Firebase, você precisará fazer upgrade do seu projeto do Firebase para o plano de preços Blaze. Isso significa que você vai anexar uma conta do Google Cloud Billing ao seu projeto. Para isso, você precisa fornecer 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 custo financeiro do Cloud Functions. As etapas descritas neste codelab estão dentro dos limites de uso sem custo financeiro. No entanto, você receberá pequenas cobranças ( cerca de US $0,03) do Cloud Storage, que é usado para hospedar as 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 para instalar a 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. Verifique 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 comando:

$ firebase --version

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

4. Autorize a CLI do Firebase executando o seguinte comando:

$ firebase login

5. No diretório spelling-functions-start, configure a CLI do Firebase para usar seu projeto do Firebase. 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ê vai adicionar funcionalidades usando o SDK do Firebase para Cloud Functions para criar o back-end do jogo: Prática ortográfica.

O Cloud Functions permite que você tenha código que é executado na nuvem sem precisar configurar um servidor. Neste codelab, você vai aprender a criar funções que reagem aos eventos do Firebase Authentication, Cloud Storage e Firebase Realtime Database. Vamos começar com a autenticação.

Ao usar o SDK do Firebase para Cloud Functions, o código das funções fica no diretório functions (por padrão). Para facilitar, já criamos o arquivo functions/index.js, onde o código será colocado. Você pode inspecionar o diretório functions antes de continuar.

$ cd functions
$ ls

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

Se você não conhece o Node.js, saiba mais sobre ele antes de continuar o codelab.

O arquivo package.json já lista duas dependências necessá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ê vai 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 gravar os gatilhos das nossas funções do Cloud
• O módulo firebase-admin permite usar a plataforma Firebase em um servidor com acesso de administrador, por exemplo, para gravar no Cloud Firestore.
• A biblioteca de fulfillment do SDK do Actions para Node.js atende aos gerenciadores do SDK do Actions para o 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 outros contêineres do Google Cloud. Isso 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 a lógica de negócios usando funções para oferecer suporte às ações do Google Assistente.

7. Criar funções

Receber 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 de 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 será acionada sempre que um novo documento for criado no Cloud Firestore. Ele vai chamar a API dictionaryapi.dev para receber as definições de palavras usando a função getWordDetailsFromDictionaryAPI que criamos acima.

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

index.js

// Acionador do Firestore que busca definições de palavras usando a API getWordDetailsFromDictionary 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);
});

Conseguir uma lista de palavras para o jogo

Você pode escrever uma função do Cloud que extrai uma lista de palavras de prática de ortografia do Cloud Firestore para o Google Assistente. Para isso, usamos o gerenciador de aplicativos.

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

Adicionar essa 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 palavra ortográfica da lista de palavras.

No arquivo index.js, substitua o TODO de 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');
});

Permitir que o jogo repita a palavra

Você pode criar uma função do Cloud que repita a palavra atual para o jogo.

No arquivo index.js, substitua o TODO para 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');
});

Conferir 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 de 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

Você pode escrever uma função do Cloud que verifique a resposta do usuário sobre como soletrar a palavra atual do jogo.

No arquivo index.js, substitua o TODO para 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 funções

As funções do Cloud só vão ficar ativas depois de serem implantadas 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 usar o endpoint, abra o Console do Firebase e clique no projeto spelling-practices. 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

Você precisará 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 pelas Regras de segurança. Primeiro, você precisa definir algumas regras básicas sobre os dados para começar. Clique em Firestore e, na guia Regras do Console do Firebase, adicione as regras a seguir e clique em Publicar.

As regras a seguir restringem o acesso aos dados para usuários conectados, o que impede que usuários não autenticados leiam ou gravem.

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 ortografia de palavras ao Cloud Firestore

Nesta etapa, você vai gravar dados de palavras com ortografia no Cloud Firestore para gerar uma lista de palavras para o Google Assistente e 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 em uma coleção de nível superior chamada wordlist. Para cada novo documento na coleção do Firestore, a função createWordingPracticeWord será acionada para receber os detalhes da palavra do 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, criaremos um documento para uma palavra: agreement

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

Quando você adiciona esse documento ao Cloud Firestore, ele aciona a função createWordingPracticeWord para buscar os detalhes da definição da palavra. Adicione mais palavras (por exemplo: admiração, carro, verdade, falar, 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 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

O 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. Aceitar os Termos de Serviço

4. Digite ou selecione o spelling-practice-codelab que você criou usando o Console do Firebase. O nome é apenas para referência interna. É possível definir um nome externo para o projeto mais tarde.

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. Insira Spelling Practice como 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, falar com o Spelling Practice, em que Spelling Practice é o nome de exibição.

Para ser implantada na produção, sua ação precisa ter um nome de exibição. Mas isso não é necessário para fazer testes. Em vez disso, você pode usar a frase "Falar com meu app de teste" no simulador para invocar a ação.

Configurar fulfillment

É necessário conectar ao Google Assistente os manipuladores de eventos das Funções do Cloud que você criou e implantou anteriormente neste codelab.

Para configurar o fulfillment, siga estas etapas:

1. Clique em Webhook na navegação lateral.
2. Selecione Endpoint HTTPS 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 sua ação.

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

Para modificar a solicitação que sua ação retorna 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 uma ação chamada simulador. A interface simula dispositivos e configurações de hardware. Dessa forma, você pode conversar com a ação como se estivesse sendo executada em um smart display, smartphone, alto-falante ou KaiOS.

Para testar a invocação principal da 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 personalizada de boas-vindas. Nesse momento, o Google Assistente responde com uma saudação, e a conversa termina.

Conferir os registros de eventos

Quando estiver na guia Teste, o painel à direita vai mostrar os logs de eventos, que mostram o histórico de conversas como logs de eventos. Cada log exibe os eventos que ocorrem durante aquela parte da conversa. Para conferir o registro 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. Confira o log de eventos da sua Action na captura de tela a seguir:

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

Agora que você já definiu o que acontece depois que um usuário invoca sua ação, já pode criar o restante da conversa. A Prática de ortografia tem quatro cenas, e você precisa ativar cada uma delas antes da exibição. A maneira mais comum de ativar uma cena é configurar a ação para que, quando a entrada do usuário corresponder a uma intent dentro de uma cena, essa intent acione a transição e ative outra cena.

Transição da invocação principal para iniciar a cena

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

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

1. Clique em Desenvolver na navegação superior. 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 vai criar uma cena chamada Start e instruir a ação a fazer a transição para a cena Start depois que ela entregar 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 ver 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 o 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 que a ação processa como uma entrada do usuário. Nesta seção, você vai adicionar os ícones de sugestão que aparecem abaixo da solicitação que acabou de configurar (Do you want to play).

Spelling Practice

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

Para adicionar ícones de sugestão à solicitação de cena Start, siga estas etapas:

9. Na cena Start, clique nas 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 a 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 "Entrada".
3. Pressione Enter. Sua ação precisa responder com a solicitação Main invocation e a solicitação de cena Start adicionada, "Welcome to Spelling Practice. Use o alfabeto fonético para soletrar a palavra. Por exemplo, Alfa para "a", "bravo" para "b", "charlie" para "c" etc. Você quer continuar?".

A captura de tela abaixo mostra essa interação:

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

Quando você responde à solicitação, sua ação gera uma mensagem indicando que não foi possível entender sua entrada: "Não entendi. Pode tentar de novo?" Como você ainda não configurou sua ação para entender e responder à entrada "Sim" ou "Não", ela vai associar a entrada a uma intent NO_MATCH.

Por padrão, a intent do sistema NO_MATCH fornece respostas genéricas, mas é possível personalizá-las 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 fazer a correspondência da entrada do usuário três vezes.

Adicionar "não" e intents fonéticas

Agora que os usuários podem responder à pergunta da sua ação, configure essa ação para entender as respostas ("Sim" ou "Não" ou "Ajuda com a fonética"). Nas seções a seguir, você vai criar intents que geram uma correspondência quando o usuário diz "Sim" ou "Não" ou "Ajuda com a Phonetics" e adicionar essas intents à 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 pode entender quando um usuário disser "não" ou algo semelhante, como "nem". Você precisa adicionar a intent do usuário no à cena Start porque o usuário está respondendo à solicitação Start ("Welcome to Orting Practice. Use o alfabeto fonético para soletrar 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 Start 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 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, a ação entende quando o usuário não quer jogar o jogo 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" à solicitação Start ("Welcome to Spelling Practice. Use o alfabeto fonético para soletrar 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 Chamar o webhook e atualize a caixa de texto event handler com a função criada 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, a ação entende quando o usuário quer jogar o jogo 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 então, clique no ícone de sugestão Yes.

Sua Ação busca uma lista de todas as palavras da prática ortográfica e as armazena na sessão. Sua ação termina 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 frases a seguir:

• 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 do usuário phonetics à cena Start, já que o usuário está respondendo à solicitação Start ("Welcome to Orting Practice. Use o alfabeto fonético para soletrar 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 no + (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 soletração

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

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

1. Clique em Desenvolver na navegação da parte de cima. Em seguida, clique em Iniciar cena na navegação à esquerda.
2. Na seção Processamento da intent do usuário, clique em when actions.intent.YES is matched e, à direita, na 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. Abra Cenas 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 entrar da cena Spelling.
7. Clique em Chamar seu webhook e insira getSpellingWord 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 {}. O comando real será preenchido pelo webhook.

Os ícones de sugestão oferecem sugestões clicáveis para o usuário. Essas sugestões são processadas pela sua ação como entradas do usuário.

Para adicionar ícones de sugestão à solicitação da cena Spelling, siga estas etapas:

10. Na cena Spelling, clique nas 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". Você pode adicionar a intent de usuário repeat à cena Spelling, já que o usuário está respondendo à solicitação Spelling ("Soletrar a palavra usando o 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 Processamento da intent do usuário.
3. Selecione repeat no menu suspenso da intent.

4. Marque Chamar seu webhook e digite repeatWordingWord 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 comando real será preenchido pelo webhook.

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

7. em Quando a correspondência com repetição for feita, Em "Tratamento de intent do usuário", clique em sugestões abaixo do editor de código. Essa 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 expressar a intent "definition". É possível adicionar a intent de usuário definition à cena Spelling, já que o usuário está respondendo à solicitação do Spelling ("Soletrar a palavra usando o 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 definição na lista suspensa de intents.

4. Marque a opção Chamar seu webhook e digite definitionOfLegingWord 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 à 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. Clique em Intents 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 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". Você pode adicionar a intent de usuário skip à cena Spelling, já que o usuário responde à solicitação Spelling ("Escreva a palavra usando o 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 da Página da intent do usuário.
3. Selecione skip no menu suspenso de intents.

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. Clique em Intents 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 Quit e pressione Enter.
4. Clique na intent Quit para abrir a página de definição da intent.
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". Você pode adicionar a intent de usuário quit à cena Spelling, já que o usuário está respondendo à solicitação do Spelling ("Soletrar a palavra usando o 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 Processamento da intent do usuário.
3. Selecione quit no menu suspenso de 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 soletrar a palavra. Também é possível definir alguns sinônimos para essas opções caso um usuário diga algo semelhante. Em outra seção, 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 Qual tipo de valor esse tipo vai oferecer suporte?, selecione a opção Palavras e sinônimos.
6. Digite as entradas e os valores correspondentes a seguir na seção Adicionar entradas:

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

8. Clique em Salvar.

Configurar o preenchimento de slot

Agora, configure o preenchimento de slot na cena de ortografia. Para configurar a lógica de preenchimento de slot, siga estas etapas:

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

8. Clique em Salvar.

Adicionar condição à tela Spelling

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

1. Clique na cena Spelling 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 Call your webhook e insira verifySpellingWord 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 comando 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. Testar a prática de ortografia no simulador

Para testar a 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 "Entrada".
3. Pressione Enter. Sua ação precisa responder com o comando Main invocation e o comando de cena Start adicionado, "Este é o procedimento de ortografia. Use o alfabeto fonético para soletrar 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 tocar um som de palavra para soletrar
6. Você pode soletrar a palavra usando alfabetos fonéticos. Por exemplo, para melhor dizer ou digitar "bravo eco tango tango echo romeo"
7. O simulador responde com a resposta correta ou incorreta.
8. Diga next para continuar para a próxima palavra ou quit para sair do loop do jogo.

13. Parabéns

Parabéns! Você criou seu jogo, Spelling Practice.

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

Conteúdo abordado

• 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 no 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 com práticas recomendadas e orientações sobre ações de conversa
• Introdução ao Cloud Firestore

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 que você criou neste codelab, siga estas etapas:

1. Para excluir seu projeto e recursos do Firebase, conclua as etapas listadas na seção Como encerrar (excluir) projetos.

Cuidado: verifique se você selecionou o projeto correto para exclusão na página Configurações do Console do Google Cloud.

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

Siga @ActionsOnGoogle e @Firebase no Twitter, fique por dentro dos nossos comunicados mais recentes e envie um tweet com a hashtag #GoogleIO para contar o que você criou.