Sobre este codelab
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.
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:
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:
- Abra o Console do Actions.
- Clique em Novo projeto.
- Digite um Nome de projeto, como
engagement-codelab
. - Clique em Criar projeto.
- Em vez de escolher uma categoria, role para baixo até a seção Mais opções e clique no card Conversas.
- Clique em Build your Action para expandir as opções e selecione Add Action(s).
- Clique em Add Your First Action.
- Na caixa de diálogo Criar ação, selecione Intent personalizada e clique em Criar para iniciar o console do Dialogflow.
- Na página de criação de agente do console do Dialogflow, clique em Criar.
- Clique no
(ícone de engrenagem) na navegação à esquerda.
- Clique em Export and Import e em Restore From Zip.
- Faça upload do arquivo
agent.zip
do diretório/user-engagement-codelab-nodejs/start/
que você salvou antes. - Digite
RESTORE
e clique em Restaurar. - 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:
- Abra o Console do Firebase.
- Selecione o projeto do Actions na lista de opções.
- 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.
- 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.
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:
- Abra o console do Dialogflow. Se quiser, você pode fechar o Console do Firebase.
- Clique em Fulfillment na navegação à esquerda.
- Ative o Webhook.
- Cole o URL copiado do painel do Firebase se ele ainda não aparecer.
- 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:
- Na barra de navegação à esquerda do console do Dialogflow, clique em Integrations >. Google Assistente
- Verifique se a opção Mudanças na visualização automática está ativada e clique em Testar para atualizar seu projeto do Actions.
- O simulador do Actions carrega seu projeto. Para testar sua ação, digite
Talk to my test app
no campo Entrada e pressione Enter. - 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.
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:
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:
- No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
- Clique em Class List na lista Actions.
- Na seção Engajamento do usuário, ative a opção Você quer oferecer atualizações diárias aos usuários.
- 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
. - Clique em Salvar na parte de cima da página.
Configurar o Dialogflow
Siga estas etapas no console do Dialogflow para criar intents para o fluxo de atualização diária de assinaturas:
Solicitar que o usuário faça a assinatura
- 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.
- Nomeie essa nova intent como
Setup Updates
. - 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
- Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima da página.
Lidar com a decisão do usuário
- 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.
- Nomeie essa nova intent como
Confirm Updates
. - 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. - Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima 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, as importações vão ficar assim:
index.js
const {
dialogflow,
Suggestions,
RegisterUpdate,
} = require('actions-on-google');
Atualizar ícones de sugestão
No arquivo
index.js
, adicione uma entrada DAILY
à lista de títulos de ícones de sugestão para que 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.
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.
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:
- No Console do Actions, acesse Testar.
- Digite
Talk to my test app
no campo Entrada e pressione Enter. - Digite
Learn about classes
e pressione Enter. A resposta da sua Ação agora vai oferecer o envio de lembretes diários. - Digite
Send daily reminders
e pressione Enter. - 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.
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:
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:
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
- Abra o console do Google Cloud e selecione o nome do projeto do Actions no menu suspenso.
- No menu de navegação (☰), acesse APIs e Serviços > Biblioteca.
- Procure a API Actions e clique em Ativar.
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:
- No menu de navegação do console do Google Cloud (☰), acesse APIs e Serviços > Credenciais.
- Clique em Criar credenciais > Chave da conta de serviço.
- No menu suspenso Conta de serviço, selecione Nova conta de serviço.
- 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
- Clique em Criar.
- Mova o arquivo JSON salvo para o diretório /user-engagement-codelab/start/functions/ do projeto.
- Renomeie o arquivo JSON como
service-account.json
.
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:
- No Console do Firebase, selecione o nome do projeto do Actions.
- No painel de navegação à esquerda, acesse Desenvolver > Banco de dados e clique em Criar banco de dados.
- Selecione Iniciar no modo de teste.
- Clique em Ativar.
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
- 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.
- Nomeie essa nova intent como
Setup Push Notifications
. - 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
- Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima da página.
Lidar com a decisão do usuário
- 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.
- Nomeie essa nova intent como
Confirm Push Notifications
. - 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. - Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima da página.
Processar a notificação push
É possível vincular suas notificações push a uma intent específica. 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:
- No console do Dialogflow, clique no botão + ao lado de Intents na navegação à esquerda para criar uma intent.
- Nomeie essa nova intent como
Class Canceled
. - Na seção Training phrases (Frases de treinamento), adicione
Cancelations
como uma expressão do usuário. - Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima da página.
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:
- 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.
- Nomeie essa nova intent como
Test Notification
. - Na seção Training phrases (Frases de treinamento), adicione
Test notification
como uma expressão do usuário. - Na seção Fulfillment, marque a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar na parte de cima da página.
Ativar notificações push
Siga estas etapas para ativar as notificações push para a intent Class Canceled:
- No console do Dialogflow, acesse Integrações na barra de navegação.
- No card Google Assistant, clique em Integration Settings.
- 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).
- Clique em Fechar.
- No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
- Clique em Class Canceled na lista Actions.
- Na seção Engajamento do usuário, ative a opção Gostaria de enviar notificações push?.
- 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
. - Clique em Salvar na parte de cima 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, as importações vão ficar assim:
index.js
const {
dialogflow,
Suggestions,
RegisterUpdate,
UpdatePermission,
} = require('actions-on-google');
Atualizar ícones de sugestão
No arquivo
index.js
, adicione uma entrada NOTIFICATIONS
à lista de títulos de ícones de sugestão para que 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.
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
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.
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.
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:
- No Console do Actions, acesse a guia Testar.
- Digite
Talk to my test app
no campo Entrada e pressione Enter. - Digite
Learn about classes
e pressione Enter. - Digite
Get notifications
e pressione Enter. - Se você ainda não concedeu a permissão da Ação para enviar notificações push, digite
yes
e pressione Enter. - Digite
yes
e pressione Enter. Sua Conta do Google já deve estar inscrita nas notificações push dessa ação.
- Digite
no
e pressione Enter para sair. - Digite
Talk to my test app
e pressione Enter para iniciar uma nova conversa. - Digite
Test notification
e pressione Enter.
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.
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.
Ativar links do Google Assistente
Siga estas etapas para criar um link do Google Assistente para a intent de boas-vindas:
- No Console do Actions, clique na guia Desenvolver e escolha Ações na barra de navegação à esquerda.
- Clique em actions.intent.MAIN na lista Ações.
- Na seção Links, ative a opção Você gostaria de ativar um URL para esta ação.
- 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
. - Copie o snippet HTML da parte inferior desta página e salve-o para mais tarde.
- Clique em Salvar na parte de cima da página.
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.
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>
Testar o link do Google Assistente
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.
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.
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:
- Engajamento do usuário e Documentos de links do Google Assistente: a documentação oficial do Actions on Google sobre os recursos discutidos neste codelab e o engajamento do usuário em geral.
- Análise de retenção de usuários: documentação do recurso de análise do Console do Actions que mostra a retenção de usuários da sua ação publicada.
- Diretrizes de design de conversação: 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 contar como estamos indo.