A plataforma para desenvolvimento do Google Assistente permite com que você crie software de forma a estender a funcionalidade do Google Assistente, um assistente pessoal e virtual, encontrado em mais de 1 bilhão de aparelhos, incluindo smart speakers, telefones, carros, TVs, headphones, e outros. Os usuários podem engajar com o assistente em conversas a fim de completar tarefas, como por exemplo fazer compras ou alugar uma bicicleta. Como pessoa desenvolvedora, você pode utilizar a plataforma de desenvolvedores do Assistente para criar e gerir experiências conversacionais encantadoras e eficazes entre utentes e o seu próprio serviço de fulfilment de terceiros.

Este codelab cobre conceitos de nível iniciante para desenvolver com o Google Assistente; você não precisa de nenhuma experiência prévia com a plataforma para completá-lo. Neste codelab, você irá construir uma Ação para Google Assistente que diz a sorte ao usuário uma vez que ele(a) começa sua aventura na terra mítica de Gryffinberg. No codelab nível 2 do Actions Builder, você poderá personalizar a Ação mais a fundo, e dizer a sorte ao usuário com base na entrada.

O que você construirá

Neste codelab, você irá construir uma Ação simples com as seguintes funcionalidades:

Ao finalizar este codelab, sua Ação terá o seguinte fluxo de conversa:

O que você aprenderá

O que você irá precisar

As seguintes ferramentas são necessárias no seu ambiente:

A seção a seguir descreve como configurar o seu ambiente de desenvolvimento e criar seu projeto Actions.

Cheque suas configurações de permissão do Google

Para testar a Ação que você construirá neste codelab, você precisa habilitar as permissões necessárias para que o simulador possa acessar a sua Ação. Para habilitar as permissões, siga os seguintes passos:

  1. Vá a página de Controles de atividade.
  2. Entre com sua conta Google, se você já não o tiver feito.
  3. Habilite as seguintes permissões:

Crie um projeto Actions

Seu projeto Actions é um contêiner para a sua Ação. Para criar seu Actions project para este codelab, siga estes passos:

  1. Abra o Actions console.
  2. Clique em New project.
  3. Digite o Project name (nome do projeto), como por exemplo actions-codelab. (Este nome é para sua referência interna, Mais tarde você pode definir um nome externo para o seu projeto)

  1. Clique em Create project.
  2. Na tela What kind of Action do you want to build?, selecione o card Custom.
  3. Clique em Next.
  4. Selecione o card Blank project.
  5. Clique em Start building.

Os usuários iniciam a conversa com a sua Ação através da invocation. Por exemplo, se você tiver uma Ação chamada HoraDoFilme, os usuários podem invocá-la ao dizer a frase "Hey Google, fale com a HoraDoFilme", onde HoraDoFilme é o display name. Sua ação deve ter um display name se você quiser fazer o deploy para produção; todavia, para testar a sua Ação você não precisa de definir o display name. Ao invés disto, você pode usar a frase "Falar com o app meu app de teste" no simulador para invocar a sua ação.

Você deve editar a main invocation (invocação principal) para definir o que acontece após o usuário invocar a sua Ação.

Por padrão, Actions Builder fornece um prompt genérico quando sua invocação é disparada ("Comece a construir sua ação ao definir a invocação principal.").

Na próxima seção, você personalizará o prompt para sua invocação principal no console Actions.

Configure uma main invocation (invocação principal)

Para modificar o prompt que sua ação enviará de volta ao usuário quando ele invoca sua ação, siga estas etapas:

  1. Clique em Main invocation (Invocação principal) na navegação.

  1. No editor de código, substitua o texto no campo de speech (Comece a construir sua ação...) com a seguinte mensagem de boas-vindas: Saudações, aventureiro(a)! Bem-vindo(a) à terra mítica de Gryffinberg! Com base em suas roupas, você não é dessas bandas. Parece que você está a caminho de uma missão épica.
  1. Clique em Save.

Teste a main invocation no simulador

