Criar ações para o Google Assistente usando o SDK do Actions (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 básicos de desenvolvimento com o SDK do Actions para 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 SDK do Actions, 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 ao usuário com uma mensagem de saudação.
• Fazer uma pergunta ao usuário. Quando o usuário responder, a ação irá gerar uma resposta 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 (veja a informação dada pelo usuário ao lado do microfone e a resposta da ação ao lado do alto-falante):

O que você aprenderá

• Como criar um projeto no Console do Actions
• Como usar a ferramenta gactions para enviar e receber seu projeto de ação entre o Console do Actions e seu sistema de arquivos local
• 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:

• Um IDE/editor de texto de sua escolha
• Um terminal para executar comandos de shell para NodeJS e NPM
• Um navegador da Web, como o Google Chrome

Observação: se você prefere trabalhar com ferramentas visuais para criar ações, faça o Codelab de criação de ações do Google Assistente usando o Actions Builder (nível 1). Ele mostra como criar a mesma Ação usando o ambiente de desenvolvimento integrado do Actions Builder no console.

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

4. Clique em Criar projeto.
5. Na tela Que tipo de ação você quer criar?, selecione o card Personalizado. Clique em Próxima.
6. Na tela Como você quer criá-lo?, selecione o card Projeto em branco. Em seguida, clique em Começar a criar.

Salvar o ID do projeto da sua ação

O ID do projeto é um identificador exclusivo para sua ação. Você vai precisar dele em várias etapas deste codelab.

Para recuperar esse ID, siga estas etapas:

1. No Console do Actions, clique nos três pontos verticais (insira o ícone aqui) no canto superior direito.
2. Clique em Configurações do projeto.

3. Copie o ID do projeto.

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 seu projeto", na página "Próximas etapas", no final deste codelab.

Instalar a interface de linha de comando do gactions

Neste codelab, você vai usar a ferramenta de interface de linha de comando (CLI) do gactions para sincronizar seu projeto no Console do Actions e no sistema de arquivos local.

Termo-chave:

• CLI do gactions: uma ferramenta que permite inicializar arquivos do projeto do Actions, enviar atualizações para o Console do Actions, implantar projetos e muito mais.

Para instalar a CLI do gactions, siga as instruções na seção Instalar a ferramenta de linha de comando gactions.

Fazer o download do projeto do Actions

Para começar a desenvolver sua ação, faça o download do seu projeto no Console do Actions.

Para fazer o download, siga estas etapas:

1. Para criar e começar a usar um diretório, execute os seguintes comandos:

mkdir myproject
cd myproject

2. Para copiar a configuração do projeto do Actions no seu sistema de arquivos local, execute o seguinte comando:

gactions pull --project-id <projectID>

Entender a estrutura de arquivos

O projeto que você fez o download no Console do Actions é representado em uma estrutura de arquivos YAML. A imagem a seguir mostra essa estrutura em detalhes:

A estrutura de arquivo inclui o seguinte:

• actions/: representa seu projeto do Actions. O sistema chama actions.yaml quando sua ação é invocada, que, por sua vez, chama o arquivo custom/global/actions.intent.MAIN.yaml.
• custom/: o diretório em que você vai trabalhar para modificar sua ação.
• global/: esse diretório contém intents do sistema que a plataforma adiciona ao projeto automaticamente. Você vai aprender mais sobre intents do sistema neste codelab.
• manifest.yaml: um arquivo que contém informações que podem ser "transportadas", ou seja, que não são específicas a um determinado projeto e podem ser transferidas para outros projetos.
• settings/: representa as configurações de um projeto do Actions, como o nome de exibição, a localidade padrão e a categoria.

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", 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 fazer testes. Nesse caso, você pode usar a frase "Falar com meu app de teste" no simulador para invocar a ação. Você vai saber mais sobre o simulador nesta seção.

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

Termo-chave:

• Invocação principal: um ponto de entrada para que o usuário inicie conversas com sua ação. Quando o usuário disser uma frase como "Ok Google, falar com <nome de exibição>", a principal invocação será acionada e responderá ao usuário.

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

Termo-chave:

• Solicitação: define o que sua ação envia aos usuários como resposta. As solicitações podem ser respostas de texto e fala simples ou mensagens avançadas, como cartões e imagens.

É possível usar uma solicitação especial, Canvas, para retornar recursos visuais em tela cheia para o usuário. Para mais informações sobre Canvas, consulte a documentação do Canvas interativo.

Na próxima seção, você vai personalizar a solicitação da invocação principal no arquivo custom/global/actions.intent.MAIN.yaml.

Configurar invocação principal

É possível editar sua solicitação de invocação principal no arquivo actions.intent.MAIN.yaml.

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

1. Abra custom/global/actions.intent.MAIN.yaml no seu editor de texto.
2. 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.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: 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.
transitionToScene: actions.scene.END_CONVERSATION

3. Salve o arquivo.

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.

Observação: você pode encontrar as informações mais recentes sobre como usar o simulador do Console do Actions no guia do simulador do Actions. Consulte caso encontre algum problema ao seguir as próximas etapas.

Agora, ao invocar uma ação, a resposta deve ser a solicitação personalizada que você adicionou ("Saudações calorosas, aventureiro!").

Use o comando gactions deploy preview para testar a ação no console sem atualizar a versão do projeto do Actions. Ao executar esse comando, nenhuma das alterações feitas no sistema de arquivos local é propagada para as versões implantadas do projeto do Actions, mas é possível testar em uma versão de visualização.

Para testar a invocação principal da ação no simulador, siga estas etapas:

1. Para implantar o projeto no Console do Actions para teste, execute o seguinte comando no terminal:

gactions deploy preview

Observação: talvez você receba uma notificação sobre problemas de validação ao executar esse comando. Se seus arquivos já tiverem sido enviados, ignore esse aviso.

A saída será semelhante a esta:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copie e cole o URL fornecido em um navegador.
3. Para invocar sua ação no simulador, digite Talk to my test app no campo Entrada no canto superior esquerdo e pressione Enter.

Dica: para invocar sua ação, você também pode clicar no ícone de sugestão Talk to my test app em Sugestões, que é processado da mesma forma que a entrada de usuário falada ou digitada. Ou então, clique no ícone do microfone e diga "Falar com meu app de teste".

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 ("Falar com meu app de teste") e a resposta da ação. Veja o log de eventos do Action na captura de tela a seguir:

Se clicar na seta para baixo ao lado de Talk to my test app 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 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 depuração 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:

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:

Termos-chave:

• Cena: um "elemento de construção" da sua ação que processa a entrada do usuário e costuma gerar a resposta para o usuário. As intents personalizadas geralmente ativam outras cenas, mas também podem ser ativadas de outras maneiras.
• Intent personalizada: define a entrada do usuário que a ação pode entender. Você pode definir as frases de treinamento dessas intents. Quando os usuários dizem algo que corresponde ou é semelhante a uma frase de treinamento, a intent correspondente é acionada.
• Frases de treinamento: exemplos do que um usuário pode dizer para gerar a correspondência com uma intent. O mecanismo de processamento de linguagem natural (PLN) do Google Assistente expande naturalmente essas frases e inclui outras que sejam semelhantes.
• Transição: define para que cena será feita a transição quando a condição for atendida.

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 e ative outra cena.

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.

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

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. Abra custom/global/actions.intent.MAIN.yaml no seu editor de texto.
2. Substitua o texto no campo transitionToScene (actions.scene.END_CONVERSATION) pelo seguinte: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: 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.
transitionToScene: Start

Isso fará com que a ação transite da invocação principal para a cena Start.

3. Salve o arquivo.
4. No terminal, crie um diretório scenes no diretório custom:

mkdir custom/scenes

5. Crie um arquivo chamado Start.yaml no diretório scenes, que representa a cena start na sua ação:

touch custom/scenes/Start.yaml

6. Abra Start.yaml no seu editor de texto.
7. Cole o código a seguir no arquivo Start.yaml:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

No código do arquivo Start.yaml, há um campo chamado onEnter, que é a primeira etapa executada no ciclo de vida de uma cena.

Termos-chave:

• OnEnter: A etapa executada quando uma cena é ativada. OnEnter define o que acontece quando o usuário entra na cena.

Nesse caso, a solicitação (Before you continue on your quest...) é adicionada à fila de solicitações quando o usuário entrar na cena Start pela primeira vez.

Termos-chave:

• Fila de solicitações: as solicitações são anexadas umas às outras em uma fila. Para que o usuário possa responder, o Google Assistente apresenta todas as solicitações na fila.

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 Yes e No 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. Atualize o código em Start.yaml para corresponder ao seguinte snippet de código, que inclui o necessário para configurar ícones de sugestão:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. Salve o arquivo.

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. No terminal, execute o seguinte comando:

gactions deploy preview

A saída será semelhante a esta:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copie e cole o URL fornecido em um navegador.
3. Clique em Testar para acessar o simulador.
4. Digite Talk to my test app no campo Entrada, no canto superior esquerdo. Depois, pressione Enter. Sua ação precisa ser uma resposta à 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?", com os ícones de sugestão exibidos.

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

Observação: os logs de eventos registram cada uma das interações do simulador na sessão atual, para que o log de eventos dos testes anteriores neste codelab apareça primeiro. Para limpar os logs de eventos, clique em Redefinir teste.

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

Termos-chave:

• NO_MATCH: uma intent "pega-tudo" que é associada quando o usuário diz algo que não corresponda a outra intent na sua ação.
• Intent do sistema: uma intent que é configurada por padrão e lida com eventos comuns do sistema, como quando um usuário não fornece nenhuma entrada. NO_MATCH e a intent ligada à invocação principal são exemplos de intents do sistema.

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

Criar intent yes

Para criar a intent yes, siga estas etapas:

1. No terminal, crie um diretório chamado intents no diretório custom:

mkdir custom/intents

2. Crie um arquivo chamado yes.yaml no diretório intents:

touch custom/intents/yes.yaml

3. Abra yes.yaml no seu editor de texto.
4. Cole o snippet de código a seguir, que contém frases de treinamento em yes.yaml:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. Salve o arquivo.

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 personalizada 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 personalizada à cena Start, siga estas etapas:

1. Abra custom/scenes/Start.yaml no seu editor de texto.
2. Adicione os gerenciadores intentEvents e yes ao final do arquivo Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

Quando a intent yes tiver uma correspondência, a solicitação "Seu futuro depende do item que você escolher para sua missão…" é adicionada à fila. Em seguida, a cena Start faz a transição para a cena do sistema actions.scene.END_CONVERSATION, que entrega as solicitações na fila e encerra a conversa.

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. No terminal, execute o seguinte comando:

gactions deploy preview

A saída será semelhante a esta:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copie e cole o URL fornecido em um navegador.
3. Clique em Testar para acessar o simulador.
4. Para testar sua ação no simulador, digite Talk to my test app no campo Entrada, no canto superior esquerdo, e pressione Enter.
5. Digite Yes no campo Entrada e pressione Enter. Ou então, clique no ícone de sugestão Yes.

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ê configurou a transição End conversation para a intent yes.

Criar intent no

Agora você pode criar a intent no para que sua ação possa 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. No terminal, crie um arquivo chamado no.yaml no diretório intents:

touch custom/intents/no.yaml

2. Abra no.yaml no seu editor de texto.
3. Cole as seguintes frases de treinamento no arquivo no.yaml:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. Salve o arquivo.

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. Abra custom/scenes/Start.yaml no seu editor de texto.
2. Adicione o gerenciador no abaixo do gerenciador yes em Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. Salve o arquivo.

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. No terminal, execute o seguinte comando:

gactions deploy preview

A saída será semelhante a esta:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copie e cole o URL fornecido em um navegador.
3. Clique em Testar para acessar o simulador.
4. Digite Talk to my test app no campo Entrada e pressione Enter.
5. Digite No no campo Entrada e pressione Enter. Ou então, clique no ícone de sugestão No.

Em vez de dar a previsão do futuro ao usuário, sua ação vai gerar uma mensagem de boa sorte na missão. Sua ação termina a sessão porque você configurou 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.

Termo-chave:

• Fulfillment: o código com a lógica da sua ação. Um webhook aciona chamadas para o fulfillment com base em eventos que ocorrem nas suas ações.

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.

Termo-chave:

• Editor do Cloud Functions: um editor integrado para projetos do Actions que pode ser usado para editar e implantar seu código de fulfillment usando o Cloud Functions para Firebase.

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

Nesta seção, você vai modificar o fulfillment 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. No terminal, verifique se você está no diretório raiz do seu projeto e crie um diretório webhooks:

mkdir webhooks

2. Crie um arquivo chamado ActionsOnGoogleFulfillment.yaml no diretório webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Abra ActionsOnGoogleFulfillment.yaml no seu editor de texto.
4. Adicione o gerenciador greeting e o conteúdo inlineCloudFunction ao arquivo ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

O arquivo ActionsOnGoogleFulfillment.yaml define os gerenciadores de webhook (como o gerenciador greeting) e instrui a ação a usar o Cloud Functions como o endpoint do webhook.

5. Crie um diretório ActionsOnGoogleFulfillment no diretório webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. Crie um arquivo chamado index.js no diretório ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Abra index.js no seu editor de texto.
8. Adicione o código a seguir a index.js:

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);

