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. O usuário interage com o Google Assistente em uma 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 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 "Prática de ortografia" que usa o Google Assistente para pedir que os usuários escrevam palavras.

O que você vai criar

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

  • Recebe respostas de ortografia do usuário e, dependendo do valor, modifica as solicitações de conversa
  • Responde com dicas relacionadas à ortografia da palavra, como a definição ou a repetição dela
  • 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 o Google Assistente. Basta dizer "Ok Google, falar com Spelling Practice". O caminho padrão dessa ação para um usuário retornante gera a seguinte interação:

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

2e9f94dc0ceafc96.png

O que você aprenderá

  • Como interagir com o Cloud Firestore
  • Como usar slots para coletar dados do usuário
  • Como processar uma entrada do usuário e enviar 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 deste codelab incluem:

  • Um navegador da Web, como o Google Chrome
  • Um ambiente de desenvolvimento integrado (IDE) para escrever o Cloud Functions.
  • Uma forma de pagamento. Este codelab usa o Cloud Functions para Firebase, que exige que seu projeto esteja no plano de preços Blaze do Firebase. 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) 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 como Spelling-Practice.

66ae8d1894f4477.png

  1. 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 ele não vai ser usado.

Para saber mais sobre os projetos do Firebase, consulte Entender 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, o que significa que você vai anexar uma conta do Google Cloud Billing ao projeto. Para isso, é necessário 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 custo financeiro do Cloud Functions. As etapas descritas neste codelab estão dentro dos limites de uso sem custo financeiro. No entanto, você vai 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 seu sistema operacional e 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 geralmente vem com o Node.js.
  2. Instale ou faça upgrade da CLI executando o seguinte comando npm:
$ npm -g install firebase-tools
  1. Verifique se a CLI foi instalada corretamente executando:
$ firebase --version

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

  1. Autorize a Firebase CLI executando:
$ firebase login
  1. 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.
$ firebase use --add

5. O diretório de funções

Agora você vai adicionar funcionalidades usando o SDK do Firebase para Cloud Functions e criar o back-end do jogo Prática de ortografia.

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

Quando você usa o SDK do Firebase para o 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 seu código será inserido. 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, é recomendável saber 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á-las 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, importe os módulos necessários e escreva quatro funções no lugar dos TODOs. Continue para a próxima etapa do codelab e importe 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 acionadores para o Cloud Functions.
  • 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 Node.js do SDK do Actions implementa manipuladores do SDK do Actions para o Google Assistente.
  1. Instale o SDK Actions executando o seguinte comando npm:
$ npm install @assistant/conversation
  1. 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 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 de palavras e gravá-las no Cloud Firestore

Você vai usar a API pública dictionaryapi.dev para receber as definições de 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 é 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 de createSpellingPracticeWord pelo seguinte:

index.js

// Firestore trigger that fetches word definitions through getWordDetailsFromDictionaryAPI for every new Firestore document

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 para o jogo

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

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

Adicionar essa função ao app.handle especial é uma maneira de tornar a função 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

Você pode escrever uma função do Cloud que retorne a próxima palavra da lista de ortografia.

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 escrever uma função do Cloud Functions que repete a palavra atual do jogo.

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

Confira a definição da palavra

Você pode escrever uma função do Cloud Functions que forneça a definição da palavra atual do 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 de ortografia 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 de 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 que você as implantar 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 usar mais tarde. Para acessar o endpoint, abra o Console do Firebase e clique no projeto spelling-practice. Abra o painel do Functions para ver o endpoint das funções.

332cb0437411a242.png

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

8. Ativar o Cloud Firestore

Você precisa ativar o Cloud Firestore.

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

5c0b4abf4410ffcf.png

O acesso aos dados no Cloud Firestore é controlado por regras de segurança. Primeiro, defina algumas regras básicas sobre os dados para começar. Clique em Firestore e, na guia "Regras" do console do Firebase, adicione as seguintes regras e clique em Publicar.

As regras a seguir restringem o acesso a 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 palavras de ortografia ao Cloud Firestore