O console Actions fornece uma ferramenta da web para testar sua Ação, chamada de simulador. A interface simula dispositivos de hardware e suas configurações, para que você possa conversar com sua Ação como se ela estivesse em sendo executada em um Smart Display, telefone, alto-falante ou KaiOS.

Quando você invoca sua Ação, ela deve responder com o prompt customizado que você adicionou ("Saudações, aventureiro(a)! ...")

Para testar a invocação principal da sua Ação no simulador, siga estes passos:

  1. Na barra de navegação superior, clique em Test para ir para o simulador.
  2. Para invocar sua ação no simulador, digite Falar com o app meu app de teste no campo Input (entrada) no canto superior esquerdo e pressione Enter.

Quando você aciona a invocação principal de sua Ação, o Assistente responde com sua mensagem de boas-vindas customizada. A esta altura, a conversa termina depois que o Assistente responde com uma saudação. Na próxima seção, você modificará sua Ação para que a conversa continue.

Visualize logs de eventos

Quando você está na aba de Teste, o painel à direita mostra os registros de eventos, que exibem o histórico da conversa como log de eventos. Cada um exibe os eventos que acontecem durante aquele turno da conversa.

Sua Ação tem atualmente um log de evento, que mostra a entrada do usuário ( "Falar com o app meu app de teste") e a resposta de sua Ação. A captura de tela a seguir mostra o log de eventos do sua Ação:

Se você clicar na seta para baixo no log de eventos, poderá ver os eventos, organizados cronologicamente, que ocorreram naquele turno da conversa:

Logs de eventos dão visibilidade de como sua Ação está funcionando e são ferramentas úteis para depurar sua Ação se você tiver algum problema. Para ver os detalhes de um evento, clique na seta ao lado do nome do evento, conforme mostrado na captura de imagem a seguir:

Agora que você definiu o que acontece depois que um usuário invoca sua Ação, você pode construir o resto da conversa de sua Ação. Antes de continuar com este codelab, familiarize-se com os seguintes termos para compreender como a conversa do sua Ação funciona:

Sua ação pode ter uma ou várias cenas, e você deve ativar cada cena antes que ela possa ser executada. (A Ação que você construirá neste codelab tem apenas uma cena intitulada Start). A maneira mais comum de ativar uma cena é configurar sua Ação de modo que, quando o usuário insere uma informação, ela corresponda a uma intenção nesta cena, desencadeando a transição para outra cena e a ativa.

Por exemplo, imagine uma Ação hipotética que fornece fatos sobre animais ao usuário. Ao invocar esta ação, a intenção de invocação principal é correspondida e dispara a transição para uma cena chamada Fatos. Essa transição ativa a cena chamada Fatos, que envia a seguinte mensagem ao usuário: Você gostaria de ouvir um fato sobre gatos ou cachorros? Dentro da cena de Fatos há uma intenção personalizada chamada Gato, 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 "gato". Quando o usuário pede para ouvir um fato a respeito de gatos, a intenção de gato é correspondida e dispara uma transição para uma cena chamada fato sobre gatos. A cena de fato sobre gatos é ativada e envia um prompt ao usuário que inclui um fato sobre gatos.

Figura 1. O fluxo de uma conversa típica se transforma em uma ação construída com o Actions Builder.

Juntos, cenas, intenções e transições formam a lógica de sua conversa e definem os vários caminhos que seu usuário pode seguir através da conversa de sua Ação. Na seção a seguir, você criará uma cena e definirá como ela é ativada depois que um usuário invoca sua ação.

Faça a transição da main invocation para scene

Nesta seção, você criará uma nova cena chamada Start, que envia um prompt ao usuário perguntando se ele gostaria de saber o futuro. Você também adicionará uma transição da invocação principal para a nova cena Start.

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

  1. Clique em Develop (desenvolver) na navegação superior. Em seguida, clique na Main invocation (invocação principal) na navegação à esquerda.
  2. Na seção Transition (transição) à direita, clique no menu suspenso e digite Start no campo de texto.

  1. Clique em Add (adicionar). Isso cria uma cena chamada Start e diz à Ação para fazer a transição para a cena Start após a Ação entregar o prompt de boas-vindas ao usuário.
  2. Clique em Scenes (cenas) na navegação à esquerda para mostrar a lista de cenas.
  3. Em Scenes (cenas), clique em Start para ver a cena Start .
  4. Clique em + na seção On enter da cena Start .
  5. Selecione Send prompts.
  6. Substitua a frase no campo de fala (Digite a resposta que os usuários verão ou ouvirão...) por uma pergunta a ser feita ao usuário: Antes de continuar em sua busca, gostaria de ouvir sua sorte?

  1. Clique em Save.