Esse código define o gerenciador greeting, que envia a saudação apropriada ao usuário.

9. Salve o arquivo.
10. Crie um arquivo chamado package.json no diretório ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

O arquivo package.json especifica dependências e outros metadados para seu webhook.

11. Abra package.json no seu editor de texto.
12. Copie o código deste repositório do GitHub e cole no arquivo package.json.
13. Salve o arquivo.

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 a propriedade lastSeenTime não estiver definida, o usuário é novo e receberá a saudação correspondente. Caso contrário, a mensagem reconhecerá o retorno do usuário e irá gerar uma saudação modificada.

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. Abra custom/global/actions.intent.MAIN.yaml no seu editor de texto.
2. Substitua o código em actions.intent.MAIN.yaml pelo seguinte:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Salve o arquivo.

Agora, quando sua intent de invocação principal for correspondida, o gerenciador do webhook greeting será chamado.

Testar a invocação principal atualizada no simulador

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

1. No terminal, execute o seguinte comando:

Observação: como este comando implanta o webhook e instala dependências, ele pode demorar mais que os comandos anteriores.

gactions deploy preview

Atenção: se você receber um erro 403 sobre a API Cloud Build ou ao associar a conta de faturamento, consulte a página Modificar as configurações de faturamento de um projeto para associar uma conta de faturamento. Para implantar usando o Cloud Functions, você precisa associar uma conta de faturamento ao seu projeto no Google Cloud. Quando concluir, execute gactions deploy preview novamente. Para evitar cobranças, siga as etapas da seção "Como limpar seu projeto", na página "Próximas etapas", no final deste codelab.

