Enregistrer des données dans une conversation (Dialogflow)

Explorer dans Dialogflow

Cliquez sur Continuer pour importer notre exemple d'enregistrement de données dans Dialogflow. Suivez ensuite les étapes ci-dessous pour déployer et tester l'exemple:

  1. Saisissez un nom d'agent et créez un agent Dialogflow pour l'exemple.
  2. Une fois l'importation de l'agent terminée, cliquez sur Accéder à l'agent.
  3. Dans le menu de navigation principal, accédez à Fulfillment.
  4. Activez l'éditeur intégré, puis cliquez sur Déployer. L'éditeur contient l'exemple de code.
  5. Dans le menu de navigation principal, accédez à Integrations (Intégrations), puis cliquez sur Google Assistant (Assistant Google).
  6. Dans la fenêtre modale qui s'affiche, activez Auto-preview changes (Prévisualiser automatiquement les modifications), puis cliquez sur Test (Tester) pour ouvrir le simulateur Actions.
  7. Dans le simulateur, saisissez Talk to my test app pour tester l'échantillon.
Continuer

Pour offrir une expérience utilisateur optimale, il faut souvent pouvoir enregistrer des données entre deux conversations ou lors de plusieurs conversations avec un utilisateur. Cela s'avère utile si vous fournissez des invites supplémentaires dans une seule conversation, enregistrez des scores de jeu d'une session à l'autre ou mémorisez de petites informations pour un utilisateur.

Les exigences varient légèrement selon que vous devez enregistrer des données dans une conversation ou entre plusieurs conversations. Pour enregistrer des données dans une conversation, vous pouvez utiliser le champ conversationToken de votre objet AppResponse.

Pour enregistrer les données de plusieurs conversations, procédez comme suit:

  1. Déterminez si l'utilisateur est validé ou un invité.
  2. Stockez les données utilisateur ou accédez-y à l'aide du champ userStorage de votre objet AppResponse.

Enregistrer des données entre deux conversations

Le champ conversationToken est une chaîne contenant un jeton opaque qui est recirculé vers l'action à chaque tour de conversation. Par exemple, si vous définissez la valeur sur "count=1" dans votre AppResponse pour le premier tour de la conversation, le AppRequest reçu par votre action pour le deuxième tour de la conversation contient "count=1" dans son conversationToken.

Le jeton est toujours initialisé sur une chaîne vide au début d'une conversation. Si vous utilisez la bibliothèque cliente Node.js Actions on Google, vous pouvez interagir avec le jeton de conversation en tant qu'objet JSON à l'aide de conv.data, où conv correspond à votre instance de Conversation.

L'exemple suivant montre comment enregistrer un compteur dans le champ conversationToken de votre 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

Notez que le code JSON ci-dessous décrit une réponse webhook qui utilise outputContexts au lieu 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

Notez que le code JSON ci-dessous décrit une réponse 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}}"
}

Consultez notre guide de bonnes pratiques Fournir des nouvelles invites et échouer en douceur pour obtenir un exemple d'utilisation.

Enregistrer des données dans plusieurs conversations

Le champ userStorage de votre objet AppResponse est une chaîne contenant un jeton opaque fourni par l'action, qui est enregistré dans les conversations d'un utilisateur particulier. Par exemple, un jeu peut enregistrer le score le plus élevé d'un utilisateur dans userStorage et utiliser sa valeur dans le message de bienvenue chaque fois que l'utilisateur démarre une nouvelle conversation.

Déterminer et gérer l'état de validation de l'utilisateur

L'état de validation d'un utilisateur peut être défini sur GUEST ou VERIFIED. Au début de chaque conversation, Actions on Google définit l'état de validation de l'utilisateur en fonction de différents indicateurs au début de la conversation. Par exemple, un utilisateur connecté à l'Assistant Google sur son appareil mobile possède l'état de validation VERIFIED.

