Envolva os usuários com seu Action for Google Assistant

Actions on Google é uma plataforma de desenvolvedor que permite criar software para estender a funcionalidade do Google Assistant , o assistente pessoal virtual do Google, em mais de 1 bilhão de dispositivos, incluindo alto-falantes inteligentes, telefones, carros, TVs, fones de ouvido e muito mais. Os usuários conversam com o Assistente para realizar tarefas, como comprar mantimentos ou reservar uma viagem. (Para obter uma lista completa do que é possível, consulte o diretório Actions .) Como desenvolvedor, você pode usar Actions on Google para criar e gerenciar facilmente experiências de conversa agradáveis ​​e eficazes entre usuários e seu 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ê não tem nenhuma experiência anterior de desenvolvimento com Actions on Google, é altamente recomendável que você se familiarize com a plataforma seguindo nossos codelabs introdutórios ( Nível 1 , Nível 2 e Nível 3 ). Esses módulos avançados o guiarão por uma série de recursos que podem ajudá-lo a expandir a funcionalidade do Action e aumentar seu público.

Uma forma importante de medir o sucesso de uma ação é o envolvimento do usuário ou a eficácia da ação em trazer os usuários de volta após sua primeira interação. Para ajudar a tornar isso mais fácil, você pode implementar vários recursos em seu Action que fornecem aos usuários caminhos de volta à sua conversa.

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

a3fc0061bd01a75.png961ef6e27dc73da2.png

O que você vai construir

Você aprimorará um recurso que já foi criado ao habilitá-lo para:

  • Envie aos usuários uma atualização diária em que eles podem tocar para falar com o seu Action
  • Envie aos usuários notificações push que remetem à sua ação
  • Crie um link que direcione os usuários à sua ação a partir de um navegador da web para celular

O que você aprenderá

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

O que você precisará

Você deve ter as seguintes ferramentas:

  • Um IDE / editor de texto de sua escolha, como WebStorm , Atom ou Sublime
  • Um terminal para executar comandos shell com Node.js, npm e git instalado
  • 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 Assistente (você deve estar conectado ao Assistente com a mesma Conta do Google que usará para construir este projeto).

Familiaridade com JavaScript (ES6) também é altamente recomendável, embora não seja obrigatório, para compreender o código do webhook.

Esta seção mostra como adicionar recursos de engajamento do usuário a uma ação completa previamente construída.

Entenda a amostra

O exemplo deste codelab é uma ação simples para uma academia fictícia chamada "Ginástica de ação". O Action traz informações sobre a academia, incluindo uma lista de aulas que se alternam a cada dia. Uma ação informativa como esta é uma boa candidata para todos os recursos de engajamento do usuário porque a lista de turmas rotativas fornece informações úteis diferentes a cada dia.

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

e2d6e4ad98948cf3.png

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

Baixe seus arquivos de base

Execute o seguinte comando para clonar o repositório GitHub para o codelab:

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

Configure seu projeto e agente

Para configurar seu projeto Actions e agente Dialogflow, conclua as seguintes etapas:

  1. Abra o console de ações .
  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 cartão de Conversa .
  6. Clique em Construir sua ação para expandir as opções e selecione Adicionar ação (ões) .
  7. Clique em Adicionar sua primeira ação .
  8. Na caixa de diálogo Criar ação , selecione Intent personalizado e clique em Criar para iniciar o console do Dialogflow.
  9. Na página de criação de agente do console do Dialogflow, clique em Criar .
  10. Clique no 6bf56243a8a11a3b.png (ícone de engrenagem) na navegação à esquerda.
  11. Clique em Exportar e Importar e em Restaurar do Zip .
  12. Faça upload do arquivo agent.zip diretório /user-engagement-codelab-nodejs/start/ você baixou anteriormente.
  13. Digite RESTORE e clique em Restore .
  14. Clique em Concluído .

Implante o seu cumprimento

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 seu clone de arquivos base, execute os seguintes comandos:

firebase use <PROJECT_ID>
npm install
firebase deploy

Depois de alguns minutos, você deverá ver " Deploy complete! ", O que indica que você implantou com sucesso seu webhook no Firebase.

Recupere o URL de implantação