Nesta etapa, você vai gravar dados de palavras de 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 createSpellingPracticeWord 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, insira wordlist e clique em Próxima.

1b4ccadb90f52f02.png

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

  1. Na caixa de texto ID do documento, insira agreement.
  2. Na caixa de texto Campo, insira word e, na caixa de texto Valor, insira agreement.
  3. Clique em Salvar.

379037e011e8511e.png

Quando você adiciona esse documento ao Cloud Firestore, ele aciona a função createSpellingPracticeWord para buscar os detalhes da definição da palavra. Adicione mais palavras (por exemplo: admiração, carro, verdadeiro, contar, melhor, trajeto, ...) criando um novo documento para cada palavra.

10. Configurar o Google Assistente

As seções a seguir mostram 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 e dar acesso ao simulador, é preciso ativar as permissões necessárias. 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, se ainda não tiver 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.

c988e1e639e6d6e1.png

Crie um projeto do Actions

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

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

b174d45710b8086b.png

  1. Digite ou selecione spelling-practice-codelab, que você criou usando o console do Firebase. O nome serve apenas para sua própria referência. Você pode definir um nome externo para o projeto mais tarde.

a2951de5d2001fac.png

  1. Clique em Importar projeto.
  2. Na tela Que tipo de ação você quer criar?, selecione o card Personalizado.
  3. Clique em Próxima.
  4. Selecione o card Projeto em branco.
  5. Clique em Começar a criar.
  6. Insira Prática de ortografia 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. Nesse caso, você pode usar a frase "Falar com meu app de teste" no simulador para invocar a ação.

Configurar fulfillment

Você precisa conectar ao Google Assistente os manipuladores de eventos das Funções do Cloud que escreveu 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 atendimento:

d523bf003e96e66f.png

  1. Insira o URL do endpoint da função na caixa de texto Endpoint HTTPS e clique em Salvar.

be53e2cd0d914d54.png

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

Configurar a invocação principal

Para definir o que acontece depois que um usuário invoca a ação, edite a invocação principal.

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

Para modificar a solicitação que sua ação retorna ao usuário quando ele chama a ação, siga estas etapas:

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

9ff088c04c995cde.png

  1. Marque Call your webhook e adicione o nome do manipulador de eventos getSpellingWordList na caixa de texto.
  2. 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 as solicitações.

  1. 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 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.

651fc8da1ac9aa0a.png

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.

Ver registros de eventos

Quando estiver na guia Teste do Console do Actions, o painel à direita mostrará os logs de eventos com o histórico de conversas. Cada log exibe os eventos que ocorrem durante aquela parte da conversa. Para ver o registro de eventos, clique no ícone cinza antes do evento.

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

a6fb192f94426824.png

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. O Praticar ortografia tem quatro cenas, e você precisa ativar cada uma delas antes que a ação seja executada. 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 para outra cena e a ative.

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

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 jogar Prática de ortografia. 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, siga estas etapas:

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

dd4f1807a57f794d.png

  1. Clique em Adicionar. Isso vai criar uma cena chamada Start e instruir a ação a fazer a transição para a cena Start após entregar a solicitação de boas-vindas ao usuário.
  2. Para mostrar a lista de cenas, clique em Cenas na navegação à esquerda.
  3. Em Cenas, clique em Iniciar para ver a cena Start.
  4. Clique em + na seção Ao inserir da cena Start.
  5. Selecione Enviar solicitações.
  6. 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 para o usuário. Essas sugestões são processadas pela sua ação como entradas 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 da cena Start, siga estas etapas:

  1. Na cena Start, clique em "Sugestões" abaixo do editor de código. Essa ação adiciona um único ícone de sugestão.
  2. No campo title, substitua Suggested Response por 'Yes'.
  3. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'No' e 'Help with Phonetics'. Seu código será semelhante a este snippet:
  4. Clique em Salvar.

5ff2ecdc56801b91.png

Testar sua ação no simulador

