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:
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
- Faça login no Firebase.
- No console do Firebase, clique em Adicionar projeto (ou Criar um projeto) e nomeie o projeto como
Spelling-Practice
.
- 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.
- Verifique se você instalou o npm, que geralmente vem com o Node.js.
- Instale ou faça upgrade da CLI executando o seguinte comando npm:
$ npm -g install firebase-tools
- 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.
- Autorize a Firebase CLI executando:
$ firebase login
- 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.
- Instale o SDK Actions executando o seguinte comando npm:
$ npm install @assistant/conversation
- 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.
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.
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
- No console do Firebase, navegue até a seção do Cloud Firestore.
- Clique em + Iniciar coleção.
- Na caixa de texto ID da coleção, insira
wordlist
e clique em Próxima.
Em seguida, vamos criar um documento para uma palavra: agreement.
- Na caixa de texto ID do documento, insira
agreement
. - Na caixa de texto Campo, insira
word
e, na caixa de texto Valor, insiraagreement
. - Clique em Salvar.
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:
- Acesse a página Controles de atividade.
- Faça login com sua Conta do Google, se ainda não tiver feito isso.
- 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
Seu projeto do Actions é um contêiner da sua ação. Para criar um projeto do Actions neste codelab, siga estas etapas:
- Abra o Console do Actions.
- Clique em Novo projeto.
- Aceitar os Termos de Serviço
- 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.
- Clique em Importar projeto.
- Na tela Que tipo de ação você quer criar?, selecione o card Personalizado.
- Clique em Próxima.
- Selecione o card Projeto em branco.
- Clique em Começar a criar.
- 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:
- Clique em Webhook na navegação lateral.
- Selecione Endpoint HTTPS como opção de atendimento:
- Insira 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
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:
- Clique em Invocação principal na navegação.
- Marque
Call your webhook
e adicione o nome do manipulador de eventosgetSpellingWordList
na caixa de texto. - 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.
- 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:
- Na barra de navegação superior, clique em Testar para acessar o simulador.
- 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.
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:
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:
- Clique em Desenvolver na navegação superior. Em seguida, clique em Invocação principal na navegação à esquerda.
- Na seção Transição à direita, clique no menu suspenso e digite
Start
no campo de texto.
- Clique em Adicionar. Isso vai criar uma cena chamada
Start
e instruir a ação a fazer a transição para a cenaStart
após entregar a solicitação de boas-vindas ao usuário. - Para mostrar a lista de cenas, clique em Cenas na navegação à esquerda.
- Em Cenas, clique em Iniciar para ver a cena
Start
. - Clique em + na seção Ao inserir da cena
Start
. - Selecione Enviar solicitações.
- 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:
- Na cena
Start
, clique em "Sugestões" abaixo do editor de código. Essa ação adiciona um único ícone de sugestão. - No campo
title
, substituaSuggested Response
por'Yes'
. - 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: - Clique em Salvar.
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:
- Na barra de navegação, clique em Testar para acessar o simulador.
- Para testar sua ação no simulador, digite
Talk to Spelling Practice
no campo "Entrada". - Pressione Enter. Sua ação precisa responder à solicitação
Main invocation
e à solicitação de cenaStart
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:
- Clique no ícone de sugestão
Yes
,No
ouHelp with Phonetics
para responder à solicitação. Você também pode dizer "Sim" ou "Não" ou "Ajuda com fonética" ou inserirYes
ouNo
ouHelp 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:
- Clique em Desenvolver na navegação.
- Clique em Intents personalizadas na navegação para abrir a lista de intents.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
no
e pressione Enter. - Clique em Não para abrir a página da intent
no
. - 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
- 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:
- Clique na cena Iniciar na navegação.
- Clique no + (sinal de adição) na cena
Start
ao lado de "Tratamento da intent do usuário". - Na seção Objetivo, selecione Não no menu suspenso.
- 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.
- Na seção Transição, selecione Encerrar conversa na lista suspensa.
- 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:
- Na barra de navegação, clique em Testar.
- Digite
Talk to Spelling Practice
no campo de entrada e pressioneEnter
. - Digite
No
no campo Entrada e pressione Enter. Ou então, clique no ícone de sugestão "Nenhuma sugestão".
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:
- Clique na cena Iniciar na navegação.
- Clique no + (sinal de adição) na cena
Start
ao lado de Tratamento da intent do usuário. - Em "Todas as intents do sistema", selecione SIM no menu suspenso de intents.
- Clique em Chamar o webhook e atualize a caixa de texto
event handler
com a função criada anteriormente:getSpellingWordList
- Na seção Transição, clique na lista suspensa e selecione Encerrar conversa.
- 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:
- Na barra de navegação, clique em Testar.
- Para testar sua ação no simulador, digite
Talk to Spelling Practice
no campo Entrada e pressione Enter. - Digite
Yes
no campo Entrada e pressione Enter. Ou então, clique no ícone de sugestãoYes
.
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:
- Clique em Desenvolver na navegação.
- Clique em Intents personalizadas na navegação para abrir a lista de intents.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
phonetics
e pressioneEnter
. - Clique na intent
phonetics
para abrir a página dela.phonetics
- 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
- 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:
- Clique na cena Iniciar na navegação.
- Clique no sinal de adição (+) na cena
Start
ao lado de "Tratamento da intent do usuário". - Selecione phonetics no menu suspenso de intents.
- Na seção Transição, clique na lista suspensa e selecione Encerrar conversa.
- 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:
- Clique em Desenvolver na navegação superior. Em seguida, clique na cena Iniciar na navegação à esquerda.
- 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 digiteSpelling
no campo de texto. - Clique em Adicionar. Isso vai criar uma cena chamada
Spelling
e instruir a ação a fazer a transição para a cenaSpelling
após a correspondência com a intent YES. - Expanda Cenas na navegação à esquerda para mostrar a lista de cenas.
- Em Cenas, clique em "Ortografia" para ver a cena
Spelling
. - Clique em + na seção Ao inserir da cena
Spelling
. - Clique em Chamar seu webhook e insira getSpellingWord na caixa de texto do manipulador de eventos.
- Selecione Enviar solicitações.
- 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:
- Na cena
Spelling
, clique em "Sugestões" abaixo do editor de código. Essa ação adiciona três ícones de sugestão. - No campo
title
, substituaSuggested Response
por'Repeat'
. - Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado
'Skip'
. - Usando a mesma formatação, adicione manualmente um ícone de sugestão chamado
'Quit'
. Seu código será semelhante a este snippet: - Clique em Salvar.
suggestions: - title: 'Repeat' - title: 'Skip' - title: 'Quit'
Criar intent Repeat
Para criar a intent repeat
, siga estas etapas:
- Clique em Desenvolver na navegação.
- Clique em Intents personalizadas na navegação para abrir a lista de intents.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
repeat
e pressioneEnter
. - Clique na intent
repeat
para abrir a página da intentdefinition
. - 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
- 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:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
ao lado de Tratamento da intent do usuário. - Selecione repetir no menu suspenso de intents.
- Marque a caixa Chamar seu webhook e insira repeatSpellingWord na caixa de texto do manipulador de eventos para receber a definição da palavra.
- Marque Enviar solicitações.
- 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"
- 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.
- No campo
title
, substituaSuggested Response
por'Skip'
. - 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'
- Clique em Salvar.
Criar intent definition
Para criar a intent definition
, siga estas etapas:
- Clique em Desenvolver na navegação.
- Clique em Intents personalizadas na navegação para abrir a lista de intents.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
definition
e pressioneEnter
. - Clique na intent
definition
para abrir a página dela.definition
- 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?
- 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:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
ao lado de Tratamento da intent do usuário. - Selecione definition no menu suspenso de intents.
- Marque a caixa Chamar seu webhook e insira definitionOfSpellingWord na caixa de texto do manipulador de eventos para receber a definição da palavra.
- Marque Enviar solicitações.
- 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
- Na cena
Start
, clique em sugestões abaixo do editor de código. Essa ação adiciona três ícones de sugestão. - No campo
title
, substituaSuggested Response
por'Skip'
. - 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'
- Clique em Salvar.
Criar intent skip
Para criar a intent skip
, siga estas etapas:
- Clique em Desenvolver na navegação.
- Clique em Intents na navegação para abrir a lista.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
skip
e pressioneEnter
. - Clique na intent
skip
para abrir a página dela.skip
- 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
- 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:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
ao lado de Tratamento da intent do usuário. - Selecione pular no menu suspenso de intents.
- Na seção Transição à direita, clique no menu suspenso e selecione
Spelling
.
- Clique em Salvar.
Criar intent quit
Para criar a intent Quit
, siga estas etapas:
- Clique em Desenvolver na navegação.
- Clique em Intents na navegação para abrir a lista.
- Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent
Quit
e pressioneEnter
. - Clique na intent
Quit
para abrir a página da intent definição. - 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
- 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:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
ao lado de Tratamento da intent do usuário. - Selecione sair no menu suspenso de intents.
- Na seção Transição à direita, clique no menu suspenso e selecione
End conversation
. - 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:
- Clique em Desenvolver na navegação.
- Em Tipos, clique no + (sinal de adição).
- Digite
phonetic_alphabet
e pressioneEnter
. - Clique em
phonetic_alphabet
para abrir as opções. - Na seção Que tipo de valores esse tipo vai aceitar?, selecione a opção Palavras e sinônimos.
- 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:
- 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:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
para Preenchimento de slot. - No campo Inserir o nome do slot, adicione
userresponse
. - No menu suspenso Selecionar tipo, escolha phonetic_alphabet como o tipo de slot.
- Marque Este slot aceita uma lista de valores.
- Marque Este slot é obrigatório.
- Selecione a opção Personalizar o writeback do valor do slot e insira "userresponse" na caixa de texto do parâmetro de sessão.
- Clique em Salvar.
Adicionar condição à tela Spelling
Para adicionar a condição à cena Spelling
, siga estas etapas:
- Clique na cena Ortografia na navegação.
- Clique no + (sinal de adição) na cena
Spelling
ao lado de "Condição". - Insira
scene.slots.status == "FINAL"
como condição - Marque a caixa Chamar seu webhook e digite verifySpellingWord na caixa de texto do manipulador de eventos para verificar a resposta do usuário.
- Marque Enviar solicitações.
- 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
- Na cena
Start
, clique em sugestões abaixo do editor de código. Essa ação adiciona três ícones de sugestão. - No campo
title
, substituaSuggested Response
por'Next'
. - 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'
- Clique em Salvar.
12. Testar a prática de ortografia no simulador
Para testar a ação no simulador, siga estas etapas:
- Na barra de navegação, clique em Testar para acessar o simulador.
- Para testar sua ação no simulador, digite
Talk to Spelling Practice
no campo "Entrada". - Pressione Enter. Sua ação precisa responder à solicitação
Main invocation
e à solicitação de cenaStart
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?". - Diga Sim para continuar
- O simulador vai tocar o som de uma palavra para você soletrar
- Você pode soletrar a palavra usando alfabetos fonéticos. Por exemplo, para better, diga ou digite "bravo echo tango tango echo romeo".
- O simulador vai responder com a resposta certa ou errada.
- 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:
- 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 criados neste codelab, siga estas etapas:
- 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.
- 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.