Você precisa fornecer ao Dialogflow o URL para a função de nuvem. Para recuperar este URL, siga estas etapas:

  1. Abra o console do Firebase .
  2. Selecione seu projeto Actions na lista de opções.
  3. Navegue até Desenvolver> Funções na barra de navegação esquerda. Se for solicitado "Escolher configurações de compartilhamento de dados", você pode ignorar essa opção clicando em Fazer isso mais tarde .
  4. Na guia Painel , você deve ver uma entrada para "atendimento" com um URL em Acionador . Salve este URL; você precisará copiá-lo para o Dialogflow na próxima seção.

1741a329947975db.png

Defina o URL do webhook no Dialogflow

Agora você precisa atualizar seu agente Dialogflow para usar seu webhook para atendimento. Para fazer isso, siga estas etapas:

  1. Abra o console do Dialogflow (você pode fechar o console do Firebase se desejar).
  2. Clique em Fulfillment no painel de navegação esquerdo.
  3. Ative o Webhook .
  4. Cole o URL que você copiou do painel do Firebase se ele ainda não aparecer.
  5. Clique em Salvar .

Verifique se o seu projeto está configurado corretamente

Os usuários devem ser capazes de invocar seu Action para obter informações sobre o Action Gym, incluindo uma resposta de texto codificada com o horário comercial e uma resposta de texto que lista a programação de aula para cada dia da semana.

Para testar sua ação no simulador de ações:

  1. Na navegação à esquerda do console do Dialogflow, clique em Integrações > Google Assistant .
  2. Certifique-se de que as alterações de visualização automática estejam ativadas e clique em Testar para atualizar seu projeto do Actions.
  3. O simulador Actions carrega seu projeto Actions. Para testar sua 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. Tente seguir as instruções para continuar a conversa, certificando-se de que seu cumprimento tenha uma resposta para cada entrada.

60acf1ff87b1a87f.png

Uma maneira comum de envolver os usuários é oferecer informações a eles quando forem mais úteis. Isso é conseguido oferecendo aos usuários a opção de assinar atualizações diárias de um intent, o que os envia uma notificação do Assistente com um link direto para o cumprimento desse intent.

Nesta etapa, você aprenderá sobre as assinaturas de atualização diária e as adicionará à sua intenção Class List do Action. Depois de seguir essas instruções, a conversa do seu Action se parecerá com o seguinte diagrama:

f48891c8118f7436.png

Como isso envolverá os usuários?

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

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

  • Certifique-se de que as atualizações diárias farão com que o usuário veja informações diferentes e úteis todos os dias. Se tocar em uma atualização diária resultar no mesmo prompt todas as vezes, o usuário provavelmente cancelará a assinatura após alguns dias.
  • Certifique-se de que sua caixa de diálogo faça sentido para o usuário se ele pular direto para a intenção da atualização diária. Seu usuário não necessariamente começará do início da conversa, então não se deve esperar que ele tenha muito contexto.
  • Mostre ao seu usuário o benefício de sua ação antes de solicitá-lo a se inscrever para receber atualizações diárias. Seu usuário deve estar pensando "Quero este conteúdo todos os dias" quando tiver 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 após mostrar ao usuário o que ele assinaria e evite importuná-lo em outro lugar.
  • Mantenha a conversa curta depois que a intenção de atualização for acionada. A maioria das atualizações diárias deve consistir apenas em uma única resposta e, em seguida, fechar sem exigir a entrada do usuário.

Ative as atualizações diárias

As assinaturas de atualização diária podem ser adicionadas ao intent de boas-vindas, que coloca o usuário no início da conversa, ou a um intent mais específico, a fim de vinculá-lo a algum lugar da conversa. Para este codelab, a intenção da Lista de classes faz mais sentido porque o diálogo muda todos os dias, e os usuários podem achar útil ser lembrado de quais classes estão disponíveis.

Siga estas etapas para habilitar atualizações diárias para a intenção da Class List :

  1. No console de Ações, 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 Gostaria de oferecer atualizações diárias aos usuários .
  4. Defina um título de conteúdo descritivo que descreva a atualização diária. O contexto será "A que horas você gostaria que eu enviasse seu <título do conteúdo> diário", portanto, certifique-se de que seu título seja descritivo e soe correto quando falado em voz alta. Para este exemplo, defina o título do conteúdo para a list of upcoming Action Gym classes .
  5. Clique em Salvar na parte superior da página.

