Envolva os usuários com a ação para o Google Assistente

1. Visão geral

Aviso: as ações de conversa foram descontinuadas em 13 de junho de 2023. Para mais informações, consulte Desativação das ações de conversa.

O Actions on Google é uma plataforma para desenvolvedores que permite criar softwares para ampliar a funcionalidade do Google Assistente, o assistente pessoal virtual do Google, 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. Para uma lista completa do que é possível fazer, consulte o diretório de ações. Como desenvolvedor, você pode usar o Actions on Google para criar e gerenciar experiências de conversação eficazes e agradáveis entre os usuários e seu serviço terceirizado.

Este é um módulo de codelab avançado destinado a leitores que já têm alguma experiência com o Actions no Google Assistente. Se você ainda não tem experiência com desenvolvimento no Actions on Google, recomendamos que consulte nossos codelabs de introdução para se familiarizar com a plataforma ( Níveis 1, 2 e 3). Esses módulos avançados dão orientação em uma série de recursos que podem ajudar a expandir a funcionalidade da sua ação e aumentar seu público-alvo.

Uma maneira importante de medir o sucesso de uma ação é o engajamento do usuário ou a eficácia da ação em trazer os usuários de volta após a primeira interação. Para facilitar isso, você pode implementar vários recursos na sua ação que oferecem aos usuários caminhos de volta à conversa.

O codelab aborda recursos de engajamento do usuário e práticas recomendadas para o Actions on Google.

O que você vai criar

Você vai aprimorar um recurso já criado para que ele possa:

• Envie aos usuários uma atualização diária que eles podem tocar para falar com sua ação
• Enviar notificações push aos usuários com um link para sua ação
• Criar um link que leve os usuários à sua ação em um navegador da Web para dispositivos móveis

O que você vai aprender

• O que é engajamento do usuário e por que ele é importante para o sucesso de uma ação
• Como modificar uma ação para aumentar o engajamento do usuário
• Quais recursos de engajamento do usuário usar em diferentes tipos de ações
• Como usar a API Actions para enviar notificações pelo Google Assistente

O que é necessário

Você precisa ter as seguintes ferramentas:

• Um IDE/editor de texto de sua escolha, como WebStorm, Atom ou Sublime
• Um terminal para executar comandos do shell com Node.js, npm e git instalados
• Um navegador da Web, como o Google Chrome
• Um ambiente de desenvolvimento local com a interface de linha de comando do Firebase
• Um dispositivo móvel (Android ou iOS) com o Google Assistente. Faça login no Google Assistente com a mesma Conta do Google que você vai usar para criar este projeto.

É recomendável ter familiaridade com o JavaScript (ES6), embora não seja obrigatório para entender o código do webhook.

2. Criar o projeto

Nesta seção, mostramos como adicionar recursos de engajamento do usuário a uma ação completa criada anteriormente.

Termos-chave:

• Engajamento do usuário:a métrica usada para medir se os usuários encontram valor em um produto ou serviço. O engajamento pode ser representado por quantos usuários retornam à sua ação, que é uma métrica usada para determinar se uma ação deve ser promovida. O alto engajamento do usuário vem de dois componentes de uma ação: informações úteis que os usuários vão querer ver mais tarde e maneiras de voltar à sua ação quando eles provavelmente vão recuperar essas informações.

Entender a amostra

O exemplo deste codelab é uma ação simples para uma academia fictícia chamada "Action Gym". A ação fornece informações sobre a academia, incluindo uma lista de aulas que mudam a cada dia. Uma ação informativa como essa é uma boa opção para todos os recursos de engajamento do usuário porque a lista de turmas rotativa oferece informações úteis diferentes a cada dia.

O diagrama a seguir mostra o fluxo de conversa do exemplo Action Gym:

Você fará pequenas modificações na caixa de diálogo para se adequar melhor aos recursos de engajamento adicionados. No entanto, o design geral da conversa não vai mudar muito.

Fazer o download dos arquivos de base

Execute o comando a seguir para clonar o repositório do GitHub do codelab:

git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs

Configurar o projeto e o agente

Para configurar seu projeto do Actions e o agente do Dialogflow, siga estas etapas:

1. Abra o Console do Actions.
2. Clique em Novo projeto.
3. Digite um Nome do projeto, como engagement-codelab.
4. Clique em Criar projeto.
5. Em vez de escolher uma categoria, role a tela para baixo até a seção Mais opções e clique no card Conversacional.
6. Clique em Criar sua Action para expandir as opções e selecione Adicionar Action(s).
7. Clique em Adicionar sua primeira ação.
8. Na caixa de diálogo Criar ação, selecione Intenção personalizada e clique em Criar para abrir o console do Dialogflow.
9. Na página de criação de agente do console do Dialogflow, clique em Criar.
10. Clique no ícone de engrenagem na navegação à esquerda.
11. Clique em Exportar e importar e em Restaurar de arquivo ZIP.
12. Faça upload do arquivo agent.zip do diretório /user-engagement-codelab-nodejs/start/ que você baixou antes.
13. Digite RESTORE e clique em Restaurar.
14. Clique em Concluído.

