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

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

Sobre este codelab

subjectÚltimo jun. 13, 2022 atualizado
account_circleEscrito por Assistant Developer Relations

1. Visão geral

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 fazer compras ou agendar uma viagem. Para acessar uma lista completa do que é possível, consulte o Diretório de ações. Como desenvolvedor, você pode usar o Actions on Google para criar e gerenciar facilmente experiências de conversa agradáveis e eficazes entre os usuários e seu serviço de terceiros.

Este é um módulo avançado do codelab, destinado a leitores que já têm alguma experiência na criação de ações para o Google Assistente. Caso não tenha experiência em desenvolvimento com o Actions on Google, recomendamos 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 vão guiar você por uma série de recursos que podem ajudar a expandir a funcionalidade da ação e aumentar o público.

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

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

a3fc0061bd01a75.png 961ef6e27dc73da2.png

O que você vai criar

Você vai aprimorar 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
  • Enviar aos usuários notificações push com um link para sua Ação
  • Crie 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 ambiente de desenvolvimento integrado/editor de texto de sua preferência, 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. Você precisa fazer login no Google Assistente com a mesma Conta do Google que vai usar para criar este projeto.

A familiaridade com JavaScript (ES6) também é altamente recomendada, embora não seja obrigatória, 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.

Noções básicas sobre o exemplo

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

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

e2d6e4ad98948cf3.png

Você vai fazer 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 abaixo para clonar o repositório do GitHub:

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, conclua as seguintes 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 Conversas.
  6. Clique em Build your Action para expandir as opções e selecione Add Action(s).
  7. Clique em Add Your First Action.
  8. Na caixa de diálogo Criar ação, selecione Intent personalizada 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 Export and Import e em Restore From Zip.
  12. Faça upload do arquivo agent.zip do diretório /user-engagement-codelab-nodejs/start/ que você salvou antes.
  13. Digite RESTORE e clique em Restaurar.
  14. Clique em Concluído.

Implantar o fulfillment

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

firebase use <PROJECT_ID>
npm install
firebase deploy

Após alguns minutos, a mensagem "Deploy complete!" será exibida, indicando que você implantou o webhook no Firebase.

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 > Functions na barra de navegação à esquerda. Se a mensagem "Escolher configurações de compartilhamento de dados" aparecer, ignore essa opção clicando em Fazer isso mais tarde.
  4. Na guia Painel, você verá uma entrada para "fulfillment". 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 do Dialogflow para usar o webhook para fulfillment. Para isso, siga estas etapas:

  1. Abra o console do Dialogflow. Se quiser, você pode fechar o Console do Firebase.
  2. Clique em Fulfillment na navegação à esquerda.
  3. Ative o Webhook.
  4. Cole o URL copiado do painel do Firebase se ele ainda não aparecer.
  5. Clique em Salvar.

Verifique se o projeto está configurado corretamente

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

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

  1. Na barra de navegação à esquerda do console do Dialogflow, clique em Integrations >. Google Assistente
  2. Verifique se a opção Mudanças na visualização automática está ativada e clique em Testar para atualizar seu projeto do Actions.
  3. O simulador do Actions carrega seu projeto. 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 e, ao mesmo tempo, verificar se o fulfillment tem uma resposta para cada entrada.

60acf1ff87b1a87f.png

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

Uma maneira comum de envolver os usuários é oferecer informações a eles nos momentos mais úteis. Para isso, os usuários podem se inscrever para receber atualizações diárias de uma intent, que envia uma notificação do Google Assistente com um link direto para o fulfillment dessa intent.

Nesta etapa, você vai aprender sobre assinaturas de atualização diária e adicioná-las à intent Class List da sua ação. Depois de seguir essas instruções, a conversa da sua ação será parecida com o diagrama a seguir:

f48891c8118f7436.png

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 app. As assinaturas de atualização diária são uma maneira simples de acessar usuários em dispositivos móveis fora do Google Assistente, desde que a intent para a qual você está enviando atualizações continue a agregar valor ao usuário diariamente.