c00885cc30e14d68.png

Configurar Dialogflow

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

Solicita que o usuário se inscreva

  1. Configure uma nova intenção para lidar com o usuário que está solicitando a assinatura de atualizações diárias. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar um novo intent.
  2. Nomeie essa nova intenção 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
  1. Na seção Fulfillment , alterne a opção Enable webhook call for this intent .
  2. Clique em Salvar na parte superior da página.

5c70faa02151da0.png

Lidar com a decisão do usuário

  1. Configure uma nova intenção para lidar com a resposta do usuário ao prompt de assinatura de atualizações diárias. Clique no botão + ao lado de Intents na navegação à esquerda para criar um novo intent.
  2. Nomeie esta nova intenção como Confirm Updates .
  3. Na seção Eventos , adicione actions_intent_REGISTER_UPDATE . Esse evento do Dialogflow será acionado pelo usuário que conclui o fluxo diário de atualização de assinatura, quer tenha feito a assinatura ou não.
  4. Na seção Fulfillment , alterne a opção Enable webhook call for this intent .
  5. Clique em Salvar na parte superior da página.

b871c2bdadac8abc.png

Implementar o cumprimento

Para implementar o preenchimento em seu webhook, conclua as seguintes etapas:

Carregar dependências

b2f84ff91b0e1396.png No arquivo index.js , atualize a função require() para adicionar o pacote RegisterUpdate pacote actions-on-google , para que suas importações fiquem assim:

index.js

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

Atualizar fichas de sugestão

b2f84ff91b0e1396.png No arquivo index.js , adicione uma entrada DAILY à lista de títulos de fichas 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',
};

Adicione cumprimento para novas intents

Quando o usuário disser que deseja assinar, inicie o fluxo de assinatura de atualizações diárias chamando o auxiliar RegisterUpdate com a intenção de destino da atualização ( Lista de classes ) e digite ( DAILY ). Após a conclusão do fluxo de assinatura, o Assistant dispara o evento actions_intent_REGISTER_UPDATE com um argumento de status que descreve se a assinatura foi bem-sucedida ou não. Ofereça avisos de acompanhamento ao usuário que mudam de acordo com o status da assinatura.

b2f84ff91b0e1396.png 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]));
  }
});

Oferece prompts alternativos para o usuário

Sua resposta da Lista de turmas 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 será solicitado a se inscrever em atualizações diárias, mesmo que tenha vindo de uma. Como você pode evitar que o usuário pense que precisa se inscrever novamente?

Felizmente, os argumentos do seu 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 alterar a resposta de acordo. Você também pode usar este ramo 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.

b2f84ff91b0e1396.png 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 isso:

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

Teste suas atualizações diárias

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

firebase deploy

Para testar seu reprompt personalizado no simulador do Actions, siga estas etapas:

  1. No console Actions, navegue até Test .
  2. Digite Talk to my test app no campo de entrada e pressione Enter.
  3. Digite Learn about classes e pressione Enter. A resposta do seu Action agora deve oferecer o envio de lembretes diários.
  4. Digite Send daily reminders e pressione Enter.
  5. Digite um horário em que gostaria de ver a atualização e pressione Enter. Para fins de teste, tente responder 3-5 minutos após a hora atual.

83a15ecac8c71787.png

No seu dispositivo móvel, você deve receber uma notificação do Assistant próximo ao horário especificado para atualizações. Observe que esta notificação pode demorar alguns minutos para aparecer. Toque na notificação e que deveria deep-link diretamente para a lista de classe intenção em Assistant, dando-lhe uma lista dos próximos classes:

8582482eafc67d5b.png

Como outra opção para envolver usuários fora de seu Action, 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 Assistente para que você possa enviá-las à vontade.

Nesta etapa, você aprenderá como implementar notificações push em sua Ação adicionando uma nova intenção de Classe Cancelada e enviando notificações aos usuários que os notificam sobre o cancelamento de uma classe. Você também configurará os três componentes a seguir necessários para enviar notificações:

  • Conta de API de ações - você envia notificações ao usuário enviando uma solicitação POST para uma API, portanto, você precisará configurar uma conta de serviço e credenciais para fazer a interface com esta API.
  • Auxiliar de permissão - você precisa da permissão do usuário para acessar a ID do usuário necessária para enviar notificações push. Neste exemplo, você usará uma função de biblioteca de cliente para chamar o auxiliar de permissão e solicitar esse ID.
  • Armazenamento - para enviar notificações push a um usuário fora de uma conversa, você precisa armazenar IDs de usuário em algum lugar que possa ser recuperado à vontade. Neste exemplo, você configurará um banco de dados Firestore para armazenar informações para cada usuário.

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