Implantar o fulfillment

Agora que o projeto do Actions e o agente do Dialogflow estão prontos, implante o arquivo index.js local usando a CLI do Firebase Functions.

No diretório /user-engagement-codelab-nodejs/start/functions/ do clone dos arquivos de base, execute os seguintes comandos:

firebase use <PROJECT_ID>

Dica: encontre o ID do projeto da sua ação no Console do Actions em Visão geral > (ícone de engrenagem) > Configurações do projeto.

npm install

firebase deploy

Se você receber a mensagem de erro "Ocorreu um erro inesperado na CLI", tente executar o comando firebase deploy novamente.

Após alguns minutos, quando você já tiver implantado o webhook, vai aparecer a mensagem "Implantação concluída!".

Recuperar o URL de implantação

Você precisa fornecer ao Dialogflow o URL da função do Cloud. Para recuperar esse URL, siga estas etapas:

1. Abra o Console do Firebase.
2. Selecione o projeto do Actions na lista de opções.
3. Acesse Desenvolver > Funções na barra de navegação à esquerda. Se você receber a solicitação "Escolher configurações de compartilhamento de dados", ignore essa opção clicando em Fazer isso depois.
4. Na guia Painel, há uma entrada para "fulfillment" com um URL em Gatilho. Salve esse URL. Você precisará copiá-lo no Dialogflow na próxima seção.

Definir o URL do webhook no Dialogflow

Agora você precisa atualizar seu agente do Dialogflow para usar o webhook no fulfillment. Para isso, siga estas etapas:

1. Abra o console do Dialogflow. Se quiser, feche o console do Firebase.
2. Clique em Fulfillment na navegação à esquerda.
3. Ative Webhook.
4. Cole o URL copiado do painel do Firebase, caso ele ainda não apareça.
5. Clique em Salvar.

Verificar se o projeto está configurado corretamente

Os usuários precisam conseguir invocar sua ação para receber informações sobre a Action Gym, incluindo uma resposta de texto codificada com horário de funcionamento e uma resposta de texto que lista a programação das aulas para cada dia da semana.

Dica:você pode encontrar as informações mais recentes sobre como usar o simulador do Actions no guia do simulador do Actions. Consulte esse material caso tenha alguma dificuldade nas etapas abaixo.

Para testar sua ação no simulador do Actions:

1. Na navegação à esquerda do console do Dialogflow, clique em Integrações > Google Assistente.
2. Verifique se a opção Visualizar automaticamente as mudanças está ativada e clique em Testar para atualizar seu projeto de ações.
3. O simulador do Actions carrega seu projeto do Actions. Para testar sua ação, digite Talk to my test app no campo Entrada e pressione "Enter".
4. Você vai receber uma resposta as boas-vindas à Action Gym. Siga as instruções para continuar a conversa e verifique se o atendimento tem uma resposta para cada entrada.

Se você não encontrar essas respostas, provavelmente houve um problema com a configuração do Firebase. Nesse caso, repita as etapas na seção "Implantar seu atendimento".

3. Adicionar assinaturas de atualizações diárias

Uma maneira comum de envolver os usuários é oferecer informações quando elas são mais úteis. Isso é feito oferecendo aos usuários a opção de assinar atualizações diárias para uma intenção, o que envia uma notificação do Google Assistente que vincula diretamente ao atendimento dessa intenção.

Nesta etapa, você vai aprender sobre as assinaturas de atualizações diárias e adicioná-las à intent Lista de turmas da sua ação. Depois de seguir estas instruções, a conversa da sua ação vai ficar parecida com o diagrama a seguir:

Como isso vai engajar os usuários?

Os usuários de smartphones provavelmente conhecem as notificações push, que fornecem informações e atualizações específicas do app. As assinaturas de atualizações diárias são uma maneira simples de acessar usuários em dispositivos móveis fora do Google Assistente, desde que a intenção para a qual você está enviando atualizações continue oferecendo valor ao usuário diariamente.

As atualizações diárias podem ser uma ferramenta de engajamento útil, mas não precisam ser incorporadas em todas as ações. Considere estas dicas ao decidir se vai adicionar assinaturas de atualização diária a uma ação:

• Verifique se as atualizações diárias vão resultar em informações diferentes e úteis para o usuário todos os dias. Se tocar em uma atualização diária resultar na mesma solicitação todas as vezes, o usuário provavelmente vai cancelar a inscrição depois de alguns dias.
• Verifique se a caixa de diálogo faz sentido para o usuário se ele pular direto para a intent de atualização diária. O usuário não vai necessariamente começar do início da conversa, então não é esperado que ele tenha muito contexto.
• Mostre ao usuário o benefício da sua ação antes de pedir que ele se inscreva para receber atualizações diárias. O usuário precisa pensar "Quero esse conteúdo todos os dias" quando tiver a opção de se inscrever.
• Não sobrecarregue o usuário com sugestões repetidas para se inscrever. Ofereça uma assinatura de atualização diária logo após mostrar ao usuário o que ele vai assinar e evite incomodá-lo com isso em outros lugares.
• Mantenha a conversa curta depois que a intenção de atualização for acionada. A maioria das atualizações diárias consiste em uma única resposta e fecha sem exigir entrada do usuário.

Dica:como as atualizações diárias aparecem como notificações no dispositivo do usuário, consulte nossas práticas recomendadas para criar notificações úteis. A maior parte do conteúdo da notificação de atualização diária é pré-projetada para o Google Assistente, mas os mesmos princípios se aplicam ao decidir se as atualizações diárias fazem sentido para sua intenção ou ação.

Ativar atualizações diárias

As assinaturas de atualizações diárias podem ser adicionadas à intent de boas-vindas, que coloca o usuário no início da conversa, ou a uma intent mais específica para criar um link direto para algum lugar dentro da conversa. Para este codelab, o intent Lista de aulas faz mais sentido porque o diálogo muda todos os dias, e os usuários podem achar útil receber um lembrete das aulas disponíveis.

Siga estas etapas para ativar as atualizações diárias da intent Lista de aulas:

1. No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
2. Clique em Lista de turmas na lista Ações.
3. Na seção Engajamento do usuário, ative a opção Você quer oferecer atualizações diárias aos usuários?.
4. Defina um título do conteúdo descritivo que descreva a atualização diária. O contexto será "A que horas você quer receber seu lembrete diário sobre ", então verifique se o título é descritivo e soa correto quando falado em voz alta. Neste exemplo, defina o Título do conteúdo como list of upcoming Action Gym classes.
5. Clique em Salvar na parte de cima da página.

Configurar o Dialogflow

Siga estas etapas no console do Dialogflow para criar intents para o fluxo de assinatura de atualização diária:

Pedir que o usuário se inscreva

1. Configure uma nova intent para lidar com o pedido do usuário de se inscrever nas atualizações diárias. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Setup Updates.
3. Na seção Frases de treinamento, adicione as seguintes expressões do usuário:

• Send daily reminders
• Reminder
• Remind me
• Updates
• Upcoming classes

4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Processar a decisão do usuário

1. Configure uma nova intent para processar a resposta do usuário ao pedido de assinatura das atualizações diárias. Clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Confirm Updates.
3. Na seção Eventos, adicione actions_intent_REGISTER_UPDATE. Esse evento do Dialogflow será acionado quando o usuário concluir o fluxo de assinatura da atualização diária, mesmo que ele tenha feito a assinatura ou não.
4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Implementar o atendimento

Para implementar o fulfillment no seu webhook, siga estas etapas:

Carregar dependências

No arquivo index.js, atualize a função require() para adicionar o pacote RegisterUpdate do pacote actions-on-google. Assim, suas importações vão ficar assim:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
} = require('actions-on-google');

Atualizar ícones de sugestão

No arquivo index.js, adicione uma entrada DAILY à lista de títulos de ícones de sugestão para que sua definição Suggestion fique assim:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
};

Adicionar atendimento para novas intents

Quando o usuário diz que quer se inscrever, inicie o fluxo de inscrição para atualizações diárias chamando o auxiliar RegisterUpdate com a intent de destino da atualização (Lista de turmas) e o tipo (DAILY). Depois que o fluxo de inscrição for concluído, o Google Assistente vai acionar o evento actions_intent_REGISTER_UPDATE com um argumento status que descreve se a inscrição foi bem-sucedida ou não. Ofereça ao usuário solicitações de acompanhamento que mudam dependendo do status da assinatura.

No arquivo index.js, adicione o seguinte código:

index.js

// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
  conv.ask(new RegisterUpdate({
    intent: 'Class List',
    frequency: 'DAILY',
  }));
});

// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
  if (registered && registered.status === 'OK') {
     conv.ask(`Gotcha, I'll send you an update everyday with the ` +
     'list of classes. Can I help you with anything else?');
  } else {
    conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
  }
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
  }
});

Oferecer comandos alternativos ao usuário