Nesse ponto, a ação deve 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 à solicitação Main invocation e à solicitação de cena Start adicionada, "Bem-vindo ao Praticar ortografia. Use o alfabeto fonético para soletrar a palavra. Por exemplo, alfa para a, bravo para b, charlie para c etc. Quer continuar?".

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

338c9570b02a618e.png

  1. Clique no ícone de sugestão Yes, No ou Help with Phonetics para responder à solicitação. Você também pode dizer "Sim" ou "Não" ou "Ajuda com 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", sua ação vai associar a entrada a uma intent NO_MATCH.

Por padrão, a intent do sistema NO_MATCH oferece respostas genéricas, mas é possível personalizar para indicar ao usuário que você não entendeu a entrada. O Google Assistente encerra a conversa do usuário com a ação se não conseguir associar a entrada de usuário três vezes.

Adicionar intents de "não" e fonéticas

Agora que os usuários podem responder à pergunta da sua ação, configure essa ação para entender as respostas ("Sim", "Não" ou "Ajuda com fonética"). Nas seções a seguir, você vai criar intents personalizadas que geram uma correspondência quando o usuário diz "Sim" ou "Não" ou "Ajuda com fonética" e adicionam esses 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 frases a seguir:
  • No
  • N
  • I don't want
  • nope

98b0c9a7b67ea9b9.png

  1. 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 de usuário no à cena Start porque o usuário está respondendo à solicitação Start ("Bem-vindo ao Treino de ortografia. Use o alfabeto fonético para soletrar a palavra. Por exemplo, alfa para a, bravo para b, charlie para c etc. Quer continuar?").

Para adicionar essa intent à 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 "Tratamento da intent do usuário".
  3. Na seção Objetivo, selecione Não no menu suspenso.

51f752e78c8b4942.png

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

O código no editor será semelhante a este:

candidates:
  - first_simple:
      variants:
        - speech: >-
             Goodbye.
  1. Na seção Transição, selecione Encerrar conversa na lista suspensa.
  2. Clique em Salvar.

Testar a intent no no simulador

Nesse ponto, a 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. Ou então, clique no ícone de sugestão "Nenhuma sugestão".

7727a456b522f31b.png

Adicionar a intent do sistema YES à cena Start

