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

1. Visão geral

Aviso: as ações de conversa serão suspensas em 13 de junho de 2023. Para mais informações, consulte Desativação de 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. Os usuários interagem com o Google Assistente em conversas para realizar tarefas, como comprar produtos ou reservar uma viagem. Para ver uma lista completa das possibilidades, 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 entre o usuário e o serviço de terceiros.

Este é um módulo de codelab avançado, destinado a leitores que já têm alguma experiência na criação de ações para o 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 orientarão você por 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 eficiência dela para atrair os usuários de volta após a primeira interação. Para facilitar esse processo, implemente vários recursos na sua ação para que os usuários voltem à conversa.

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

O que você vai criar

Você melhorará um recurso que já foi criado ativando-o para:

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

O que você vai aprender

• O que é o engajamento do usuário e por que isso é importante para o sucesso de uma ação
• Como modificar uma ação para aumentar o engajamento dos usuários
• 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

Pré-requisitos

Você precisa ter as seguintes ferramentas:

• Um ambiente de desenvolvimento integrado/editor de texto de sua escolha, como WebStorm, Atom ou Sublime
• Um terminal para executar comandos de 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 Assistente (é preciso fazer login no Assistente com a mesma Conta do Google que você 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

Esta seção mostra 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 pelo número de usuários que retornam à sua ação, que é uma métrica usada para determinar se deve promover uma ação. O alto engajamento do usuário tem dois componentes de uma ação: informações úteis que ele verá mais tarde e formas de recuperar a ação quando for mais provável que ele tenha essas informações para recuperá-las.

Entender o exemplo

O exemplo para este 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 rotativas a cada dia. Uma ação informativa como essa é uma boa candidata para todos os recursos de engajamento do usuário porque a lista de classes rotativa fornece informações úteis diferentes a cada dia.

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

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 mudará muito.

Fazer o download dos arquivos de base

Execute o seguinte comando para clonar o repositório do GitHub para o 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 de projeto, como engagement-codelab.
4. Clique em Criar projeto.
5. Em vez de escolher uma categoria, role para baixo até a seção Mais opções e clique no card Conversa.
6. Clique em Criar sua ação para expandir as opções e selecione Adicionar ações.
7. Clique em Adicionar sua primeira ação.
8. Na caixa de diálogo Create Action, selecione Custom Intent e clique em Build para iniciar o console do Dialogflow.
9. Na página de criação do agente do Console do Dialogflow, clique em Criar.
10. Clique no ícone de engrenagem na navegação à esquerda.
11. Clique em Export and Import e em Restore from Zip.
12. Faça upload do arquivo agent.zip no diretório /user-engagement-codelab-nodejs/start/ que você salvou localmente.
13. Digite RESTORE e clique em Restaurar.
14. Clique em Concluir.

Implante 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 do Action no Console do Actions em Visão geral > (ícone de engrenagem) > Configurações do projeto.

npm install

firebase deploy

Se você vir uma mensagem de erro que diz "Ocorreu um erro inesperado na CLI", execute o comando firebase deploy novamente.

Após alguns minutos, você deve ver "Implantação concluída!", o que indica que você implantou seu webhook no Firebase.

Recuperar o URL de implantação

Forneça ao Dialogflow o URL para a 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 uma solicitação para "Escolher configurações de compartilhamento de dados" poderá ignorar esta opção clicando em Fazer isso mais tarde.
4. Na guia Painel, você verá uma entrada para "fulfillment" com um URL em Acionador. 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 fazer isso, siga estas etapas:

1. Abra o Console do Dialogflow (é possível fechar o Console do Firebase se quiser).
2. Clique em Fulfillment na navegação à esquerda.
3. Ative o Webhook.
4. Cole o URL que você copiou do painel do Firebase se ele ainda não tiver aparecido.
5. Clique em Salvar.

Verificar se o projeto está configurado corretamente

Os usuários precisam ser capazes de invocar sua ação para consultar informações sobre a ação necessária, incluindo uma resposta de texto codificada com horário de funcionamento e uma resposta de texto que liste a programação da aula 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 a ação no simulador do Actions, faça o seguinte:

1. No painel de navegação à esquerda do console do Dialogflow, clique em Integrations > Google Assistant.
2. Verifique se a opção Visualização automática está ativada e clique em Testar para atualizar o projeto do Actions.
3. O simulador do Actions carrega seu projeto. Para testar a ação, digite Talk to my test app no campo Entrada e pressione Enter.
4. Você verá uma resposta de boas-vindas ao Action Gym. Siga as instruções para continuar a conversa e verificar se o fulfillment tem uma resposta para cada entrada.

Se você não receber essas respostas, é provável que haja um problema com a configuração do Firebase. Nesse caso, tente repetir as etapas na seção "Implantar seu fulfillment".

3. Adicionar assinaturas de atualização diária

Uma maneira comum de envolver os usuários é oferecer informações quando for mais útil. Para isso, os usuários têm a opção de se inscrever em atualizações diárias de uma intent, o que envia uma notificação do Google Assistente que é vinculada diretamente à conclusão dessa intent.

Nesta etapa, você aprenderá sobre as assinaturas de atualização diária e adicioná-las à intent Lista de classes do Action. Depois de seguir essas instruções, a conversa da sua ação ficará como no diagrama a seguir:

Como isso envolverá os usuários?

Os usuários de smartphones provavelmente estão familiarizados com as notificações push, que fornecem informações e atualizações específicas do aplicativo. As assinaturas de atualização diária são uma maneira simples de acessar os usuários em dispositivos móveis fora do Google Assistente, desde que a intent de envio de atualizações continue a oferecer valor ao usuário diariamente.

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

• Garanta que as atualizações diárias façam com que o usuário veja informações úteis e diferentes todos os dias. Se tocar em uma atualização diária resultar na mesma solicitação todas as vezes, o usuário provavelmente cancelará a inscrição após alguns dias.
• A caixa de diálogo precisa fazer sentido para o usuário se ele for direto para a intenção da atualização diária. O usuário não começará necessariamente desde o início da conversa, então não deve ter muito contexto.
• Mostre ao usuário os benefícios da ação antes de solicitar a inscrição nas atualizações diárias. Seu usuário deve estar pensando: "Eu quero esse conteúdo todos os dias" quando eles têm a opção de se inscrever.
• Não sobrecarregue o usuário com sugestões repetidas de inscrição. Ofereça uma assinatura de atualização diária logo depois de mostrar ao usuário o que ele assinou e evite incentivá-lo em outro lugar.
• Mantenha a conversa curta depois que a intent de atualização for acionada. A maioria das atualizações diárias precisa consistir em apenas uma resposta e ser fechada sem exigir a entrada do usuário.

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

Ativar as atualizações diárias

É possível adicionar assinaturas de atualização diária à intent de boas-vindas que coloca o usuário no início da conversa ou a uma intent mais específica para vinculá-las a alguma parte da conversa. Neste codelab, a intent Lista de classes faz mais sentido porque a caixa de diálogo muda todos os dias, e os usuários podem achar útil lembrar quais classes estão disponíveis.

Siga estas etapas para ativar as atualizações diárias da intent Class List:

1. No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
2. Clique em Class List na lista Actions.
3. Na seção Engajamento do usuário, alterne a opção Você quer oferecer atualizações diárias para os 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 que eu mande seu dia`? Então, veja se o título é descritivo e os sons estão corretos em voz alta. Para este exemplo, defina o Título do conteúdo como list of upcoming Action Gym classes.
5. Clique em Salvar na parte superior da página.

Configurar o Dialogflow

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

Solicitar que o usuário se inscreva no canal

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

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

4. Na seção Fulfillment, ative a opção Enable webhook call for this intent.
5. Clique em Salvar na parte superior 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 assinatura de atualizações diárias. Clique no botão + ao lado de Intents no menu de navegação à esquerda para criar uma nova intent.
2. Nomeie essa nova intent como Confirm Updates.
3. Na seção Eventos, adicione actions_intent_REGISTER_UPDATE. O evento do Dialogflow será acionado pelo usuário que concluiu o fluxo de assinatura de atualização diária, mesmo que ele não tenha inscrito ainda.
4. Na seção Fulfillment, ative a opção Enable webhook call for this intent.
5. Clique em Salvar na parte superior da página.

Implementar o fulfillment

Para implementar o fulfillment no 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 ficarão 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 do ícone de sugestão para que sua definição de Suggestion fique assim:

index.js

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

Adicionar fulfillment a novas intents

Quando o usuário disser que quer se inscrever, inicie o fluxo de assinatura de atualizações diárias chamando o auxiliar do RegisterUpdate com a intent de destino da atualização (Lista de classes) e o tipo (DAILY). Depois que o fluxo de assinatura é concluído, o Google Assistente aciona o evento actions_intent_REGISTER_UPDATE com um argumento status que descreve se a assinatura foi concluída. Ofereça solicitações de acompanhamento para o usuário que mudam de acordo com o 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 solicitações alternativas para o usuário

A resposta da lista de classes vai oferecer a assinatura de atualização diária no final, mas isso causa um problema. Como essa mesma resposta será acionada quando o usuário tocar na notificação de atualização diária, ele receberá uma solicitação para assinar as atualizações diárias, mesmo que sejam de uma notificação. Como você pode evitar que o usuário pense que precisa se inscrever novamente?

Felizmente, os argumentos do objeto conv incluem informações sobre onde o usuário iniciou a conversa. Você pode verificar os argumentos conv para ver se eles contêm uma seção UPDATES, que indica que o usuário iniciou a conversa a partir de uma notificação de atualização diária, e mudar a resposta adequadamente. Também é possível usar essa ramificação de conversa para fechar a caixa de diálogo imediatamente após fornecer a lista de classes, 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]));
  }
});

por:

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 prompt personalizado no simulador do Actions, siga estas etapas:

1. No Console do Actions, acesse Testar.
2. Digite Talk to my test app no campo Entrada e pressione Enter.
3. Digite Learn about classes e pressione Enter. Agora a resposta do Action deve oferecer o envio de lembretes diários.
4. Digite Send daily reminders e pressione Enter.
5. Digite o horário em que você quer ver a atualização e pressione Enter. Para fins de teste, tente responder com três a cinco minutos após a hora atual.

Se você receber uma mensagem de 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 novamente e tente testar no Simulator novamente.

No seu dispositivo móvel, você receberá uma notificação do Assistente sobre a hora especificada para as atualizações. Essa notificação pode levar alguns minutos para aparecer. Toque na notificação para que ela tenha um link direto para a intent Lista de classes no Google Assistente, que exibe uma lista das próximas turmas:

4. Adicionar notificações push

Como outra opção para envolver 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, e você pode enviá-las como quiser.

Termos-chave:

• API Actions: a API Actions é uma API REST do 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 para ele usando o conteúdo da solicitação.

Nesta etapa, você aprenderá a implementar notificações push na sua ação adicionando uma nova intent Class Canceled e enviando notificações aos usuários para notificá-los sobre o cancelamento da classe. Você também configurará estes três componentes 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. Por isso, você precisa configurar uma conta de serviço e credenciais para interagir com essa API.
• Assistente de permissões: você precisa da permissão do usuário para acessar o ID do usuário necessário para enviar notificações push. Neste exemplo, você usará uma função da biblioteca de cliente para chamar o auxiliar de permissões e solicitar esse ID.

Termos-chave:

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

• Armazenamento: para enviar notificações push a um usuário fora de uma conversa, você precisa armazenar os IDs de usuários em algum lugar que possa ser retirado à vontade. Neste exemplo, você configurará um banco de dados Firestore para armazenar informações para cada usuário.

Depois de seguir estas instruções, você adicionará a seguinte caixa de diálogo à sua conversa do Action:

Como isso envolverá os usuários?

Os usuários de smartphones provavelmente estão familiarizados com as notificações push, que fornecem informações e atualizações específicas do aplicativo. 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 as atualizações diárias, os usuários já sabem que serão notificados diariamente. No entanto, com as notificações push, os usuários não sabem se ativaram o recebimento de notificações pouco frequentes ou serão incomodados com várias notificações por dia.

As notificações push podem ser uma ferramenta de engajamento útil, mas não devem ser necessariamente incorporadas a 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, use as atualizações diárias.
• Certifique-se de que suas notificações push mostrarão informações úteis sempre que forem recebidas. As notificações também podem incluir um link direto para uma das intents da sua ação. Por isso, confira se a intent é útil e relevante.
• Seja explícito ao pedir que um usuário se inscreva nas notificações push. Ele precisa entender o que esperar em cada notificação push e ter uma ideia da frequência de envio das notificações.

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 esses mesmos princípios se aplicam quando você decide se 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 na lista suspensa.

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

Criar uma conta de serviço

A API Actions exige autenticação. Portanto, 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 & 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: proprietário do projeto
• 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 salvo para o diretório /user-engagement-codelab/start/functions/.
7. Renomeie o arquivo JSON como service-account.json.

Ativar o Firestore

Para enviar notificações fora da conversa, você precisa armazenar os IDs de usuário que podem ser referenciados no código de notificações. Neste exemplo, estamos usando um banco de dados Firestore para armazenar os IDs dos usuários inscritos.

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

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

Dica:no momento, estamos usando regras de segurança do modo de teste apenas para fins de teste. Você precisaria de regras de segurança de dados mais rigorosas em vigor antes que sua ação fosse publicada na 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 de notificações push:

Solicitar que o usuário se inscreva no canal

1. Configure uma nova intent para processar a solicitação de inscrição de usuários em notificações push para turmas canceladas. No Console do Dialogflow, clique no botão + ao lado de Intents no menu de navegação à esquerda para criar uma intent nova.
2. Nomeie essa nova intent como Setup Push Notifications.
3. Na seção Frases de treinamento, adicione as seguintes expressões de usuário:

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

4. Na seção Fulfillment, ative a opção Enable webhook call for this intent.
5. Clique em Salvar na parte superior 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 assinatura de notificações push. Clique no botão + ao lado de Intents no menu de navegação à esquerda para criar uma nova intent.
2. Nomeie essa nova intent como Confirm Push Notifications.
3. Na seção Eventos, adicione actions_intent_PERMISSION. O evento do Dialogflow será acionado pelo usuário que concluiu o fluxo de inscrição das notificações push, independentemente de ele ter concluído a assinatura.
4. Na seção Fulfillment, ative a opção Enable webhook call for this intent.
5. Clique em Salvar na parte superior 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 toquem nelas tenham links diretos para essa intent na sua ação. Neste exemplo, adicione uma nova intent para notificações push que forneça detalhes sobre as classes canceladas.

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

1. No Console do Dialogflow, clique no botão + ao lado de Intents no menu de navegação à esquerda para criar uma intent nova.
2. Nomeie essa nova intent como Class Canceled.
3. Na seção Frases de treinamento, adicione Cancelations como uma expressão de usuário.
4. Na seção Fulfillment, ative a opção Enable webhook call for this intent.
5. Clique em Salvar na parte superior da página.

Enviar notificações de teste durante uma conversa

Na produção, você precisa ter um script diferente do código de fulfillment da ação que envie notificações push. Para este exemplo, crie uma intent que você possa invocar para enviar uma notificação push ao falar com a 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 de outra forma como parte da conversa da sua ação.

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

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

Ativar notificações push

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

1. No Console do Dialogflow, acesse Integrações na barra de navegação.
2. No card do Google Assistente, clique em Configurações de integração.
3. Adicione Class Canceled como uma intent Implicit invocation. Essa etapa é necessária para que o Dialogflow reconheça que os usuários podem iniciar a conversa com a intent Class Canceled ao tocar 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 Class Canceled na lista Actions.
7. Na seção Engajamento do usuário, alterne a opção Você quer 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 para ?" então, verifique se seu título é descritivo e os sons estão corretos em voz alta. Para este exemplo, defina o Título do conteúdo como class cancelations.
9. Clique em Salvar na parte superior da página.

Implementar o fulfillment

Para implementar o fulfillment no 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 ficarão 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 do ícone de sugestão para que sua definição de 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 seu banco de dados do Firestore, adicione o pacote firebase-admin e inclua constantes nos campos armazenados no banco de dados. Além disso, importe os pacotes google-auth-library e request para gerenciar a autenticação e as solicitações para a 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');

Oferta para configurar 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]));
    };
  };
});

por:

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 fulfillment a novas intents

Quando o usuário disser que quer se inscrever para receber notificações push, chame o auxiliar UpdatePermission para solicitar permissão. Se isso for bem-sucedido, o argumento PERMISSION será adicionado aos argumentos do objeto conv, que você pode marcar para alternar a conversa.

Depois de conseguir a permissão do usuário, use o ID do usuário do argumento do objeto conv e salve-o no seu banco de dados. Mais tarde, você enviará esse ID de usuário para a API Actions, que é a forma como o Google Assistente determina quem recebe a notificação.

Por fim, para adicionar o fulfillment da intent Class Canceled, toque na notificação push. Nesse exemplo, a resposta é uma string de marcador, mas em uma versão pronta para produção dessa ação, o script de notificação mostraria informações mais dinâmicas sobre qual classe 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 para 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, o acionamento da intent de notificação de teste fará a iteração no banco de dados do Firestore e enviará notificações push a todos os usuários que se inscreveram para receber notificações.

Lembre-se de que, neste exemplo, você está incluindo o código que envia a notificação push no fulfillment do webhook e aciona esse código invocando um intent de teste na conversa. No Actions que você pretende publicar, o código de notificação push precisa existir 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 suas 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 Teste.
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 concedeu sua permissão de ação para enviar notificações push, digite yes e pressione Enter.
6. Digite yes e pressione Enter. Sua Conta do Google deve estar inscrita nas notificações push dessa ação.

Se você receber um erro ao tentar se inscrever para receber 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 e tente novamente no Simulator.

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

Em alguns minutos, você receberá uma notificação push de teste do Assistente no seu dispositivo móvel. Ao tocar nessa notificação, você terá um link direto para a intent Class Canceled da sua ação.

Se estiver com problemas para receber a notificação, siga as instruções do teste no celular. Abra o Google Assistente no smartphone e diga "quot;talk to my test app"" e siga as instruções de teste acima da etapa 3.

5. Criar um link do Assistente

Até agora, falamos sobre os recursos de engajamento que podem ser implementados para fazer com que os usuários continuem voltando para sua ação, mas eles são baseados em usuários que descobrem e usam sua ação.

Você pode criar um link do Assistente que vinculará os usuários em dispositivos móveis diretamente ao seu ação no Assistente. Como o link do Assistente é um hiperlink padrão, você pode adicioná-lo a um site ou a qualquer material de marketing da Web, como um blog ou uma postagem de mídia social.

Nesta etapa, você aprenderá o que é um link do Assistente, como criá-lo para a intent de boas-vindas do Action e como adicioná-lo a um site simples para teste.

Como isso envolverá os usuários?

Atraia usuários para sua ação pela primeira vez pode ser um desafio, principalmente quando eles precisam invocar explicitamente sua ação no Google Assistente. Um link do Google Assistente diminui esse atrito dando aos usuários um link direto para sua ação. Quando um usuário segue seu link do Assistente em um dispositivo com Google Assistente, ele é direcionado para sua ação. Quando um usuário abrir o link em um dispositivo não móvel ou em qualquer outro dispositivo que não seja compatível com o Google Assistente, ele será direcionado para a lista do Diretório de ações, caso tenha sido publicado, para que o link ainda possa promover sua ação a esses usuários.

Os links do Assistente podem ser uma ferramenta útil de engajamento, portanto, crie um se quiser anunciar sua ação no site ou nas mídias sociais. Mas lembre-se das seguintes dicas antes de criar e distribuir um link do Assistente:

• Os links do Google Assistente só funcionam depois que sua ação é publicada. Enquanto seu projeto estiver em estado de rascunho, o link só funcionará nos próprios dispositivos. Qualquer outra pessoa será direcionada para uma página de erro 404 no diretório do Actions.
• Para permitir que os usuários testem um link do Assistente antes da publicação, libere a ação em um ambiente Alfa ou Beta. Apenas os usuários que participarem da versão Alfa ou Beta poderão testar o link do Assistente.
• Garanta que a intent de destino do seu link do Assistente cause uma boa primeira impressão aos novos usuários. A intent de boas-vindas é o destino padrão de um link do Assistente, porque já deveria ser uma boa ideia apresentar a ação.

Dica:neste exemplo, você criará somente um link simples do Google Assistente que levará os usuários à intent de boas-vindas. No entanto, é possível fazer muito mais para personalizar um link do Google Assistente. É possível anexar parâmetros de URL que direcionam os usuários a intents específicas e até mesmo incluir parâmetros de intent para personalizar a resposta recebida quando eles acessam o link. Embora não estejamos abordando essas opções avançadas neste codelab, você pode ver mais informações na documentação do desenvolvedor.

Ativar os links do Google Assistente

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

1. No Console do Actions, clique na guia Desenvolver e selecione Ações na barra de navegação à esquerda.
2. Clique em actions.intent.MAIN na lista Actions.
3. Na seção Links, alterne a opção Gostaria de ativar um URL para esta ação.
4. Defina um Título do link descritivo que descreva sua ação. Use um par de verbos e títulos simples que descreva o que o usuário pode conseguir com sua ação. Para este exemplo, defina o Título do link como learn about Action Gym.
5. Copie o snippet de HTML do fim desta página e salve-o para mais tarde.
6. Clique em Salvar na parte superior da página.

Implantar um site de teste

Para testar seu link do Assistente, use as ferramentas do Firebase e implante um site de teste com seu fulfillment. Já criamos um site de teste simples para este exemplo. Você só precisa adicionar o link do Google Assistente.

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

No arquivo index.html, cole o snippet HTML do link do Assistente no elemento do corpo. O arquivo ficará como o exemplo 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 Assistente

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

firebase deploy

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

Acesse esse URL no navegador da Web do seu dispositivo móvel. Você verá o link do Assistente no seu site de teste. Ao clicar nesse link no seu dispositivo móvel, você deve ir para a intent de boas-vindas do Action no Google Assistente.

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

6. Próximas etapas

Parabéns!

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

Recursos de aprendizado adicionais

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

• Engajamento do usuário: 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 no Console do Actions que mostra a retenção de usuários para a ação publicada.
• Diretrizes de design de conversa: práticas recomendadas e diretrizes sobre como projetar 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 informar sobre nosso desempenho.