Sua resposta da lista de turmas vai oferecer a assinatura de atualização diária no final, mas isso apresenta um problema. Como essa mesma resposta será acionada quando o usuário tocar na notificação de atualização diária, ele ainda vai precisar se inscrever nas atualizações diárias, mesmo que tenha acabado de receber uma. Como evitar que o usuário pense que precisa assinar de novo?

Felizmente, os argumentos do objeto conv incluem informações sobre onde o usuário iniciou a conversa. Verifique os argumentos conv para saber se eles contêm uma seção UPDATES, que indica que o usuário iniciou a conversa em uma notificação de atualização diária, e mude a resposta de acordo. Você também pode usar essa ramificação da conversa para encerrar a caixa de diálogo imediatamente após fornecer a lista de aulas, o que segue nossa prática recomendada de manter a atualização diária curta.

No arquivo index.js, substitua o seguinte código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  const classesMessage =
  `On ${day} we offer the following classes: ${classes}. ` +
  `Can I help you with anything else?`;
  conv.ask(classesMessage);
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS]));
  }
});

com este código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

Testar as atualizações diárias

No terminal, execute o seguinte comando para implantar o código atualizado do webhook no Firebase:

firebase deploy

Dica:você pode encontrar as informações mais recentes sobre como usar o simulador do Actions no guia do simulador do Actions. Consulte esse material caso tenha alguma dificuldade nas etapas abaixo.

Para testar o novo pedido de repetição personalizado no simulador do Actions, siga estas etapas:

1. No Console do Actions, navegue até Testar.
2. Digite Talk to my test app no campo Entrada e pressione Enter.
3. Digite Learn about classes e pressione Enter. A resposta da sua ação agora deve oferecer o envio de lembretes diários.
4. Digite Send daily reminders e pressione Enter.
5. Digite um horário em que você quer ver a atualização e pressione Enter. Para fins de teste, responda 3 a 5 minutos depois do horário atual.

Se você receber um erro ao tentar se inscrever para receber atualizações diárias na etapa 4, volte para Build > Actions > Class List e desative as atualizações diárias. Clique em Save, ative as atualizações diárias novamente, clique em Save de novo e tente testar no simulador outra vez.

No seu dispositivo móvel, você vai receber uma notificação do Google Assistente por volta do horário especificado para atualizações. Essa notificação pode levar alguns minutos para aparecer. Toque na notificação para abrir um link direto para a intenção Lista de turmas no Google Assistente, que mostra uma lista das próximas aulas:

4. Adicionar notificações push

Como outra opção para interagir com os usuários fora da sua ação, você pode chamar a API Actions para enviar notificações push aos usuários. Ao contrário das atualizações diárias, essas notificações não são programadas automaticamente pelo Google Assistente. Assim, você pode enviá-las quando quiser.

Termos-chave:

• API Actions:é uma API REST do Google Assistente usada para enviar notificações aos usuários. Com a permissão do usuário, é possível enviar uma solicitação POST ao endpoint da API Actions, que envia uma notificação push usando o conteúdo da solicitação.

Nesta etapa, você vai aprender a implementar notificações push na sua ação adicionando uma nova intent Aula cancelada e enviando notificações aos usuários sobre o cancelamento de uma aula. Você também vai configurar os três componentes a seguir, necessários para enviar notificações:

• Conta da API Actions: você envia notificações ao usuário enviando uma solicitação POST a uma API. Portanto, é necessário configurar uma conta de serviço e credenciais para interagir com essa API.
• Assistente de permissão: você precisa da permissão do usuário para acessar o ID necessário para enviar notificações push. Neste exemplo, você vai usar uma função de biblioteca de cliente para chamar o auxiliar de permissão e solicitar esse ID.

Termos-chave:

• Assistente:um assistente é uma intent que, quando atendida, permite que o Google Assistente assuma temporariamente a conversa para pedir informações específicas ao usuário. Se a solicitação for bem-sucedida, o auxiliar vai retornar essas informações para você.

• Armazenamento: para enviar notificações push a um usuário fora de uma conversa, é necessário armazenar os IDs de usuário em algum lugar que possa ser recuperado a qualquer momento. Neste exemplo, você vai configurar um banco de dados do Firestore para armazenar informações de cada usuário.

Depois de seguir estas instruções, adicione o seguinte diálogo à conversa da ação:

Como isso vai engajar os usuários?

Os usuários de smartphones provavelmente conhecem as notificações push, que fornecem informações e atualizações específicas do app. As notificações push são uma maneira flexível de acessar usuários em dispositivos móveis fora do Google Assistente, desde que eles tenham um bom motivo para ativá-las. Com atualizações diárias, os usuários já sabem que vão receber notificações todos os dias. Com as notificações push, no entanto, os usuários não sabem se estão ativando o recebimento de notificações ocasionais ou se vão receber várias notificações por dia.