O Google Assistente fornece este prompt (antes de continuar em sua busca...) para o usuário quando ele entra na cena Start.

Adicione balões de sugestão

Os balões de sugestão oferecem sugestões clicáveis para os usuários, que a sua Ação processa como entrada do usuário. Nesta seção, você irá adicionar balões de sugestão que aparecem abaixo do prompt que você acabou de configurar. (Antes de continuar em sua busca, gostaria de ouvir a sua sorte?) para auxiliar os arquivos com aparelhos que possuem telas.

Para adicionar balões de sugestão ao prompt da cena Start, siga estas etapas:

  1. Na Start scene (cena Start), clique nas suggestions (sugestões) abaixo do editor de código. Essa ação adiciona um único balão de sugestão.
  2. No campo de título, substitua a Suggested Response (Resposta sugerida) por 'Sim' .
  3. Usando a mesma formatação, adicione manualmente um balão de sugestão intitulado ' 'Nao'. Seu código deve ser semelhante ao seguinte snippet:
    suggestions:
      - title: 'Sim'
      - title: 'Não'
  1. Clique em Save.

Teste a sua Ação no simulador

Neste ponto, sua ação deve fazer a transição da invocação principal para a cena Start e perguntar ao usuário se ele(a) gostaria que sua sorte fosse lida. Balões de sugestão também devem aparecer na tela simulada.

Para testar sua ação no simulador, siga estas etapas:

  1. Na barra de navegação, clique em Test para ser levado(a) ao simulador.
  2. Para testar sua ação no simulador, digite Falar com o app meu app de teste no campo Input .
  3. Pressione Enter. Sua ação deve responder com o prompt de invocação principal e o prompt da cena Start adicionado, "Antes de continuar em sua missão, gostaria de saber sua sorte?".

A captura de tela a seguir mostra essa interação:

  1. Clique no balão de sugestão Sim ou Nao para responder ao prompt. (Você também pode dizer "Sim" ou "Nao" ou inserir Sim ou Nao no campo de Input).

Quando você responde ao prompt, sua Ação responde com uma mensagem indicando que não é possível compreender sua entrada: "Desculpe, não entendi. Você poderia tentar novamente?" Como você ainda não configurou sua Ação para compreender e responder a entrada "Sim" ou "Não", sua Ação corresponde a sua entrada a uma intenção NO_MATCH .

Por padrão, a intenção do sistema NO_MATCH fornece respostas genéricas, mas você pode customizar essas respostas para indicar ao usuário que não foi possível compreender o que foi inserido. O Assistente encerra a conversa do usuário com a sua Ação, depois que não foi possível corresponder à entrada três vezes.

Adicione intenções de sim e não

Agora que os usuários podem responder à pergunta que sua Ação dispõe, você pode configurá-la para compreender as respostas dos usuários ("Sim" ou "Nao"). Nas seções a seguir, você cria intenções personalizadas que são correspondidas quando o usuário diz "Sim" ou "Nao" e adiciona essas intenções à cena Start.

Crie a intenção sim

Para criar o intent sim siga os seguintes passos:

  1. Clique em Develop (desenvolver) na navegação.
  2. Clique em Intents na navegação para abrir a lista de intents.
  3. Clique em + (sinal de mais) no final da lista de intents. Nomeie a nova intenção como sim e pressione Enter.
  4. Clique na intenção sim para abrir a página de intenção sim.
  5. Na seção Add training phrases (Adicionar frases de treinamento), clique na caixa de texto Enter Phrase e digite as seguintes frases:

  1. Clique em Save.

Adicione a intenção sim à scene Start