7c9d4b633c547823.png

Como isso envolverá os usuários?

Os usuários de smartphones provavelmente estão familiarizados com notificações push, que fornecem atualizações e informações específicas do aplicativo. As notificações push são uma forma flexível de acessar usuários em dispositivos móveis fora do Assistant, desde que os usuários tenham um bom motivo para ativá-los. Com as atualizações diárias, os usuários já sabem que serão notificados diariamente. Com as notificações push, no entanto, os usuários não sabem se estão optando por receber 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 em todas as ações. Considere estas dicas ao decidir se deseja adicionar notificações push a uma ação:

  • Planeje alguns agendamentos de exemplo para suas notificações push. Se você planeja enviar apenas uma notificação push por dia, considere usar atualizações diárias.
  • Certifique-se de que suas notificações push fornecerão informações úteis sempre que forem recebidas. Suas notificações também podem ter links diretos para um dos intents do seu Action, portanto, certifique-se de que o intent seja útil e relevante.
  • Seja explícito ao pedir a um usuário para assinar notificações push. Eles devem entender o que esperar de cada notificação push e ter uma ideia da frequência com que as notificações são enviadas.

Habilite a API Actions

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

d015c1515b99e3db.png

  1. No menu de navegação ( ☰) , vá para APIs e serviços> Biblioteca.
  2. Procure a API Actions e clique em Enable .

6d464f49c88e70b4.png

Crie uma conta de serviço

A API Actions requer autenticação, então 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 Google Cloud Console (☰) , vá para APIs e serviços> Credenciais .
  2. Clique em Criar credenciais> Chave da conta de serviço .
  3. No menu drop-down conta do serviço, selecione Conta de Serviço Novo.
  4. Preencha as seguintes informações:
  • Nome da conta de service-account : service-account
  • Função : Projeto> Proprietário
  • ID da conta de service-account : service-account (sempre seguido por @ <project_id> .iam.gserviceaccount.com)
  • Tipo de chave : JSON
  1. Clique em Criar.
  2. Mova o arquivo JSON baixado para o diretório / user-engagement-codelab / start / functions / do seu projeto.
  3. Renomeie o arquivo JSON para service-account.json .

d9bd79d35691de3a.png

Habilitar Firestore

Para enviar notificações fora da conversa, você precisa de uma forma de armazenar IDs de usuário que podem ser referenciados a partir de seu código de notificação. Para este exemplo, estamos usando um banco de dados Firestore para armazenar os IDs de usuário de usuários inscritos.

Siga estas etapas para criar um banco de dados Firestore para seu Action:

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

6dfc386413954caa.png

Configurar Dialogflow

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

Solicita que o usuário se inscreva

  1. Configure uma nova intenção para lidar com o usuário que está solicitando a assinatura de notificações push para aulas canceladas. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar um novo intent.
  2. Nomeie esta 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
  1. Na seção Fulfillment , alterne a opção Enable webhook call for this intent .
  2. Clique em Salvar na parte superior da página.

3d99bc41d0492552.png

Lidar com a decisão do usuário

  1. Configure uma nova intenção para lidar com a resposta do usuário ao prompt de inscrição de notificações push. Clique no botão + ao lado de Intents na navegação à esquerda para criar um novo intent.
  2. Nomeie essa nova intenção como Confirm Push Notifications .
  3. Na seção Eventos , adicione actions_intent_PERMISSION . Este evento do Dialogflow será acionado pelo usuário que conclui o fluxo de inscrição de notificações push, quer ele tenha se inscrito ou não.
  4. Na seção Fulfillment , alterne a opção Enable webhook call for this intent .
  5. Clique em Salvar na parte superior da página.

d37f550c5e07cb73.png

Lidar com a notificação push

Você pode vincular suas notificações push a um intent específico, de forma que os usuários que tocarem na notificação push sejam vinculados diretamente a esse intent em sua ação. Neste exemplo, adicione um novo intent para notificações push que forneça detalhes sobre aulas canceladas.