A saída será semelhante a esta:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copie e cole o URL fornecido em um navegador.
3. 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!"

O SDK do Actions tem interoperabilidade com um IDE baseado na Web chamado Action Builder, que é integrado ao Console do Actions. É possível enviar seu sistema de arquivos local para o rascunho da sua ação no console com o comando gactions push. Ao contrário de gactions deploy preview, que só permite testar sua ação no simulador, o gactions push move todo o conteúdo dos arquivos locais para o Actions Builder.

O Console do Actions tem uma representação visual da configuração da ação. Visualizar pode ser útil durante o desenvolvimento e não afeta a versão veiculada para teste.

Observação: executar gactions push substitui o rascunho atual do seu projeto do Actions se estiver trabalhando de forma colaborativa.

Para enviar e visualizar seu projeto no Console do Actions, siga estas etapas:

1. No terminal, execute o seguinte comando para enviar seu projeto ao Console do Actions:

gactions push

A saída será semelhante a esta:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. Copie e cole o URL fornecido em um navegador.
3. No Console do Actions, clique em Desenvolver na barra de navegação superior.
4. Clique na seta suspensa ao lado de Cenas e clique em Iniciar. Você verá uma representação visual da cena Start da ação, conforme esta captura de tela:

Parabéns!

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

Conteúdo abordado

• Como configurar um projeto no Console do Actions
• Como usar o SDK do Actions para criar seu projeto no sistema de arquivos local
• 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:

• O site de documentação oficial para desenvolver ações para o 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.

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]

Atenção: o codelab de nível 2, "Criar ações para o Google Assistente usando o SDK do Actions (nível 2)", se baseia no projeto que você criou neste codelab. Se você planeja fazer o codelab de nível 2, não exclua seu projeto. É possível fazer isso na seção "Como limpar seu projeto" no fim do codelab de nível 2.

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.

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

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