As notificações push podem ser uma ferramenta de engajamento útil, mas não precisam ser incorporadas em todas as ações. Considere estas dicas ao decidir se quer adicionar notificações push a uma ação:

• Planeje alguns exemplos de programações para suas notificações push. Se você planeja enviar apenas uma notificação push por dia, considere usar atualizações diárias.
• Verifique se as notificações push fornecem informações úteis sempre que são recebidas. As notificações também podem ter um link direto para uma das intents da sua ação. Por isso, verifique se a intent é útil e relevante.
• Seja explícito ao pedir que um usuário se inscreva para receber notificações push. Eles precisam entender o que esperar de cada notificação push e ter uma ideia da frequência com que elas são enviadas.

Dica:confira nossas práticas recomendadas para criar notificações úteis. O logotipo e a prioridade da notificação são predeterminados para o Google Assistente, mas os mesmos princípios se aplicam ao decidir se você quer adicionar uma notificação push à sua ação.

Ativar a API Actions

1. Abra o console do Google Cloud e selecione o nome do projeto do Actions no menu suspenso.

2. No menu de navegação (☰), acesse APIs e serviços > Biblioteca.
3. Pesquise a API Actions e clique em Ativar.

Criar uma conta de serviço

A API Actions exige autenticação. Por isso, você precisa criar uma conta de serviço para enviar solicitações. Siga estas etapas para criar e instalar uma chave de conta de serviço para a API Actions:

1. No menu de navegação do console do Google Cloud (☰), acesse APIs e serviços > Credenciais.
2. Clique em Criar credenciais > Chave da conta de serviço.
3. No menu suspenso Conta de serviço, selecione Nova conta de serviço.
4. Preencha as seguintes informações:

• Nome da conta de serviço: service-account
• Papel: Projeto > Proprietário
• ID da conta de serviço : service-account (sempre seguido por @<project_id>.iam.gserviceaccount.com)
• Tipo de chave: JSON

5. Clique em Criar.
6. Mova o arquivo JSON baixado para o diretório /user-engagement-codelab/start/functions/ do seu projeto.
7. Renomeie o arquivo JSON para service-account.json.

Ativar o Firestore

Para enviar notificações fora da conversa, você precisa de uma maneira de armazenar IDs de usuários que podem ser referenciados no seu código de notificação. Neste exemplo, usamos um banco de dados do Firestore para armazenar os IDs dos usuários inscritos.

Siga estas etapas para criar um banco de dados do Firestore para sua ação:

1. No console do Firebase, selecione o nome do projeto do Actions.
2. Na navegação à esquerda, acesse Desenvolver > Banco de dados e clique em Criar banco de dados.
3. Selecione Iniciar no modo de teste.
4. Clique em Ativar.

Dica:estamos usando regras de segurança do modo de teste apenas para fins de teste. Você precisa ter regras de segurança de dados mais robustas antes que sua ação seja publicada em produção. Saiba mais sobre as regras de segurança do Cloud Firestore na documentação do Firestore.

Configurar o Dialogflow

Siga estas etapas no console do Dialogflow para criar o fluxo de ativação das notificações push:

Pedir que o usuário se inscreva

1. Configure uma nova intent para processar o pedido do usuário de se inscrever nas notificações push de aulas canceladas. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Setup Push Notifications.
3. Na seção Frases de treinamento, adicione as seguintes expressões do usuário:

• Subscribe to notifications
• Send notification
• Notify me
• Send class notifications
• Cancelled notifications

4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Processar a decisão do usuário

1. Configure uma nova intent para processar a resposta do usuário à solicitação de inscrição em notificações push. Clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Confirm Push Notifications.
3. Na seção Eventos, adicione actions_intent_PERMISSION. Esse evento do Dialogflow será acionado quando o usuário concluir o fluxo de inscrição nas notificações push, mesmo que ele tenha se inscrito ou não.
4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Processar a notificação push

É possível vincular suas notificações push a uma intent específica para que os usuários que tocarem na notificação sejam direcionados diretamente a essa intent na sua ação. Neste exemplo, adicione uma nova intent para notificações push que forneça detalhes sobre as aulas canceladas.

Siga estas etapas para adicionar uma intent que será acionada quando o usuário tocar em uma notificação push:

1. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Class Canceled.
3. Na seção Frases de treinamento, adicione Cancelations como uma expressão do usuário.
4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Enviar notificações de teste no meio da conversa

Em produção, você precisa ter um script separado do código de atendimento da ação que envia notificações push. Para este exemplo, crie uma intent que possa ser invocada para enviar uma notificação push enquanto você fala com sua ação. Essa intent é apenas para fins de depuração. Na prática, as notificações push não devem ser processadas pelo fulfillment nem acionadas como parte da conversa da sua ação.

