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

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ê 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:

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, é preciso ativar as permissões necessárias para que o simulador acesse seu Action. 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.

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

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ê já tem uma conta desse tipo, ignore as etapas a seguir.

Para associar uma conta de faturamento ao projeto, siga estas etapas:

  1. Acesse a página de faturamento do Google Cloud Platform.
  2. Clique em Adicionar conta de faturamento.
  3. Preencha suas informações de pagamento e clique em Iniciar meu teste gratuito ou Enviar e ativar o faturamento.
  4. Clique na guia Meus projetos na parte superior da página.
  5. Clique nos três pontos em Actions ao lado do projeto do Actions para o codelab.
  6. Clique em Mudar faturamento.
  7. No menu suspenso, selecione a conta de faturamento que você configurou. Clique em Definir conta.

Para evitar cobranças, siga as etapas da seção "Como limpar o projeto" na página "Próximas etapas" no final deste codelab.

Os usuários iniciam a conversa com sua ação por meio de 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", em que 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 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 o Action chamada simulador. A interface simula dispositivos de hardware e as configurações deles. Dessa forma, você pode conversar com o Action como se ele estivesse sendo executado 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 ("Saudações calorosas, aventureiro!")

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 no canto superior esquerdo e pressione Enter.

656f5736af6a5a07.png

Quando você aciona a invocação principal do Action, 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 ("Falar com meu app de teste") e a resposta do Action. 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 ("Falar com meu app de teste").
  • interactionMatch: corresponde à resposta de invocação principal do Action, 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

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. Ao invocar essa ação, o usuário gera uma correspondência com a intent Main invocation 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? Dentro da cena Facts, há uma intent personalizada chamada Cat com frases de treinamento que o usuário pode dizer para ouvir um fato sobre gatos. Por exemplo, "Quero ouvir um fato sobre gatos" ou "gato". Quando pede para ouvir um fato sobre gatos, o usuário gera uma correspondência com a intent Cat 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 essa curiosidade.

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

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. Para exibir 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: 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 os ícones de sugestão que aparecem abaixo da solicitação que acabou de configurar (Before you continue on your quest, would you like your fortune told?) 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 abaixo do editor de código. 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.
  3. Pressione Enter. Sua ação precisa responder à solicitação Main invocation e à solicitação de cena Start adicionada, "Antes de continuar a missão, você quer ouvir sua previsão para o futuro?".

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 responde com 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 personalizá-las 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 "Sim" ou "Não" e adicionam esses intents à cena Start.

Criar intent yes

Para criar a intent yes, siga estas etapas:

  1. Clique em Desenvolver na navegação.
  2. Para abrir a lista, clique em Intents na navegação.
  3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent yes e pressione Enter.
  4. Clique na intent yes para abrir a página da intent yes.
  5. 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, pois o usuário responde à 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 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 na lista suspensa de intents.

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 na lista suspensa 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. Ou então, clique no ícone de sugestão Yes.

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 navegação.
  2. Para abrir a lista, clique em Intents na navegação.
  3. Clique em + (sinal de adição) no final da lista de intents. Nomeie a nova intent 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

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 navegação.
  2. Clique no sinal + (sinal de adição) na cena Start ao lado de Tratamento da intent do usuário.
  3. Na seção Intent, selecione Não na lista suspensa.

4aa558abdecb3121.png

  1. Clique em Enviar solicitações e 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 na lista suspensa.
  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. Ou então, clique no ícone de sugestão No.

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.

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 navegação.
  2. Clique na guia Webhook na navegação.
  3. Selecione Cloud Functions in-line e 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 saiba chamar essa função quando o usuário invocar sua ação.

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

  1. Clique em Invocação principal na navegação.
  2. Desmarque Enviar solicitação e selecione Chamar seu webhook.
  3. 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. Para testar sua ação no simulador, 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!"

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

Recursos de aprendizado adicionais

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

Siga o perfil @ActionsOnGoogle no Twitter para ver os anúncios mais recentes e envie um tuíte com #AoGDevs para compartilhar suas criações!

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 Como excluir um projeto. Caso contrário, seu projeto será removido automaticamente após cerca de 30 dias.

Pesquisa de feedback

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