Agora a Ação pode compreender quando um usuário exprime uma intenção de "sim". Você pode adicionar o intent personalizado sim a cena Start, uma vez que um usuário está respondendo ao prompt Start ("Antes de continuar a missão, gostaria de saber a sua sorte?").

Para adicionar esta intenção personalizada na Start scene, siga os seguintes passos:

  1. Clique na cena Start no navegador.
  2. Clique no + (sinal de mais) na Start scene próximo do User intent handling.
  3. Selecione sim no menu drop-down de intent.

  1. Clique em Send prompts and atualize o campo speech com o seguinte texto: Seu futuro depende do que você escolher na sua missão. Escolha com sabedoria. Até mais, desconhecido(a).

O código no seu editor deve estar como pode ser visto no trecho de código abaixo:

 candidates:
  - first_simple:
      variants:
        - speech: >-
            Sua sorte depende do que você escolher na sua missão. Escolha com sabedoria. Até mais, desconhecido(a).
  1. Na seção Transition, clique no menu dropdown e selecione End conversation.
  2. Clique em Save.

Teste a intenção sim no simulador

Neste ponto, sua Ação compreende quando o usuário quer ouvir sua sorte e retorna a resposta apropriada.

Para testar essa intenção no simulador, siga estas etapas:

  1. Na barra de navegação, clique em Test .
  2. Para testar sua ação no simulador, digite Falar com o app meu app de teste no campo Entrada e pressione Enter .
  3. Digite Sim no campo de Entrada e pressione Enter. De forma alternativa, clique no balão de sugestão Sim.

Sua ação responde ao usuário e diz a ele que sua sorte depende da ajuda que escolherem. Sua Ação então encerra a sessão porque você selecionou a transição Encerrar conversa para o intent sim..

Crie a intenção não

Agora, você precisa de criar o intent que compreende e responde ao usuário quando eles não querem saber a sua sorte. Para criar tal intent, siga os seguintes passos.

  1. Clique em Develop no navegador.
  2. Clique em Intents na navegação para abrir a lista de intents.
  3. Clique em + (sinal de mais) no final da lista de intents. Nomeie a nova intenção como nao e pressione Enter .
  4. Clique em não
  5. Na seção Adicionar frases de treinamento, clique em na caixa de texto Inserir frase e digite as seguintes frases:
  1. Clique em Save.

Adicione a intenção não à scene Start

Agora, a Ação pode compreender quando um usuário está expressando "não" ou algo semelhante a "não", como "não" . Você precisa adicionar a intenção personalizada nao à cena Start porque o usuário está respondendo ao prompt inicial ("Antes de continuar em sua busca, gostaria que sua sorte fosse informada?").

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

  1. Clique na cena Start na navegação.
  2. Clique no + (sinal de mais) na cena Start ao lado de User intent handling.
  3. Na seção Intent, selecione não no menu suspenso.

  1. Clique em Send prompts e atualize o campo speech com o seguinte texto: Entendi desconhecido(a). Boa sorte em sua missão! Adeus.

O código em seu editor deve ser semelhante ao seguinte snippet:

 candidates:
  - first_simple:
      variants:
        - speech: >-
            Entendi desconhecido(a). Boa sorte em sua missão! Adeus.
  1. Na seção Transition, selecione End conversation no menu suspenso.
  2. Clique em Save.

Teste a intenção não no simulador

Neste ponto, sua Ação compreende quando o usuário não quer ouvir sua sorte e retorna a resposta apropriada.

Para testar essa intenção no simulador, siga estas etapas:

  1. Na barra de navegação, clique em Teste .
  2. Digite Falar com o app meu app de teste no campo de Input e pressione Enter.
  3. Digite Nao no campo de Input e pressione Enter. Como alternativa, clique no balão de sugestão Nao.

Ao invés de dizer a sorte ao usuário, sua Ação deseja sorte em sua missão. Sua Ação então encerra a sessão porque você selecionou a transição End conversation para o intent não.

Atualmente, as respostas do sua Ação são estáticas; quando uma cena contendo um prompt é ativada, sua Ação envia o mesmo prompt todas as vezes. Nesta seção, você implementará o fulfillment que contém a lógica para construir uma resposta conversacional dinâmica.