Siga estas etapas para criar uma intent de teste de notificações push:

1. Para fins de teste e depuração, configure uma nova intent que permita enviar notificações push para usuários inscritos. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
2. Nomeie essa nova intent como Test Notification.
3. Na seção Frases de treinamento, adicione Test notification como uma expressão do usuário.
4. Na seção Fulfillment, clique na opção Ativar chamada de webhook para esta intent.
5. Clique em Salvar na parte de cima da página.

Ativar notificações push

Siga estas etapas para ativar as notificações push da intent Class Canceled:

1. No console do Dialogflow, acesse Integrações na barra de navegação.
2. No card Google Assistente, clique em Configurações de integração.
3. Adicione Aula cancelada como um intent de invocação implícita. Essa etapa é necessária para que o Dialogflow reconheça que os usuários podem iniciar a conversa com a intent Aula cancelada (tocando em uma notificação push).
4. Clique em Fechar.

5. No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
6. Clique em Aula cancelada na lista Ações.
7. Na seção Engajamento do usuário, ative a opção Gostaria de enviar notificações push?.
8. Defina um título do conteúdo descritivo que descreva a notificação push. O contexto será "Tudo bem se eu enviar notificações push sobre ?", então verifique se o título é descritivo e soa correto quando falado em voz alta. Neste exemplo, defina o Título do conteúdo como class cancelations.
9. Clique em Salvar na parte de cima da página.

Implementar o atendimento

Para implementar o fulfillment no seu webhook, siga estas etapas:

Carregar dependências

No arquivo index.js, atualize a função require() para adicionar o pacote UpdatePermission do pacote actions-on-google. Assim, suas importações vão ficar assim:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
  UpdatePermission,
} = require('actions-on-google');

Atualizar ícones de sugestão

No arquivo index.js, adicione uma entrada NOTIFICATIONS à lista de títulos de ícones de sugestão para que sua definição Suggestion fique assim:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
  NOTIFICATIONS: 'Get notifications',
};

Configurar novas importações

Para se conectar ao banco de dados do Firestore, adicione o pacote firebase-admin e constantes para os campos armazenados no banco de dados. Além disso, importe os pacotes google-auth-library e request para processar a autenticação e as solicitações da API Actions.

No arquivo index.js, adicione o seguinte código às suas importações:

index.js

// Firebase admin import
const admin = require('firebase-admin');

// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();

// Firestore constants
const FirestoreNames = {
 INTENT: 'intent',
 USER_ID: 'userId',
 USERS: 'users',
};

// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');

Oferecer a configuração de notificações de cancelamento de turmas

No arquivo index.js, substitua o seguinte código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

com este código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
    };
  };
});

Adicionar atendimento para novas intents

Quando o usuário disser que quer se inscrever para receber notificações push, chame o auxiliar UpdatePermission para pedir permissão. Se isso funcionar, o argumento PERMISSION será adicionado aos argumentos do objeto conv, que você pode verificar para mudar o assunto da conversa.

Depois de ter a permissão do usuário, extraia o ID dele dos argumentos do objeto conv e salve no banco de dados. Mais tarde, você vai enviar esse ID de usuário para a API Actions, que é como o Google Assistente determina quem recebe a notificação.

Por fim, adicione o fulfillment para a intent Class Canceled que é acionada ao tocar na notificação push. Neste exemplo, sua resposta é uma string de marcador de posição. No entanto, em uma versão pronta para produção dessa ação, o script de notificação forneceria informações mais dinâmicas sobre qual aula foi cancelada.

No arquivo index.js, adicione o seguinte código:

index.js

// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
 conv.ask('Update permission for setting up push notifications');
 conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});

// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
 if (conv.arguments.get('PERMISSION')) {
   let userId = conv.arguments.get('UPDATES_USER_ID');
   if (!userId) {
     userId = conv.request.conversation.conversationId;
   }
   // Add the current conversation ID and the notification's
   // target intent to the Firestore database.
   return db.collection(FirestoreNames.USERS)
   .add({
     [FirestoreNames.INTENT]: 'Class Canceled',
     [FirestoreNames.USER_ID]: userId,
   })
   .then(() => {
     conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
     'Can I help you with anything else?');
   });
 } else {
   conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
     'Can I help you with anything else?');
 }
 if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
  }
});

// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
 conv.ask('Classname at classtime has been canceled.');
});

Adicionar notificações de teste

Para enviar uma notificação push a um usuário, envie uma solicitação POST à API Actions com o ID do usuário, o título da notificação e a intent de destino. Neste exemplo, acionar a intent "Notificação de teste" vai iterar pelo banco de dados do Firestore e enviar notificações push para todos os usuários inscritos.