As atualizações diárias podem ser uma ferramenta de engajamento útil, mas não devem ser incorporadas a todas as ações. Considere estas dicas ao decidir se você quer 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 sempre resulta na mesma solicitação, é provável que o usuário cancele a inscrição depois de alguns dias.
  • Verifique se a caixa de diálogo faz sentido para o usuário caso ele vá direto para a intent da atualização diária. O usuário não vai começar necessariamente do início da conversa, então não se deve esperar que ele tenha muito contexto.
  • Mostre ao usuário os benefícios da sua ação antes de solicitar que ele se inscreva para receber atualizações diárias. O usuário precisa pensar "quero esse conteúdo todos os dias". quando têm a opção de assinar.
  • 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 assinaria e evite incomodá-lo com isso em outros lugares.
  • Mantenha a conversa curta depois que a intent de atualização for acionada. A maioria das atualizações diárias deve consistir em uma única resposta e fechar sem exigir a entrada do usuário.

Ativar atualizações diárias

As assinaturas de atualização diária 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 vinculá-lo diretamente a algum lugar da conversa. Para este codelab, a intent Lista de turmas faz mais sentido porque o diálogo muda todos os dias, e os usuários podem achar útil receber lembretes sobre as turmas disponíveis.

Siga estas etapas para ativar atualizações diárias para a 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, 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 que eu envie seu <título do conteúdo> diário". Portanto, certifique-se de que o título seja descritivo e soe correto quando for falado 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 de cima da página.

c00885cc30e14d68.png

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 faça a assinatura

  1. Configure uma nova intent para processar o pedido do usuário para se inscrever em 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 Training phrases (Frases de treinamento), adicione as seguintes expressões do usuário:
  • Send daily reminders
  • Reminder
  • Remind me
  • Updates
  • Upcoming classes
  1. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  2. Clique em Salvar na parte de cima da página.

5c70faa02151da0.png

Lidar com 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 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 atualização diária de assinaturas, independentemente de ter feito a assinatura ou não.
  4. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  5. Clique em Salvar na parte de cima da página.

b871c2bdadac8abc.png

Implementar o fulfillment

Para implementar o fulfillment no webhook, siga estas etapas:

Carregar dependências

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

index.js

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

Atualizar ícones de sugestão

b2f84ff91b0e1396.png No arquivo index.js, adicione uma entrada DAILY à lista de títulos de ícones de sugestão para que a 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 para novas intents

Quando o usuário disser que quer se inscrever, inicie o fluxo de assinatura de atualizações diárias chamando o assistente RegisterUpdate com a intent de destino da atualização (Lista de classes) e o tipo (DAILY). Após a conclusão do fluxo de assinatura, o Google Assistente aciona o evento actions_intent_REGISTER_UPDATE com um argumento status, que descreve se a assinatura foi bem-sucedida ou não. Ofereça solicitações de acompanhamento ao usuário que mudem dependendo do 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]));
 
}
});

Oferecer comandos alternativos para o usuário

A 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 precisará se inscrever para receber 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 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 de acordo. Também é possível usar essa ramificação da conversa para fechar a caixa de diálogo logo após fornecer a lista de classes, o 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]));
 
}
});

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

Para testar sua nova solicitação personalizada 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. A resposta da sua Ação agora vai oferecer o envio de lembretes diários.
  4. Digite Send daily reminders e pressione Enter.
  5. Digite o horário em que gostaria de ver a atualização e pressione Enter. Para fins de teste, tente responder três a cinco minutos depois do horário atual.

83a15ecac8c71787.png

No seu dispositivo móvel, você vai receber uma notificação do Google Assistente no horário especificado 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 Class List no Google Assistente, fornecendo uma lista das próximas aulas:

8582482eafc67d5b.png

4. Adicionar notificações push

Outra opção para engajar usuários fora da sua ação é 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 para que você possa enviá-las quando quiser.

Nesta etapa, você vai aprender a implementar notificações push na sua ação adicionando uma nova intent Class Canceled e enviando notificações aos usuários sobre um cancelamento de classe. 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, será 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 User-ID necessário para enviar notificações push. Neste exemplo, você usará uma função da biblioteca cliente para chamar o assistente de permissão e solicitar esse ID.
  • Armazenamento: para enviar notificações push a um usuário fora de uma conversa, é necessário armazenar os IDs de usuário em um local que possa ser recuperado à vontade. Neste exemplo, você vai configurar um banco de dados do Firestore para armazenar as informações de cada usuário.

Depois de seguir essas instruções, você vai adicionar a seguinte caixa de diálogo à conversa da ação:

7c9d4b633c547823.png

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 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 serão notificados diariamente. Com as notificações push, no entanto, os usuários não sabem se estão ativando o recebimento de notificações com pouca frequência 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 precisam ser incorporadas a todas as ações. Considere estas dicas ao decidir se você quer adicionar notificações push a uma ação:

  • Planeje algumas programações de exemplo para suas notificações push. Se você planeja enviar apenas uma notificação push por dia, considere usar atualizações diárias.
  • Garanta que suas notificações push fornecerão informações úteis sempre que forem recebidas. Suas notificações também podem criar links diretos para uma das intents da sua ação, portanto, verifique se a intent é útil e relevante.
  • Seja explícito ao pedir que um usuário se inscreva em notificações push. Ele deve entender o que esperar de cada notificação push e ter uma ideia da frequência de envio das notificações.

Ativar 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 (☰), acesse APIs e Serviços > Biblioteca.
  2. Procure a API Actions e clique em Ativar.

6d464f49c88e70b4.png

Criar uma conta de serviço

A API Actions requer 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ária
  • ID da conta de serviço: service-account (sempre seguido de @<project_id>.iam.gserviceaccount.com)
  • Tipo de chave: JSON
  1. Clique em Criar.
  2. Mova o arquivo JSON salvo para o diretório /user-engagement-codelab/start/functions/ do projeto.
  3. Renomeie o arquivo JSON como service-account.json.

d9bd79d35691de3a.png

Ativar o Firestore

Para enviar notificações fora da conversa, é necessário armazenar IDs de usuário que possam ser referenciados a partir do seu código de notificação. Neste exemplo, estamos usando 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. No painel de 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.

6dfc386413954caa.png

Configurar o Dialogflow

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

Solicitar que o usuário faça a assinatura

  1. Configure uma nova intent para processar o pedido de inscrição do usuário em 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 Training phrases (Frases de treinamento), adicione as seguintes expressões do usuário:
  • Subscribe to notifications
  • Send notification
  • Notify me
  • Send class notifications
  • Cancelled notifications
  1. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  2. Clique em Salvar na parte de cima da página.

3d99bc41d0492552.png

Lidar com a decisão do usuário

  1. Configure uma nova intent para processar a resposta do usuário à solicitação de inscrição de 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 assinaturas de notificações push, independentemente de ter feito a assinatura ou não.
  4. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  5. Clique em Salvar na parte de cima da página.

d37f550c5e07cb73.png

Processar a notificação push

É possível vincular suas notificações push a uma intent específica. Assim, os usuários que tocarem nela terão um link direto para essa intent na sua ação. Neste exemplo, adicione uma nova intent para notificações push que fornece detalhes sobre as aulas canceladas.

Siga estas etapas para adicionar uma intent que será acionada pelo toque do usuário 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 Training phrases (Frases de treinamento), adicione Cancelations como uma expressão do usuário.
  4. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  5. Clique em Salvar na parte de cima da página.

940379556f559631.png

Envie notificações de teste no meio da conversa

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

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

  1. Para fins de teste e depuração, configure uma nova intent que permita enviar notificações push aos 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 Training phrases (Frases de treinamento), adicione Test notification como uma expressão do usuário.
  4. Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
  5. Clique em Salvar na parte de cima da página.

6967f5a997643eb8.png

Ativar notificações push

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

  1. No console do Dialogflow, acesse Integrações na barra de navegação.
  2. No card Google Assistant, clique em Integration Settings.
  3. Adicione Class Canceled como uma intent de invocação implícita. Esta etapa é necessária para que o Dialogflow reconheça que os usuários podem iniciar uma conversa com o intent Class Canceled (clicando em uma notificação push).
  4. Clique em Fechar.

1ac725231ed279a1.png

  1. No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
  2. Clique em Class Canceled na lista Actions.
  3. Na seção Engajamento do usuário, ative a opção Gostaria de enviar notificações push?.
  4. 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 <título do conteúdo>?". Portanto, verifique se o título é descritivo e se está correto em voz alta. Para este exemplo, defina o Título do conteúdo como class cancelations.
  5. Clique em Salvar na parte de cima da página.

4304c7cd575f6de3.png

Implementar o fulfillment

Para implementar o fulfillment no webhook, siga estas etapas:

Carregar dependências

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

index.js

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

Atualizar ícones de sugestão

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

b2f84ff91b0e1396.png No arquivo index.js, adicione o seguinte código às 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 da turma

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

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 para novas intents

