Salvar dados em uma conversa (Dialogflow)

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:

  1. Insira um nome de agente e crie um novo agente do Dialogflow para a amostra.
  2. Depois que a importação do agente for concluída, clique em Go to agent.
  3. No menu de navegação principal, acesse Fulfillment.
  4. Ative o Inline Editor e clique em Implantar. O editor contém o código de amostra.
  5. No menu de navegação principal, acesse Integrações e clique em Google Assistente.
  6. Na janela modal exibida, ative a opção Auto-preview changes e clique em Test para abrir o simulador do Actions.
  7. No simulador, insira Talk to my test app para testar a amostra.
Continuar

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:

  1. Determine se o usuário é verificado ou se é um convidado.
  2. Armazene ou acesse dados do usuário usando o campo userStorage do objeto AppResponse.

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?`);
index.js

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();
MyActionsApp.java

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!`);
  }
});
index.js

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();
}
MyActionsApp.java

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!`);
}
index.js

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();
MyActionsApp.java

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?`);
});
index.js

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();
}
MyActionsApp.java

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?`);
index.js

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();
MyActionsApp.java

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ê.

  1. Abra o app Google Assistente no seu smartphone.
  2. Toque no ícone da gaveta.

  3. 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.
  4. 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.