Voici les raisons possibles pour lesquelles un utilisateur peut présenter l'état de validation GUEST:

  • l'utilisateur a désactivé les résultats personnels ;
  • L'utilisateur a désactivé le paramètre Activité sur le Web et les applications. N'oubliez pas que certains utilisateurs peuvent avoir désactivé ce paramètre au niveau du domaine.
  • si Voice Match est activé sur un appareil et que la mise en correspondance échoue ou que l'utilisateur appelle l'Assistant sans énoncer sa commande (par exemple, en appuyant de manière prolongée sur un appareil Google Home).
  • L'utilisateur n'est pas connecté.

Vérifiez toujours l'état de validation de l'utilisateur avant de stocker des données avec userStorage ou de démarrer un flux d'association de comptes pour empêcher les utilisateurs invités d'interagir avec une fonctionnalité qui échouera pour eux.

Si vous utilisez la bibliothèque cliente Actions On Google pour Node.js, vous pouvez interagir avec l'espace de stockage utilisateur en tant qu'objet JSON à l'aide de conv.user.storage, où conv correspond à votre instance de Conversation. L'exemple suivant montre comment enregistrer un compteur dans le champ userStorage de votre 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

Notez que le code JSON ci-dessous décrit une réponse 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

Notez que le code JSON ci-dessous décrit une réponse 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}}"
}

Consultez notre guide des bonnes pratiques Personnaliser la conversation avec les préférences utilisateur pour obtenir un exemple d'utilisation pratique.

Remarque juridique: Obtenez le consentement des utilisateurs avant d'accéder à userStorage. Certains pays imposent des réglementations qui exigent des développeurs qu'ils obtiennent le consentement de l'utilisateur avant de pouvoir accéder à certaines informations ou les enregistrer (telles que des informations personnelles) dans le userStorage. Si vous opérez dans l'un de ces pays et que vous souhaitez accéder à ces informations ou les enregistrer dans userStorage, vous devez utiliser l'outil d'aide à la confirmation pour demander le consentement de l'utilisateur et l'obtenir avant de pouvoir commencer à stocker ces informations dans userStorage.

Expiration de l'espace de stockage utilisateur

Lorsque l'Assistant peut faire correspondre une identité à l'utilisateur, le contenu de userStorage n'expire jamais, et seul l'utilisateur ou l'action elle-même peut l'effacer.

Lorsque l'Assistant ne peut pas faire correspondre d'identité à l'utilisateur, le contenu de userStorage est effacé à la fin de la conversation. Voici quelques exemples de situations dans lesquelles l'Assistant ne peut pas établir de correspondance entre une identité et l'utilisateur:

  • Voice Match est configuré et il n'y a pas de correspondance.
  • L'utilisateur a désactivé les données à caractère personnel.

Effacer le contenu du champ "userStorage"

Vous pouvez effacer le contenu du champ userStorage de votre action en définissant le champ resetUserStorage de votre AppResponse sur "true". Si vous définissez la valeur de userStorage sur une chaîne vide, la valeur de userStorage restera inchangée lors du prochain tour de conversation. Cela vous permet d'éviter de renvoyer l'intégralité de la userStorage à tour de rôle lorsque son contenu n'a pas changé.

Si vous utilisez la bibliothèque cliente Actions On Google pour Node.js, vous pouvez simplement définir la valeur de conv.user.storage sur {} (objet vide).

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

Notez que le code JSON ci-dessous décrit une réponse 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

Notez que le code JSON ci-dessous décrit une réponse 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\":{}}"
}

En tant qu'utilisateur, vous pouvez afficher le contenu du champ userStorage dans une action que vous avez appelée. Vous pouvez également supprimer les données utilisateur stockées de cette action spécifique en empêchant le service de se souvenir de vous.

  1. Ouvrez l'application Assistant sur votre téléphone.
  2. Appuyez sur l'icône du panneau.

  3. Dans l'onglet Explore (Explorer), recherchez l'action dont vous souhaitez afficher ou effacer l'espace de stockage utilisateur, puis appuyez dessus pour ouvrir la page d'informations.
  4. Faites défiler la page jusqu'en bas.
    • Pour afficher le contenu du champ userStorage, appuyez sur [Afficher les données stockées].
    • Pour supprimer les données utilisateur enregistrées, appuyez sur Empêcher $action de se souvenir de moi.