Quando o usuário disser que quer se inscrever para receber notificações push, chame o assistente UpdatePermission para solicitar a permissão do usuário. Se tudo der certo, o argumento PERMISSION vai ser adicionado aos argumentos do objeto conv, que você pode verificar para dinamizar a conversa.

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

Por fim, adicione um fulfillment para a intent Class Canceled acionada ao tocar na notificação push. Nesse exemplo, sua resposta é uma string de marcador de posição. No entanto, em uma versão dessa ação pronta para produção, o 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 à 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 vai iterar pelo banco de dados do Firestore e enviar notificações push a todos os usuários inscritos.

Lembre-se de que, neste exemplo, você está incluindo o código que envia a notificação push no fulfillment do webhook e acionando esse código invocando uma intent de teste na conversa. Nas ações que você pretende publicar, o código da notificação push precisa existir em um script separado do fulfillment.

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

Testar as notificações push

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

firebase deploy

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 concedeu a permissão da Ação para enviar notificações push, digite yes e pressione Enter.
  6. Digite yes e pressione Enter. Sua Conta do Google já deve estar inscrita nas notificações push dessa 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ê vai receber uma "Notificação de teste da Action Gym" notificação push do Google Assistente no seu dispositivo móvel. Tocar nessa notificação cria um link direto para o intent Class Canceled da sua ação.

33cbde513c10122e.png

5. Criar um link do Google Assistente

Até agora, discutimos os recursos de engajamento que podem ser implementados para fazer com que os usuários continuem acessando sua ação, mas eles têm como base a descoberta e o uso da ação.

Você pode criar um link do Assistente que direcione os usuários em dispositivos móveis diretamente à sua ação no Assistente. Como um 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 postagem de mídia social.

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 envolverá os usuários?

Atraia usuários para sua ação pela primeira vez, principalmente quando eles precisam invocá-la explicitamente no Google Assistente. Um link do Google Assistente diminui esse atrito porque fornece aos usuários um link direto para sua ação. Quando um usuário segue o link do Google Assistente em um dispositivo com Google Assistente, ele é levado diretamente para sua ação. Quando um usuário abrir seu link em um dispositivo não móvel ou em qualquer outro dispositivo sem suporte ao Google Assistente, ele ainda será direcionado para a página de detalhes do diretório de ações (se tiver sido publicado). Assim, o link ainda poderá comercializar sua ação para esses usuários.

Os links do Google Assistente podem ser uma ferramenta de engajamento útil, então crie um se você quiser anunciar a ação pelo seu site ou mídias sociais. Confira estas dicas antes de criar e distribuir um link do Assistente:

  • Os links do Google Assistente só funcionam depois que a ação é publicada. Enquanto o projeto estiver em estado de rascunho, o link só funcionará nos seus próprios dispositivos. Os outros usuários serão direcionados para uma página 404 no diretório "Ações".
  • Você pode permitir que os usuários testem um link do Assistente antes da publicação ao lançar a ação em um ambiente Alfa ou Beta. Apenas os usuários que participarem da versão Alfa ou Beta vão poder testar o link do Google Assistente.
  • Verifique se a intenção de destino do link do Google Assistente causa uma boa primeira impressão nos novos usuários. Sua intent de boas-vindas é o destino padrão de um link do Google Assistente, porque ele já deve fazer um bom trabalho de apresentação da ação.

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ê gostaria de ativar um URL para esta ação.
  4. Defina um Título do link descritivo que descreva a ação. Transforme seu título em um par de verbos e substantivos simples que descreva o que o usuário pode realizar com sua ação. Para este exemplo, defina o Título do link como learn about Action Gym.
  5. Copie o snippet HTML da parte inferior desta página e salve-o para mais tarde.
  6. Clique em Salvar na parte de cima da página.

55341b8102b71eab.png

Implantar um site de teste

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

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

b2f84ff91b0e1396.png No arquivo index.html, cole o snippet HTML do link do Assistente no elemento do corpo. 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>

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

firebase deploy

Quando a execução do comando de implantação terminar, anote o URL de hospedagem na resposta.

b01e8d322fb5d623.png

Acesse esse URL no navegador da Web do seu dispositivo móvel e você verá o link do Assistente no site de teste. Ao clicar nesse link no seu dispositivo móvel, você acessa a intent de boas-vindas da sua ação no Google Assistente.

599845d647f5b624.png

Você também pode tentar acessar o URL de hospedagem em um navegador para computador. Isso vai levar 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!

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 para sua ação:

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 como estamos indo.