Criar ações para o Google Assistente usando o Actions Builder (nível 1)

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 básico de desenvolvimento com o Google Assistente. Não é preciso ter experiência com a plataforma para concluir. Neste codelab, você vai criar uma ação simples para o Google Assistente que informe ao usuário uma previsão para o futuro ao iniciar uma aventura na terra mítica de Gryffinberg. No codelab de nível 2 do Actions Builder, você vai adicionar mais detalhes à ação para personalizar a previsão do usuário de acordo com as entradas disponibilizadas.

O que você vai criar

Neste codelab, você vai criar uma ação simples com as seguintes funções:

  • Responder aos usuários com uma mensagem de saudação.
  • Fazer uma pergunta ao usuário. Quando o usuário responder, o Action responderá conforme o que ele selecionar.
  • Disponibilizar ícones de sugestão nos quais o usuário pode clicar para fornecer informações.
  • Modificar a mensagem de saudação para usuários retornantes.

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

1c1e79902bed7230.png

18ef55647b4cb52c.png

O que você aprenderá

  • Como criar um projeto no Console do Actions
  • Como enviar uma solicitação ao usuário depois que ele invocar uma ação
  • Como processar uma entrada do usuário e enviar uma resposta
  • Como testar sua ação no simulador do Actions
  • Como implementar o fulfillment usando o editor do Cloud Functions

Pré-requisitos

Você precisa ter as seguintes ferramentas no seu ambiente:

2. Configurar

As seções a seguir mostram como configurar o ambiente para desenvolvedores e criar seu projeto do Actions.

Verificar as 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 de seleção Incluir o histórico do Chrome e a atividade em sites, apps e dispositivos que usam serviços do Google.

Criar um projeto do Actions

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

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

8cd05a84c1c0a32f.png

  1. Clique em Create project.
  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.

Associar uma conta de faturamento

Se mais tarde você quiser implantar o fulfillment com o Cloud Functions neste codelab, é preciso associar uma conta de faturamento ao seu projeto no Google Cloud.

Se você ainda não associou uma conta de faturamento ao seu projeto, siga estas etapas:

  1. Acesse a página de faturamento do Google Cloud Platform.
  2. Clique em Adicionar conta de faturamento ou Criar conta.
  3. Insira as informações de pagamento.
  4. Clique em Iniciar meu teste sem custo financeiro ou Enviar e ativar o faturamento.
  5. Acesse a página de faturamento do Google Cloud Platform.
  6. Clique na guia Meus projetos.
  7. Clique nos três pontos em Actions ao lado do projeto do Actions para o codelab.
  8. Clique em Alterar faturamento.
  9. No menu suspenso, selecione a conta de faturamento que você configurou. Clique em Definir conta.

Para evitar cobranças, siga as etapas na seção Como limpar seu projeto, no final deste codelab.

3. Inicie uma conversa

Os usuários iniciam a conversa com sua ação usando uma invocação. Por exemplo, se você tiver uma ação chamadaMovieTime, o usuário pode chamar sua ação dizendo uma frase como"Ok Google, falar com o MovieTime", onde MovieTime é onome 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 testá-la. Nesse caso, você pode usar a frase "Falar com meu app de teste" no simulador para invocar a ação.

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

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

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

Configurar 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 barra de navegação.

966d037e1d7914df.png

  1. No editor de código, substitua o texto no campo speech (Start building your action...) pela seguinte mensagem de boas-vindas: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.
  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.

Agora, ao invocar uma ação, ela deve responder com a solicitação personalizada que você adicionou ("A wondrous greeting, adventurer!...").

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 my test app no campo Entrada e pressione Enter.

656f5736af6a5a07.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. Na próxima seção, você vai modificar sua ação para que a conversa continue.

Ver logs 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.

No momento, a ação tem um log de eventos, que mostra a entrada do usuário ("Talk to my test app") e a resposta da ação. Veja o log de eventos do Action na captura de tela a seguir:

443129bdcbecc593.png

Se clicar na seta para baixo no log de eventos, você verá os eventos daquele trecho da conversa, em ordem cronológica:

  • userInput: corresponde à entrada do usuário ("Talk to my test app").
  • interactionMatch: corresponde à resposta de invocação principal da ação, que é acionada pela entrada do usuário. Ao clicar na seta para expandir a linha, você verá a solicitação que adicionou para a invocação principal (A wondrous greeting, adventurer!...)
  • endConversation: corresponde à transição selecionada na intent Main invocation, que encerra a conversa no momento. Saiba mais sobre transições na próxima seção deste codelab.

Os logs de eventos mostram como a ação está funcionando e são ferramentas úteis para depurá-la em caso de problemas. Para ver as informações de um evento, clique na seta ao lado do nome dele, como mostra a captura de tela a seguir:

fcc389b59af5bef1.png

4. Criar a conversa do Action

Agora que você já definiu o que acontece depois que um usuário invoca sua ação, já pode criar o restante da conversa. Antes de continuar com este codelab, conheça os termos a seguir para entender como a conversa da sua ação funciona:

Sua ação pode ter uma ou várias cenas, e você precisa ativar cada uma delas antes que a ação seja executada. A ação que você criou neste codelab tem apenas uma cena, chamada Start. 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 ative-a.

Por exemplo, imagine uma ação que ofereça ao usuário fatos curiosos. Quando o usuário invoca essa ação, a intent Main invocation é correspondida e aciona a transição para uma cena chamada Facts. Essa transição ativa a cena Facts, que envia a seguinte solicitação ao usuário: Would you like to hear a fact about cats or dogs? Na cena Facts, há uma intent de usuário chamada Cat, que contém frases de treinamento que o usuário pode dizer para ouvir um fato sobre gatos, como "Eu quero ouvir um fato sobre gatos." ou "cat". Quando o usuário pede para ouvir um fato sobre gatos, a intent Cat é correspondida e aciona uma transição para uma cena chamada Cat fact. A cena Cat fact é ativada e envia uma solicitação ao usuário que inclui uma curiosidade sobre os gatos.

a78f549c90c3bff6.png

Figura 1. O fluxo do trecho de uma conversa comum em uma ação criada com o Actions Builder

Juntas, as cenas, intents e transições compõem a lógica da conversa e definem os vários caminhos que o usuário pode seguir na sua ação. Na seção a seguir, você vai criar uma cena e definir como ela será ativada depois que um usuário invocar sua ação.

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

Nesta seção, você vai criar uma cena chamada Start, que envia uma solicitação ao usuário perguntando se ele quer ouvir uma previsão do futuro. Você também vai adicionar uma transição da invocação principal para a nova cena Start.

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

  1. Clique em Desenvolver na barra de navegação.
  2. Clique em Invocação principal na barra de navegação lateral.
  3. Na seção Transição, clique no menu suspenso e digite Start no campo de texto.

29e12dff950a3bce.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. Clique em Cenas na barra de navegação lateral para exibir a lista de cenas.
  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: Before you continue on your quest, would you like your fortune told?

3fc95466efd476f.png

  1. Clique em Salvar.

O Google Assistente fornece essa solicitação (Before you continue on your quest...) ao usuário quando ele entra na cena Start.

Adicionar ícones de sugestão

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 ícones de sugestão para oferecer suporte aos usuários em dispositivos com telas.

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

  1. Na cena Start, clique em sugestões. Esta 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'. Seu código será semelhante a este snippet:
    suggestions:
      - title: 'Yes'
      - title: 'No'
  1. Clique em Salvar.

2d13c2ada791ec26.png

Testar 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 ouvir uma previsão do futuro. 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 my test app no campo Entrada e pressione Enter. Sua ação precisa responder à solicitação Main invocation e à solicitação de cena Start adicionada, "Before you continue on your quest, would you like your fortune told?".

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

3c2013ebb2da886a.png

  1. Clique no ícone de sugestão Yes ou No para responder à solicitação. Você também pode dizer "Sim" ou "Não" ou inserir Yes ou No 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 yes e no

Agora que os usuários podem responder à pergunta da sua ação, configure essa ação para entender as respostas ("Sim" ou "Não"). Nas seções a seguir, você vai criar intents personalizadas que geram uma correspondência quando o usuário diz "Yes" ou "No" e adicionam esses intents à cena Start.

Criar intent yes

Para criar a intent yes, siga estas etapas:

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

98440276cb9e7de8.png

  1. Clique em Salvar.

Adicionar a intent yes à cena Start