Siga estas etapas para adicionar um intent a ser acionado pelo usuário tocando em uma notificação push:

  1. No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar um novo intent.
  2. Nomeie esta 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 , alterne a opção Enable webhook call for this intent .
  5. Clique em Salvar na parte superior da página.

940379556f559631.png

Enviar notificações de teste no meio da conversa

Na produção, você deve ter um script separado do código de cumprimento Action que envia notificações push. Para este exemplo, crie um intent que você pode invocar para enviar uma notificação push enquanto fala com seu Action. Essa intenção é apenas para fins de depuração; na prática, as notificações push não devem ser tratadas pelo seu atendimento ou de outra forma acionadas como parte da conversa do seu Action.

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

  1. Para fins de teste e depuração, configure uma nova intenção que permite 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 um novo intent.
  2. Nomeie esta nova intenção 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 , alterne a opção Enable webhook call for this intent .
  5. Clique em Salvar na parte superior da página.

6967f5a997643eb8.png

Ativar notificações push

Siga estas etapas para habilitar notificações push para o intent Class Canceled :

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

1ac725231ed279a1.png

  1. No console Actions, clique na guia Develop e escolha Actions na barra de navegação à esquerda.
  2. Clique em Class Canceled na lista Actions .
  3. Na seção Engajamento do usuário , alterne o botão Deseja enviar notificações push? opção.
  4. Defina um título de conteúdo descritivo que descreva a notificação push. O contexto será "Tudo bem se eu enviar notificações push para <título do conteúdo>?", Portanto, certifique-se de que seu título seja descritivo e soe correto quando falado em voz alta. Para este exemplo, defina o título do conteúdo para class cancelations .
  5. Clique em Salvar na parte superior da página.

4304c7cd575f6de3.png

Implementar o cumprimento

Para implementar o preenchimento em seu webhook, conclua as seguintes etapas:

Carregar dependências

b2f84ff91b0e1396.png No arquivo index.js , atualize a função require() para adicionar o pacote UpdatePermission pacote actions-on-google , para que suas importações fiquem assim:

index.js

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

Atualizar fichas de sugestão

b2f84ff91b0e1396.png No arquivo index.js , adicione uma entrada NOTIFICATIONS à lista de títulos de fichas 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 Firestore, adicione o pacote firebase-admin e adicione constantes para os campos armazenados no banco de dados. Além disso, importe os pacotes google-auth-library e request para lidar com autenticação e solicitações para a API Actions.

b2f84ff91b0e1396.png 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');

Ofereça-se para configurar notificações de cancelamento de aula

b2f84ff91b0e1396.png 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 isso:

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

Adicione cumprimento para novas intents

Quando o usuário disser que deseja assinar notificações push, chame o auxiliar UpdatePermission para solicitar permissão do usuário. Se for bem-sucedido, o argumento PERMISSION será adicionado aos argumentos do objeto conv que você pode verificar para dinamizar a conversa.

Depois de obter a permissão do usuário, pegue o ID do usuário dos argumentos do objeto conv e salve-o em seu banco de dados. Posteriormente, você enviará esse ID de usuário para a API Actions, que é como o Assistant determina quem recebe a notificação.

Por último, adicione cumprimento para o intent Class Canceled que é acionado tocando na notificação push. Neste exemplo, sua resposta é uma string de espaço reservado, embora em uma versão pronta para produção desta Action, seu script de notificação forneceria informações mais dinâmicas sobre qual classe foi cancelada.

b2f84ff91b0e1396.png 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 para a API Actions com o ID do usuário, o título da notificação e a intenção de destino. Neste exemplo, acionar a intenção de Notificação de Teste irá iterar por meio de seu banco de dados Firestore e enviar notificações push para cada usuário que se inscreveu para receber notificações.

Lembre-se de que, neste exemplo, você está incluindo o código que envia a notificação push em seu cumprimento de webhook e acionando esse código invocando um intent de teste em sua conversa. Em ações que você pretende publicar, seu código de notificação push deve existir em um script separado do seu cumprimento.

b2f84ff91b0e1396.png 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.');
});

Teste suas notificações push

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

firebase deploy