Seu fulfillment identifica se a pessoa usuária é recorrente ou nova e modifica a mensagem de saudação da Ação para usuários recorrentes. Ela é abreviada para usuários(as) recorrentes e reconhece o seu retorno: "Saudações, aventureiro(a)! Bem-vindo(a) de volta à terra mítica de Gryffinberg!"

Para este codelab, use o editor Cloud Functions no console Actions para editar e fazer o deploy de seu código de fulfillment.

Sua Ação pode acionar webhooks que notificam seu fulfillment de um evento que ocorre durante uma invocação ou partes específicas da execução de uma cena. Quando um webhook é disparado, sua Ação envia uma solicitação com uma carga útil JSON para seu fulfillment junto com o nome do manipulador a ser usado para processar o evento. Esse manipulador executa alguma lógica e retorna uma resposta JSON correspondente.

Construa seu fulfillment

Agora você pode modificar seu fulfillment no editor embutido para gerar diferentes prompts para usuários recorrentes assim como novos quando eles invocarem sua ação.

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

  1. Clique em Develop no navegador.
  2. Clique na aba Webhook no navegador.
  3. Selecione Inline Cloud Functions e clique em Confirmar. O código boilerplate é adicionado automaticamente para os arquivos index.js e package.json.

  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 = 'Saudações, aventureiro(a)(a)! Bem-vindo(a) de volta à terra mítica de Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Bem-vindo(a) à terra mítica de Gryffinberg! Com base em suas roupas, você não é dessas bandas. Parece que você está a caminho de uma missão épica.';
 }
 conv.add(message);
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
  1. Clique em Save Fulfillment.
  2. Clique em Deploy Fulfillment.

Aguarde alguns minutos para que as Cloud Functions possam fornecer e fazer o deploy de seu fulfillment. Você deve ver uma mensagem de deployment do Cloud Function em andamento... acima do editor de código. Quando o deploy código é com sucesso, a mensagem é atualizada para a Your Cloud Function deployment is up to date.

Compreenda o código

Seu fulfillment, que usa a biblioteca Actions on Google Fulfillment para Node.js, responde a solicitações HTTP do Google Assistente.

No trecho de código anterior, você definiu o manipulador de saudação, que verifica se o usuário já visitou a Ação, verificando se há um valor na propriedade lastSeen Time. Se houver um valor datetime, a mensagem reconhece o retorno do usuário e gera uma saudação modificada; caso contrário, ele fornece a saudação original ao novo usuário.

Atualize a invocação principal para desencadear um webhook

Agora que você definiu a função de saudação, você pode configurar o manipulador de eventos de saudação em sua intenção de invocação principal para que sua Ação saiba chamar essa função quando o usuário invocar sua Ação.

Para configurar sua Ação para chamar o novo manipulador de saudação, siga estas etapas:

  1. Clique em Main invocation na navegação .
  2. Desmarque Send prompt e selecione Call your webhook.
  3. Adicione a saudação a caixa de texto.

  1. Clique em Save.

Teste a main invocation atualizada no simulador

Para testar sua ação no simulador, siga estas etapas:

  1. Na barra de navegação, clique em Test para levar você ao simulador.
  2. Para testar sua ação no simulador, digite Falar com o app meu app de teste no campo Input e pressione Enter .

Como você testou sua Ação anteriormente neste codelab, você não é um novo usuário, então recebe a seguinte saudação abreviada: "Saudações, aventureiro(a)! Bem-vindo(a) de volta à terra mítica de Gryffinberg!... "

Parabéns!

Você aprendeu o básico de construir Ações para o Google Assistente.

O que você cobriu:

Recursos de aprendizado adicionais

Explore os seguintes recursos para aprender mais sobre a construção de ações para o Google Assistente.

Siga @ActionsOnGoogle no Twitter para os últimos anúncios e tuíte com a #AoGDevs para compartilhar o que você criar!

Pesquisa de Feedback

Antes de ir, por favor preencha uma breve pesquisa sobre a sua experiência.