Agora, a ação pode entender quando um usuário expressar a intent "Sim". Você pode adicionar a intent de usuário yes à cena Start porque o usuário está respondendo à solicitação Start ("Antes de continuar a missão, você quer ouvir sua previsão para o futuro?

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

  1. Clique na cena Iniciar na barra de navegação.
  2. Clique no sinal + (sinal de adição) na cena Start ao lado de Tratamento da intent do usuário.
  3. Selecione Sim no menu suspenso da intent.

681928e3d71abdbf.png

  1. Clique em Enviar solicitações e atualize o campo speech com o seguinte texto: Your future depends on the aid you choose to use for your quest. Choose wisely! Farewell, stranger.

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

candidates:
  - first_simple:
      variants:
        - speech: >-
            Your future depends on the aid you choose to use for your quest. Choose
            wisely! Farewell, stranger.
  1. Na seção Transição, clique no menu suspenso e selecione Encerrar conversa.
  2. Clique em Salvar.

Testar a intent yes no simulador

Nesse ponto, sua ação entende quando o usuário quer ouvir a previsão do futuro 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 my test app no campo Entrada e pressione Enter.
  3. Digite Yes no campo Entrada e pressione Enter. Também é possível clicar no ícone de sugestão Sim.

f131998710d8ffd8.png

Sua ação responde ao usuário e diz que o futuro vai depender do item escolhido. Sua ação termina a sessão porque você selecionou a transição End conversation para a intent yes.

Criar intent no

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

  1. Clique em Desenvolver na barra de navegação.
  2. Clique em Intents personalizadas na barra de navegação para abrir a lista de intents.
  3. Clique em + (sinal de adição) no final da lista de intents.
  4. Nomeie a nova intent no e pressione Enter.
  5. Clique em Não para abrir a página de intent no.
  6. 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

2e7b8fd57eac94c5.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 personalizada no à cena Start por causa da resposta do usuário à solicitação Start ("Antes de continuar a missão, você quer ouvir sua previsão para o futuro?").

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

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

4aa558abdecb3121.png

  1. Clique em Enviar solicitações.
  2. Atualize o campo speech com o seguinte texto: I understand, stranger. Best of luck on your quest! Farewell.

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

 candidates:
  - first_simple:
      variants:
        - speech: >-
             I understand, stranger. Best of luck on your quest! Farewell.
  1. Na seção Transição, selecione Encerrar conversa no menu suspenso.
  2. Clique em Salvar.

Testar a intent no no simulador

Agora, a ação entende quando o usuário não quer ouvir a previsão do futuro 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 my test app no campo Entrada e pressione Enter.
  3. Digite No no campo Entrada e pressione Enter. Também é possível clicar no ícone de sugestão Não.

c0c8b04066577eb2.png

Em vez de dar a previsão do futuro ao usuário, sua ação vai desejar boa sorte na missão. Sua ação termina a sessão porque você selecionou a transição End conversation para a intent no.

5. Implementar o fulfillment

No momento, as respostas da sua ação são estáticas. Quando uma cena com uma solicitação está ativada, a ação envia sempre a mesma solicitação. Nesta seção, você vai implementar um fulfillment que contém a lógica para criar uma resposta dinâmica de conversa.

Seu fulfillment identifica se o usuário é novo e, se for retornante, modifica a mensagem de saudação da ação. A mensagem de saudação para usuários retornantes é mais curta e leva essa característica em conta: "Saudações calorosas, aventureiro! Bem-vindo de volta à terra mitológica de Gryffinberg!"

Neste codelab, você vai usar o editor do Cloud Functions para editar e implantar seu código de fulfillment no Console do Actions.

Sua ação pode acionar webhooks que notificam o fulfillment de um evento que ocorre durante uma invocação ou partes específicas da execução de uma cena. Quando um webhook é acionado, a ação envia uma solicitação com um payload JSON para o fulfillment com o nome do gerenciador a ser usado para processar o evento. Esse gerenciador realiza uma lógica e retorna uma resposta JSON correspondente.

Criar fulfillment

Agora, é possível modificar o fulfillment no editor in-line para gerar solicitações diferentes caso o usuário que invocar sua ação seja novo ou retornante.

Para adicionar essa lógica ao fulfillment, siga estas etapas:

  1. Clique em Desenvolver na barra de navegação.
  2. Clique na guia Webhook na barra de navegação.
  3. Marque a caixa de seleção Cloud Functions in-line.
  4. Clique em Confirmar. O código padrão é adicionado automaticamente aos arquivos index.js e package.json.

d4702f1de6404285.png

  1. Substitua o conteúdo de index.js pelo seguinte código:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
  1. Clique em Salvar fulfillment.
  2. Clique em Implantar fulfillment.

Aguarde alguns minutos para que o Cloud Functions provisione e implante o fulfillment. Você verá a mensagem Implantação do Cloud Function em andamento... acima do editor de código. Quando o código for implantado, a mensagem será atualizada para A implantação da Função do Cloud foi atualizada.

Entender o código

O fulfillment, que usa a biblioteca de fulfillment do Actions on Google para Node.js, responde às solicitações HTTP do Google Assistente.

No snippet de código anterior, você precisa definir o gerenciador greeting, que verifica se o usuário já visitou a ação com a propriedade lastSeenTime. Se lastSeenTime não estiver definido, o usuário é novo, e o gerenciador greeting dará a saudação correspondente.

Atualizar a invocação principal para acionar um webhook

Agora que você definiu a função greeting, já pode configurar o manipulador de eventos greeting na intent de invocação principal para que a ação chame essa função quando for invocada pelo usuário.

Para configurar sua ação para chamar o novo gerenciador greeting, siga estas etapas:

  1. Clique em Invocação principal na barra de navegação.
  2. Desmarque Enviar solicitação.
  3. Marque a caixa de seleção Chamar o webhook.
  4. Adicione greeting à caixa de texto.

a803afe4f7375a97.png

  1. Clique em Salvar.

Testar a invocação principal atualizada 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. Digite Talk to my test app no campo Entrada e pressione Enter.

Como já testou sua ação neste codelab, você não é um novo usuário. Portanto, receberá a seguinte saudação reduzida: "Saudações calorosas, aventureiro! Bem-vindo de volta à terra mitológica de Gryffinberg!"

Como limpar o projeto [recomendado]

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

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

6. Parabéns!

Agora você já conhece os conceitos básicos da criação de ações para o Google Assistente.

Conteúdo abordado

  • Como configurar um projeto do Actions com o Console do Actions
  • Como adicionar uma solicitação à invocação principal para que os usuários possam iniciar uma conversa com a ação
  • Como criar uma interface de conversa com cenas, intents, transições, ícones de sugestão e fulfillment
  • Como testar sua ação no simulador do Actions

Saiba mais

Confira os seguintes recursos para saber mais sobre como criar ações para o Google Assistente:

Pesquisa de feedback

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