Agora, vamos adicionar a intent SYSTEM "YES" à cena Start, já que o usuário respondeu sim à solicitação Start ("Bem-vindo ao Spelling Practice. Use o alfabeto fonético para soletrar a palavra. Por exemplo, alfa para a, bravo para b, charlie para c etc. 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 Tratamento da intent do usuário.
  3. Em "Todas as intents do sistema", selecione SIM no menu suspenso de intents.

f6cbe789cde49e8f.png

  1. Clique em Chamar o webhook e atualize a caixa de texto event handler com a função criada anteriormente: getSpellingWordList
  2. Na seção Transição, clique na lista suspensa e selecione Encerrar conversa.
  3. 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 então, clique no ícone de sugestão Yes.

Sua ação busca uma lista de todas as palavras para praticar ortografia 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 dela.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

1455bdfca8dae46.png

  1. Clique em Salvar.

Adicionar a intent phonetics à cena Start

Agora, a ação pode entender quando um usuário expressar a intent "fonética". Você pode adicionar a intent de usuário phonetics à cena Start, já que o usuário responde à solicitação Start ("Bem-vindo ao Praticar ortografia. Use o alfabeto fonético para soletrar a palavra. Por exemplo, alfa para a, bravo para b, charlie para c etc. 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 "Tratamento da intent do usuário".
  3. Selecione phonetics no menu suspenso de intents.

67ee2e08000b2aee.png

  1. Na seção Transição, clique na lista suspensa e selecione Encerrar conversa.
  2. Clique em Salvar.

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

Nesta seção, você vai criar uma cena chamada Spelling, 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, siga estas etapas:

  1. Clique em Desenvolver na navegação superior. Em seguida, clique na cena Iniciar na navegação à esquerda.
  2. Na seção Processamento da intenção do usuário, clique em when actions.intent.YES is matched e, à direita, na seção transição, clique no menu suspenso e digite Spelling no campo de texto.
  3. Clique em Adicionar. Isso vai criar uma cena chamada Spelling e instruir a ação a fazer a transição para a cena Spelling após a correspondência com a intent YES.
  4. Expanda 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 inserir 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 webhook vai preencher o comando real.

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:

  1. Na cena Spelling, clique em "Sugestões" abaixo do editor de código. Essa ação adiciona três ícones de sugestão.
  2. No campo title, substitua Suggested Response por 'Repeat'.
  3. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Skip'.
  4. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'. Seu código será semelhante a este snippet:
  5. Clique em Salvar.
suggestions:
      - title: 'Repeat'
      - title: 'Skip'
      - title: 'Quit'

e1d437f714ea1539.png

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 frases a seguir:
  • one more time please
  • say the word again
  • repeat the word
  • tell me again
  • repeat

e61f0b9f80510bc9.png

  1. Clique em Salvar.

Adicionar a intent repeat à cena Spelling

Agora, a ação pode entender quando um usuário expressar a intent "repetir". 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 Tratamento da intent do usuário.
  3. Selecione repetir no menu suspenso de intents.

5cfd623b25bedbed.png

  1. Marque a caixa Chamar seu webhook e insira repeatSpellingWord na caixa de texto do manipulador de eventos para receber a definição da palavra.
  2. Marque Enviar solicitações.
  3. Substitua a frase no campo speech (Enter the response that users will see or hear...) por "'". O webhook vai preencher o comando real.

Adicionar ícones de sugestão a "Quando a repetição é correspondente"

  1. Em "Quando houver correspondência para a repetição" em "Gerenciamento 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.
  2. No campo title, substitua Suggested Response por 'Skip'.
  3. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código precisa ser semelhante a este snippet:
suggestions:
      - title: 'Skip'
      - title: 'Quit'

ab40e4b0c432b97c.png

  1. 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 dela.definition
  5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as frases a seguir:
  • I would like to know the definition
  • tell me the definition
  • what does it mean
  • meaning
  • definition
  • what is the definition?

c1b88a9c0b1ac082.png

  1. Clique em Salvar.

Adicionar a intent definition à cena Spelling

Agora, a ação pode entender quando um usuário expressar a intent "definição". Você pode adicionar a intent de usuário definition à 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 Tratamento da intent do usuário.
  3. Selecione definition no menu suspenso de intents.

646bdcac3ad3eb0c.png

  1. Marque a caixa Chamar seu webhook e insira definitionOfSpellingWord na caixa de texto do manipulador de eventos para receber a definição da palavra.
  2. Marque Enviar solicitações.
  3. 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

  1. Na cena Start, clique em sugestões abaixo do editor de código. Essa ação adiciona três ícones de sugestão.
  2. No campo title, substitua Suggested Response por 'Skip'.
  3. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código precisa ser semelhante a este snippet:
suggestions:
      - title: 'Skip'
      - title: 'Quit'

25227545839d933f.png

  1. 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.
  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 dela.skip
  5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as frases a seguir:
  • next word
  • go next
  • next
  • skip
  • skip word

d1c4908a3d7882f8.png

  1. Clique em Salvar.

Adicionar a intent Skip à cena Spelling

Agora, a ação pode entender quando um usuário expressar a intent "pular". Você pode adicionar a intent de usuário skip à 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 Tratamento da intent do usuário.
  3. Selecione pular no menu suspenso de intents.

5465f97542217964.png

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

c8072485ca82bd3f.png

  1. 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.
  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 definição.
  5. Na seção Adicionar frases de treinamento, clique na caixa de texto Inserir frase e digite as frases a seguir:
  • I quit
  • Goodbye
  • Cancel
  • Exit
  • Quit

9916f77b8766541e.png

  1. Clique em Salvar.

Adicionar a intent Quit à cena Spelling

Agora, a ação pode entender quando um usuário expressar a intent "sair". Você pode adicionar a intent de usuário quit à 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 Tratamento da intent do usuário.
  3. Selecione sair no menu suspenso de intents.

5f62fb18a3653d66.png

  1. Na seção Transição à direita, clique no menu suspenso e selecione End conversation . 1ffbe35a7bbbb4b0.png
  2. Clique em Salvar.

Criar tipo phonetic_alphabet

Nesta seção, você vai criar um tipo chamado phonetic_alphabet, que especifica as opções de alfabeto fonético que os usuários podem escolher para soletrar a palavra. Você também pode 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 Que tipo de valores esse tipo vai aceitar?, selecione a opção Palavras e sinônimos.
  6. Digite as entradas e os valores correspondentes a seguir na seção Adicionar entradas:

a

alfa, apple, amsterdam

b

bravo, butter, baltimore

c

charlie, cat, casablanca

d

delta, cachorro, dinamarca

e

echo, edward, edison

f

foxtrot, fox, florida

g

golf, george, gallipoli

h

hotel, harry, havana

i

india, ink, italia

j

juliette, johnny, jerusalem

k

quilo, rei, quilograma

l

lima, love, london

m

mike, money, madagascar

n

november, new york, nancy

o

oscar, orange, oslo

p

papa, paris, peter

q

quebec, queen

r

romeo, roma, robert

s

sierra, sugar, santiago

t

tango, tommy, tripoli

u

uniforme, guarda-chuva, tio

v

victor, vinegar, Valencia

w

whiskey, william, washington

x

raio-x

y

yankee, yellow, yorker

z

zulu, zebra, zurich

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

5b5a5cd9fa557e1b.png

  1. Clique em Salvar.

Configurar o preenchimento de slot

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

  1. Clique na cena Ortografia na navegação.
  2. Clique no + (sinal de adição) na cena Spelling para Preenchimento de slot.
  3. No campo Inserir o nome do slot, adicione userresponse.
  4. No menu suspenso Selecionar tipo, escolha 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 insira "userresponse" na caixa de texto do parâmetro de sessão.

ba57a419877a07f3.png

  1. 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 no + (sinal de adição) na cena Spelling ao lado de "Condição".
  3. Insira scene.slots.status == "FINAL" como condição
  4. Marque a caixa Chamar seu webhook e digite verifySpellingWord na caixa de texto do manipulador de eventos para verificar a resposta do usuário.
  5. Marque Enviar solicitações.
  6. Substitua a frase no campo speech (Enter the response that users will see or hear...) por {}. O webhook vai preencher o comando real.

Adicionar ícones de sugestão à resposta do webhook

  1. Na cena Start, clique em sugestões abaixo do editor de código. Essa ação adiciona três ícones de sugestão.
  2. No campo title, substitua Suggested Response por 'Next'.
  3. Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado 'Quit'.Seu código precisa ser semelhante a este snippet:
suggestions:
      - title: 'Next'
      - title: 'Quit'

ac3d7a9366ebc1b1.png

  1. 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 à solicitação Main invocation e à solicitação de cena Start adicionada, "Bem-vindo ao Praticar ortografia. Use o alfabeto fonético para soletrar a palavra. Por exemplo, alfa para a, bravo para b, charlie para c etc. Quer continuar?".
  4. Diga Sim para continuar
  5. O simulador vai tocar o som de uma palavra para você soletrar
  6. Você pode soletrar a palavra usando alfabetos fonéticos. Por exemplo, para better, diga ou digite "bravo echo tango tango echo romeo".
  7. O simulador vai responder com a resposta certa ou errada.
  8. Diga próxima para continuar para a próxima palavra ou sair para sair do jogo.

13. Parabéns

Parabéns! Você criou o jogo Prática de ortografia.

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

O que você abordou

  • Como interagir com o Cloud Firestore
  • Como usar slots para coletar dados do usuário
  • Como processar uma entrada do usuário e enviar 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 do Google Assistente:

Limpar o projeto [recomendado]

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

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

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

  1. Opcional: para remover seu projeto do console do Actions imediatamente, conclua as etapas da seção Como excluir um projeto. Caso contrário, seu projeto será removido automaticamente após cerca de 30 dias.

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