Explorar no Dialogflow
Clique em Continuar para importar a amostra "Salvar dados" no Dialogflow. Depois, siga as etapas abaixo para implantar e testar o exemplo:
- Insira um nome de agente e crie um novo agente do Dialogflow para a amostra.
- Depois que a importação do agente for concluída, clique em Go to agent.
- No menu de navegação principal, acesse Fulfillment.
- Ative o Inline Editor e clique em Implantar. O editor contém o código de amostra.
- No menu de navegação principal, acesse Integrações e clique em Google Assistente.
- Na janela modal exibida, ative a opção Auto-preview changes e clique em Test para abrir o simulador do Actions.
- No simulador, insira
Talk to my test app
para testar a amostra.
Parte de uma experiência do usuário excelente é poder salvar dados entre turnos de uma conversa ou em várias conversas com um usuário. Isso é útil quando você fornece resolicitações úteis em uma única conversa, salva pontuações de jogos em sessões diferentes ou lembra pequenas informações para um usuário.
Os requisitos variam um pouco dependendo se você precisa salvar dados em uma
conversa ou entre conversas. Para salvar dados em uma conversa, use o campo conversationToken
do seu objeto AppResponse
.
Para salvar dados em conversas, siga estas etapas:
- Determine se o usuário é verificado ou se é um convidado.
- Armazene ou acesse dados do usuário usando o campo
userStorage
do objetoAppResponse
.
Salvar dados entre os turnos de uma conversa
O campo conversationToken
é uma string que contém um token opaco que
é recirculado para a ação a cada rodada de conversas. Por exemplo, se você definir
o valor como "count=1"
no AppResponse
para a primeira interação da
conversa, a AppRequest
recebida pela sua ação na segunda rodada
da conversa contém "count=1"
na conversationToken
.
O token é sempre inicializado como uma string vazia no início de uma
conversa. Se você usar a
biblioteca de cliente Node.js para Actions on Google, poderá
interagir com o token de conversa como um objeto JSON usando conv.data
, em que
conv
é sua instância de Conversation
.
O exemplo a seguir mostra como salvar um contador no campo conversationToken
de AppResponse
:
Node.js
conv.data.firstNum = firstNum; conv.ask(`Got it, the first number is ${firstNum}.`); conv.ask(`What's the second number?`);
Java
ResponseBuilder responseBuilder = getResponseBuilder(request); responseBuilder.getConversationData().put("firstNum", firstNum); responseBuilder.add("Got it, the first number is " + firstNum + "."); responseBuilder.add("What's the second number?"); return responseBuilder.build();
JSON
Observe que o JSON abaixo descreve uma resposta do webhook que usa outputContexts
em vez de conversationToken
.
{ "payload": { "google": { "expectUserResponse": true, "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Got it, the first number is 23." } }, { "simpleResponse": { "textToSpeech": "What's the second number?" } } ] } } }, "outputContexts": [ { "name": "projects/save-data-df-js/agent/sessions/ABwppHGfFkWJdHKPpBEYiGkhdoakWmYj_2sZa4o8pbGG9nj4q5_GfDTtNEXOY34mLX8G4o_d7oZdUW9bnBZC/contexts/_actions_on_google", "lifespanCount": 99, "parameters": { "data": "{\"firstNum\":23}" } } ] }
JSON
Observe que o JSON abaixo descreve uma resposta do webhook.
{ "expectUserResponse": true, "expectedInputs": [ { "possibleIntents": [ { "intent": "actions.intent.TEXT" } ], "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "Got it, the first number is 23." } }, { "simpleResponse": { "textToSpeech": "What's the second number?" } } ] } } } ], "conversationToken": "{\"data\":{\"firstNum\":23}}" }
Consulte o guia de práticas recomendadas Fornecer novas solicitações úteis e falhar normalmente para ver um exemplo de uso prático.
Salvar dados em conversas
O campo userStorage
do objeto AppResponse
é uma string que
contém um token opaco fornecido pela ação que é salva em
conversas de um usuário específico. Por exemplo, um jogo pode salvar a maior
pontuação de um usuário em userStorage
e usar o valor dela na mensagem de boas-vindas sempre
que o usuário iniciar uma nova conversa.
Como determinar e processar o status de verificação do usuário
O status de verificação de um usuário pode ter o valor GUEST
ou VERIFIED
. No
início de cada conversa, o Actions on Google define o status de verificação
do usuário com base em vários indicadores quando a conversa é iniciada. Por
exemplo, um usuário que fez login no Google Assistente no dispositivo móvel tem um
status de verificação de VERIFIED
.
Confira a seguir os possíveis motivos para um usuário ter um status de verificação
GUEST
:
- Os resultados personalizados estão desativados para o usuário.
- O usuário desativou a Atividade na Web e de apps. Lembre-se de que alguns usuários podem desativar essa configuração no nível do domínio.
- Se o Voice Match estiver ativado em um dispositivo e a correspondência falhar ou o usuário invocar o Google Assistente sem usar a voz, como tocar e manter pressionado o Google Home.
- O usuário não está conectado.
Sempre confira o status de verificação do usuário antes de armazenar dados com userStorage
ou iniciar um fluxo de vinculação de conta para evitar que usuários convidados interajam com um recurso que falhará para eles.
Se você usar a biblioteca de cliente do Actions On Google para Node.js,
poderá interagir com o armazenamento do usuário como um objeto JSON usando
conv.user.storage
, em que conv
é sua instância de Conversation
. O
exemplo a seguir mostra como salvar um contador no campo userStorage
de
AppResponse
:
Node.js
app.intent('Save Sum', (conv) => { if (conv.user.verification === 'VERIFIED') { conv.user.storage.sum = conv.data.sum; conv.close(`Alright, I'll store that for next time. See you then.`); } else { conv.close(`I can't save that right now, but we can add ` + `new numbers next time!`); } });
Java
@ForIntent("Save Sum") public ActionResponse saveSum(ActionRequest request) { ResponseBuilder responseBuilder = getResponseBuilder(request); Integer sum = ((Double) request.getConversationData().get("sum")).intValue(); String verificationStatus = request.getUser().getUserVerificationStatus(); if (verificationStatus.equals("VERIFIED")) { responseBuilder.getUserStorage().put("sum", sum); responseBuilder.add("Alright, I'll store that for next time. See you then."); } else { responseBuilder.add("I can't save that right now, but we can add new numbers next time!"); } responseBuilder.endConversation(); return responseBuilder.build(); }
Node.js
if (conv.user.verification === 'VERIFIED') { conv.user.storage.sum = conv.data.sum; conv.close(`Alright, I'll store that for next time. See you then.`); } else { conv.close(`I can't save that right now, but we can add ` + `new numbers next time!`); }
Java
ResponseBuilder responseBuilder = getResponseBuilder(request); Integer sum = ((Double) request.getConversationData().get("sum")).intValue(); String verificationStatus = request.getUser().getUserVerificationStatus(); if (verificationStatus.equals("VERIFIED")) { responseBuilder.getUserStorage().put("sum", sum); responseBuilder.add("Alright, I'll store that for next time. See you then."); } else { responseBuilder.add("I can't save that right now, but we can add new numbers next time!"); } responseBuilder.endConversation(); return responseBuilder.build();
JSON
Observe que o JSON abaixo descreve uma resposta do webhook.
{ "payload": { "google": { "expectUserResponse": false, "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Alright, I'll store that for next time. See you then." } } ] }, "userStorage": "{\"data\":{\"sum\":68}}" } } }
JSON
Observe que o JSON abaixo descreve uma resposta do webhook.
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Alright, I'll store that for next time. See you then." } } ] } }, "conversationToken": "{\"data\":{\"firstNum\":23,\"sum\":68}}", "userStorage": "{\"data\":{\"sum\":68}}" }
Consulte nosso guia de práticas recomendadas Personalizar a conversa com preferências do usuário para ver um exemplo de uso prático.
Observação legal: como obter consentimento antes de acessar o userStorage
.
Alguns países têm regulamentações que exigem que os desenvolvedores recebam o consentimento do
usuário antes de acessar ou salvar determinadas informações (como informações
pessoais) na userStorage
. Se você opera em um desses países e quer acessar ou salvar essas informações no userStorage
, use o Assistente de confirmação para pedir o consentimento do usuário e receber a autorização antes de começar a armazenar essas informações no userStorage
.
Expiração do armazenamento do usuário
Quando o Google Assistente consegue associar uma identidade ao usuário, o conteúdo de
userStorage
nunca expira, e apenas o usuário ou a própria ação pode apagar.
Quando o Google Assistente não consegue associar uma identidade ao usuário, o conteúdo de
userStorage
é apagado no final da conversa. Confira alguns exemplos
de casos em que o Google Assistente não consegue fazer a correspondência entre uma identidade e o usuário:
- O Voice Match está configurado, e não há correspondência.
- O usuário desativou os dados pessoais.
Limpar o conteúdo do campo userStorage
Você pode limpar o conteúdo do campo userStorage
da sua ação
definindo o campo resetUserStorage
da AppResponse
como "true". Se
você definir o valor de userStorage
como uma string vazia, o valor de
userStorage
vai permanecer inalterado na próxima vez da conversa. Isso permite
evitar o envio de toda a userStorage
em turnos em que o conteúdo não
mudou.
Se você estiver usando a biblioteca de cliente do Actions On Google para Node.js, basta definir o valor de conv.user.storage
como {}
(objeto vazio).
Node.js
app.intent('Forget Number', (conv) => { conv.user.storage = {}; conv.ask(`Alright, I forgot your last result.`); conv.ask(`Let's add two new numbers. What is the first number?`); });
Java
@ForIntent("Forget Number") public ActionResponse forgetNumber(ActionRequest request) { ResponseBuilder responseBuilder = getResponseBuilder(request); responseBuilder.getUserStorage().clear(); responseBuilder.add("Alright, I forgot your last result."); responseBuilder.add("Let's add two new numbers. What is the first number?"); return responseBuilder.build(); }
Node.js
conv.user.storage = {}; conv.ask(`Alright, I forgot your last result.`); conv.ask(`Let's add two new numbers. What is the first number?`);
Java
ResponseBuilder responseBuilder = getResponseBuilder(request); responseBuilder.getUserStorage().clear(); responseBuilder.add("Alright, I forgot your last result."); responseBuilder.add("Let's add two new numbers. What is the first number?"); return responseBuilder.build();
JSON
Observe que o JSON abaixo descreve uma resposta do webhook.
{ "payload": { "google": { "expectUserResponse": true, "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Alright, I forgot your last result." } }, { "simpleResponse": { "textToSpeech": "Let's add two new numbers. What is the first number?" } } ] }, "userStorage": "{\"data\":{}}" } } }
JSON
Observe que o JSON abaixo descreve uma resposta do webhook.
{ "expectUserResponse": true, "expectedInputs": [ { "possibleIntents": [ { "intent": "actions.intent.TEXT" } ], "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "Alright, I forgot your last result." } }, { "simpleResponse": { "textToSpeech": "Let's add two new numbers. What is the first number?" } } ] } } } ], "userStorage": "{\"data\":{}}" }
Como usuário, você pode conferir o conteúdo do campo userStorage
em uma ação
invocada. Também é possível remover os dados de usuário armazenados dessa ação específica,
fazendo com que o serviço não se lembre de você.
- Abra o app Google Assistente no seu smartphone.
- Toque no ícone da gaveta.
- Na guia Explore, encontre a ação que você quer conferir ou limpe o armazenamento do usuário e toque nela para abrir a página de detalhes.
- Role até a parte de baixo da página.
- Para acessar o conteúdo do campo
userStorage
, toque em [Ver dados armazenados]. - Para remover os dados armazenados do usuário, toque em Impedir que $action se lembre de mim.
- Para acessar o conteúdo do campo