Neste exemplo, você está incluindo o código que envia a notificação push no seu webhook fulfillment e acionando esse código ao invocar uma intent de teste na sua conversa. Nas ações que você pretende publicar, o código de notificação push precisa estar em um script separado do fulfillment.

No arquivo index.js, adicione o seguinte código:

index.js

// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
 // Use the Actions API to send a Google Assistant push notification.
 let client = auth.fromJSON(require('./service-account.json'));
 client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
 let notification = {
   userNotification: {
     title: 'Test Notification from Action Gym',
   },
   target: {},
 };
 client.authorize((err, tokens) => {
   if (err) {
     throw new Error(`Auth error: ${err}`);
   }
   // Iterate through Firestore and send push notifications to every user
   // who's currently opted in to canceled class notifications.
   db.collection(FirestoreNames.USERS)
       .where(FirestoreNames.INTENT, '==', 'Class Canceled')
       .get()
       .then((querySnapshot) => {
         querySnapshot.forEach((user) => {
           notification.target = {
             userId: user.get(FirestoreNames.USER_ID),
             intent: user.get(FirestoreNames.INTENT),
           };
           request.post('https://actions.googleapis.com/v2/conversations:send', {
             'auth': {
               'bearer': tokens.access_token,
             },
             'json': true,
             'body': {'customPushMessage': notification, 'isInSandbox': true},
           }, (err, httpResponse, body) => {
             if (err) {
               throw new Error(`API request error: ${err}`);
             }
             console.log(`${httpResponse.statusCode}: ` +
               `${httpResponse.statusMessage}`);
             console.log(JSON.stringify(body));
           });
         });
       })
       .catch((error) => {
         throw new Error(`Firestore query error: ${error}`);
       });
 });
 conv.ask('A notification has been sent to all subscribed users.');
});

Testar as notificações push

No terminal, execute o seguinte comando para implantar o código atualizado do webhook no Firebase:

firebase deploy

Dica:você pode encontrar as informações mais recentes sobre como usar o simulador do Actions no guia do simulador do Actions. Consulte esse material caso tenha alguma dificuldade nas etapas abaixo.

Para testar as notificações no simulador do Actions, siga estas etapas:

1. No console do Actions, acesse a guia Testar.
2. Digite Talk to my test app no campo Entrada e pressione Enter.
3. Digite Learn about classes e pressione Enter.
4. Digite Get notifications e pressione Enter.
5. Se você ainda não tiver concedido à sua ação permissão para enviar notificações push, digite yes e pressione Enter.
6. Digite yes e pressione Enter. Sua Conta do Google agora está inscrita nas notificações push dessa ação.

Se você receber um erro ao tentar se inscrever nas notificações push na etapa 4, volte para Build > Actions > Class Canceled e desative as notificações push. Clique em Save, ative as notificações push novamente, clique em Save de novo e tente testar no simulador outra vez.

7. Digite no e pressione Enter para sair.
8. Digite Talk to my test app e pressione "Enter" para iniciar uma conversa.
9. Digite Test notification e pressione Enter.

Em alguns minutos, você vai receber uma notificação push do Google Assistente no seu dispositivo móvel com a mensagem "Notificação de teste da Action Gym". Ao tocar nessa notificação, você vai acessar o link direto do intent Aula cancelada da sua ação.

Se você tiver problemas para receber a notificação, siga as instruções de teste no seu smartphone. Abra o Google Assistente no smartphone e diga "talk to my test app". Depois, siga as instruções de teste acima a partir da etapa 3.

5. Criar um link do Google Assistente

Até agora, discutimos recursos de engajamento que você pode implementar para manter os usuários voltando à sua ação, mas isso depende de ter usuários que descobrem e usam sua ação.

Você pode criar um link do Google Assistente que direciona os usuários em dispositivos móveis diretamente para sua Ação no Google Assistente. Como um link do Google Assistente é um hiperlink padrão, você pode adicioná-lo a um site ou a qualquer material de marketing na Web, como um blog ou uma postagem em redes sociais.

Nesta etapa, você vai aprender o que é um link do Google Assistente, como criar um para a intent de boas-vindas da sua ação e como adicioná-lo a um site simples para teste.

Como isso vai engajar os usuários?

Atrair usuários para sua ação pela primeira vez pode ser difícil, principalmente quando eles precisam invocar explicitamente a ação no Google Assistente. Um link do Google Assistente reduz esse atrito ao dar aos usuários um link direto para sua ação. Quando um usuário segue seu link do Google Assistente em um dispositivo compatível, ele é direcionado diretamente para sua ação. Quando um usuário abre seu link em um dispositivo não móvel ou em qualquer outro dispositivo que não seja compatível com o Google Assistente, ele ainda é direcionado à página do diretório de ações (se ela tiver sido publicada) para que o link possa continuar promovendo sua ação para esses usuários.