Para testar as notificações no simulador de ações, siga estas etapas:

  1. No console Actions, acesse a guia Test .
  2. Digite Talk to my test app no campo de 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. Agora, sua conta do Google deve estar inscrita para receber notificações push para esta ação.

3a8704bdc0bcbb17.png

  1. Digite no e pressione Enter para sair.
  2. Digite Talk to my test app e pressione Enter para iniciar uma nova conversa.
  3. Digite Test notification e pressione Enter.

634dfcb0be8dfdec.png

Em alguns minutos, você deve receber uma notificação push do Assistente de "Notificação de teste da Action Gym" no seu dispositivo móvel. Tocar nesta notificação criará um link direto para a intenção de Classe cancelada de sua ação.

33cbde513c10122e.png

Até agora, discutimos os recursos de engajamento que você pode implementar para fazer com que os usuários voltem ao seu Action, mas eles se baseiam em ter usuários que descobrem e usam seu Action.

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

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

Como isso envolverá os usuários?

Atrair usuários para seu Action pela primeira vez pode ser desafiador, especialmente quando eles precisam invocar explicitamente seu Action no Assistant. Um link do Assistente alivia esse atrito, fornecendo aos usuários um link direto para sua ação. Quando um usuário segue o link do Assistente em um dispositivo habilitado para Assistente, ele é levado diretamente para o seu Action. Quando um usuário abre seu link em um dispositivo não móvel ou qualquer outro dispositivo que não oferece suporte ao Assistente, ele ainda será levado para a lista do diretório de ações (se tiver sido publicado) para que o link ainda possa comercializar sua ação para aqueles Comercial.

Os links do assistente podem ser uma ferramenta de engajamento útil, portanto, você deve criar um se estiver planejando anunciar sua ação por meio de seu site ou mídia social. Esteja ciente das dicas a seguir antes de criar e distribuir um link do Assistente:

  • Os links do assistente só funcionam depois que sua ação é publicada. While your project is in a draft state, the link will only work on your own devices. Anyone else will be taken to a 404 page in the Actions directory.
  • You can let users test an Assistant link prior to publishing by releasing your Action in an alpha or beta environment . Note that only users who participate in your alpha or beta will be able to test your Assistant link.
  • Make sure the destination intent for your Assistant link makes a good first impression with new users. Your welcome intent is the default destination for an Assistant link because it should already do a good job of introducing your Action

Follow these steps to create an Assistant link for the welcome intent:

  1. In the Actions console, click the Develop tab, and choose Actions in the left navigation bar.
  2. Click on actions.intent.MAIN under the Actions list.
  3. Under the Links section, toggle the Would you like enable a URL for this Action option.
  4. Set a descriptive Link title that describes your Action. Make your title a simple verb-noun pair that describes what the user can accomplish with your Action. For this example, set the Link title to learn about Action Gym .
  5. Copy the HTML snippet from the bottom of this page and save it for later.
  6. Click Save at the top of the page.

55341b8102b71eab.png

Deploy a test website

To test your Assistant link, you can use Firebase tools to deploy a test website alongside your fulfillment. We've already built a simple test website for this example, you just need to add your Assistant link.

Go to your fulfillment's /user-engagement-codelab-nodejs/start/public/ directory and open the index.html file in a text editor.

b2f84ff91b0e1396.png In the index.html file, paste your Assistant link's HTML snippet into the body element. The file should end up looking like the snippet below:

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>

In the terminal, run the following command to deploy your test website to Firebase:

firebase deploy

Once the deploy command finishes running, take note of the Hosting URL in the output.

b01e8d322fb5d623.png

Go to this URL on your mobile device's web browser and you should see the Assistant link on your test website. Clicking this link on your mobile device should take you to your Action's welcome intent in Assistant.

599845d647f5b624.png

You can also try going to the Hosting URL on a desktop browser, which should take you to a 404 page in the Assistant directory since your Action isn't published.

Congratulations!

You've now learned about the importance of user engagement when developing an Action, what user engagement features are available on the platform, and how to add each feature to an Action.

Additional learning resources

Explore these resources to learn more about user engagement for your Action:

Follow us on Twitter @ActionsOnGoogle to stay tuned to our latest announcements, and tweet to #AoGDevs to share what you have built!

Feedback survey

Before you go, please fill out this form to let us know how we're doing!