Os links do Google Assistente podem ser uma ferramenta de engajamento útil. Por isso, crie um se você planeja anunciar sua ação no site ou nas redes sociais. Confira as dicas a seguir antes de criar e distribuir um link do Google Assistente:

• Os links do Google Assistente só funcionam depois que sua ação é publicada. Enquanto o projeto estiver em estado de rascunho, o link só vai funcionar nos seus dispositivos. Qualquer outra pessoa será direcionada para uma página 404 no diretório "Ações".
• Você pode permitir que os usuários testem um link do Google Assistente antes da publicação lançando sua ação em um ambiente Alfa ou Beta. Somente os usuários que participarem do teste Alfa ou Beta poderão testar o link do Google Assistente.
• Verifique se a intent de destino do link do Google Assistente causa uma boa primeira impressão nos novos usuários. A intent de boas-vindas é o destino padrão de um link do Google Assistente porque ela já faz um bom trabalho de apresentação da sua ação.

Dica:neste exemplo, você vai criar apenas um link simples do Google Assistente que envia os usuários para a intent de boas-vindas, mas há muito mais que você pode fazer para personalizar um link do Google Assistente. Você pode anexar parâmetros de URL ao seu link que enviam os usuários para intents específicas e até mesmo incluir parâmetros de intent para personalizar a resposta que os usuários recebem quando seguem seu link. Embora não abordemos essas opções avançadas neste codelab, você pode saber mais na documentação para desenvolvedores.

Ativar links do Google Assistente

Siga estas etapas para criar um link do Google Assistente para a intent de boas-vindas:

1. No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
2. Clique em actions.intent.MAIN na lista Ações.
3. Na seção Links, ative a opção Você quer ativar um URL para esta ação?.
4. Defina um título do link descritivo que descreva sua ação. Crie um título simples com um verbo e um substantivo que descreva o que o usuário pode fazer com sua ação. Neste exemplo, defina o Título do link como learn about Action Gym.
5. Copie o snippet HTML da parte de baixo desta página e salve para mais tarde.
6. Clique em Salvar na parte de cima da página.

Implantar um site de teste

Para testar seu link do Google Assistente, use as ferramentas do Firebase para implantar um site de teste junto com o fulfillment. Já criamos um site de teste simples para este exemplo. Basta adicionar o link do Google Assistente.

Acesse o diretório /user-engagement-codelab-nodejs/start/public/ do fulfillment e abra o arquivo index.html em um editor de texto.

No arquivo index.html, cole o snippet HTML do link do Google Assistente no elemento body. O arquivo vai ficar parecido com o snippet abaixo:

index.html

<body>
    <p>
     <a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
     </a>
    </p>
</body>

Testar o link do Google Assistente

No terminal, execute o seguinte comando para implantar o site de teste no Firebase:

firebase deploy

Quando o comando de implantação terminar de ser executado, anote o URL de hospedagem na saída.

Acesse este URL no navegador da Web do seu dispositivo móvel. O link do Google Assistente vai aparecer no site de teste. Ao clicar nesse link no seu dispositivo móvel, você vai acessar a intent de boas-vindas da sua ação no Google Assistente.

Você também pode acessar o URL do Hosting em um navegador para computador, que vai direcionar você a uma página 404 no diretório do Google Assistente, já que sua ação não foi publicada.

6. Próximas etapas

Parabéns!

Agora você aprendeu sobre a importância do engajamento do usuário ao desenvolver uma ação, quais recursos de engajamento do usuário estão disponíveis na plataforma e como adicionar cada recurso a uma ação.

Recursos de aprendizado adicionais

Confira estes recursos para saber mais sobre o engajamento do usuário com sua ação:

• Engajamento do usuário e Documentos de links do Google Assistente: a documentação oficial do Actions on Google sobre os recursos discutidos neste codelab e o engajamento do usuário em geral.
• Análise de retenção de usuários: documentação do recurso de análise de dados no console do Actions que mostra a retenção de usuários da sua ação publicada.
• Diretrizes de design de conversa: práticas recomendadas e orientações sobre como criar recursos de engajamento do usuário.
• Repositório do Actions on Google do GitHub: exemplos de códigos e bibliotecas.
• r/GoogleAssistantDev: a comunidade oficial do Reddit para desenvolvedores que trabalham com o Google Assistente.

Siga nosso perfil do Twitter @ActionsOnGoogle para ficar por dentro dos nossos comunicados mais recentes e envie um tuíte para #AoGDevs contando o que você criou.

Pesquisa de feedback

Antes de sair, preencha este formulário para nos contar o que você achou.