حفظ البيانات في المحادثة (Dialogflow)

الاستكشاف في Dialogflow

انقر على متابعة لاستيراد نموذج حفظ البيانات في Dialogflow. بعد ذلك، اتّبِع الخطوات أدناه لنشر النموذج واختباره:

  1. أدخِل اسم وكيل وأنشِئ وكيل Dialogflow جديدًا للنموذج.
  2. بعد الانتهاء من استيراد الوكيل، انقر على الانتقال إلى الوكيل.
  3. من قائمة التنقّل الرئيسية، انتقِل إلى توصيل الطلبات.
  4. فعِّل المحرِّر المضمّن، ثم انقر على نشر. ويتضمّن المحرِّر نموذج الرمز.
  5. من قائمة التنقّل الرئيسية، انتقِل إلى عمليات الدمج، ثم انقر على مساعد Google.
  6. في النافذة المشروطة التي تظهر، فعِّل تغييرات المعاينة التلقائية وانقر على اختبار لفتح محاكي الإجراءات.
  7. في المحاكي، أدخِل Talk to my test app لاختبار العيّنة.
متابعة

غالبًا ما يكون حفظ البيانات بين أدوار المحادثة أو عبر محادثات متعددة مع المستخدم جزءًا من توفير تجربة مستخدم ممتازة. يُعد هذا الأمر مفيدًا إذا كنت تقدم ردودًا مفيدة في محادثة واحدة، أو تحفظ نتائج الألعاب عبر الجلسات، أو تذكر أجزاء صغيرة من المعلومات لأحد المستخدمين.

تختلف المتطلبات قليلاً بناءً على ما إذا كنت بحاجة إلى حفظ البيانات خلال محادثة أو عبر المحادثات. لحفظ البيانات في محادثة، يمكنك استخدام الحقل conversationToken في عنصر AppResponse.

لحفظ البيانات في جميع المحادثات، اتّبِع الخطوات التالية بدلاً من ذلك:

  1. حدد ما إذا كان قد تم التحقق من المستخدم أم أنه ضيف.
  2. يمكنك تخزين بيانات المستخدمين أو الوصول إليها باستخدام الحقل userStorage في العنصر AppResponse.

حفظ البيانات بين أدوار المحادثة

الحقل conversationToken هو سلسلة تحتوي على رمز مميّز مبهم تتم إعادة توجيهه إلى "الإجراء" في كل محادثة. على سبيل المثال، إذا ضبطت القيمة على "count=1" في AppResponse للمنعطف الأول من المحادثة، تحتوي قيمة AppRequest التي يتلقاها الإجراء الخاص بك خلال الدور الثاني من المحادثة على "count=1" في conversationToken.

يتم إعداد الرمز المميّز دائمًا في سلسلة فارغة في بداية المحادثة. إذا كنت تستخدم مكتبة عميل Actions on Google Node.js، يمكنك التفاعل مع الرمز المميّز للمحادثة ككائن JSON باستخدام conv.data، حيث يكون conv هو مثيل Conversation.

يعرض النموذج التالي كيفية حفظ عدّاد في الحقل conversationToken في 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

لاحظ أن تنسيق JSON أدناه يصف استجابة الرد التلقائي على الويب التي تستخدم outputContexts بدلاً من 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

تجدر الإشارة إلى أنّ تنسيق JSON أدناه يصف الردّ التلقائي على الويب.

{
  "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}}"
}

راجع دليل أفضل الممارسات تقديم مطالبات مفيدة والفشل بشكلٍ جيد للحصول على مثال عملي حول الاستخدام.

حفظ البيانات في جميع المحادثات

الحقل userStorage في الكائن AppResponse هو سلسلة تحتوي على رمز مميّز مبهم يوفّره الإجراء الذي يتم حفظه في المحادثات لمستخدم معيّن. على سبيل المثال، يمكن للعبة حفظ أعلى نتيجة لمستخدم في userStorage واستخدام قيمتها في رسالة الترحيب في كل مرة يبدأ فيها المستخدم محادثة جديدة.

تحديد حالة التحقق من المستخدم والتعامل معها

يمكن أن تكون قيمة حالة إثبات هوية المستخدم GUEST أو VERIFIED. في بداية كل محادثة، يضبط "المهام مع مساعد Google" حالة التحقق من المستخدم استنادًا إلى مجموعة متنوعة من المؤشرات عند بدء المحادثة. كمثال على ذلك، إذا سجّل مستخدم الدخول إلى "مساعد Google" على جهازه الجوّال، ستكون حالة التحقق هي VERIFIED.

في ما يلي الأسباب المحتملة التي تؤدي إلى ظهور حالة إثبات الهوية للمستخدم GUEST:

  • تم إيقاف النتائج الشخصية للمستخدم.
  • أوقَف المستخدم النشاط على الويب وفي التطبيقات. ضع في اعتبارك أن بعض المستخدمين قد يتم تعطيل هذا الإعداد على مستوى النطاق.
  • إذا كانت ميزة Voice Match مفعّلة على أحد الأجهزة، وتعذّرت المطابقة أو استدعى المستخدم "مساعد Google" بدون استخدام الصوت (مثل الضغط مع الاستمرار على جهاز Google Home).
  • لم يسجّل المستخدم الدخول.

يُرجى التحقّق دائمًا من حالة إثبات هوية المستخدم قبل تخزين البيانات باستخدام userStorage أو بدء عملية ربط الحساب لمنع المستخدمين الضيوف من التفاعل مع ميزة لن تكون متاحة لهم.

إذا كنت تستخدم مكتبة برامج "المهام مع مساعد Google" لنظام التشغيل Node.js، يمكنك الواجهة مع مساحة تخزين المستخدم ككائن JSON باستخدام conv.user.storage، حيث يكون conv هو مثيل Conversation. يوضّح النموذج التالي كيفية حفظ عدّاد في الحقل userStorage على 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

تجدر الإشارة إلى أنّ تنسيق JSON أدناه يصف الردّ التلقائي على الويب.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Alright, I'll store that for next time. See you then."
            }
          }
        ]
      },
      "userStorage": "{\"data\":{\"sum\":68}}"
    }
  }
}

تنسيق JSON

تجدر الإشارة إلى أنّ تنسيق JSON أدناه يصف الردّ التلقائي على الويب.

{
  "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}}"
}

اطّلع على دليل أفضل الممارسات تخصيص المحادثة استنادًا إلى الإعدادات المفضَّلة للمستخدم للحصول على مثال عملي على الاستخدام.

ملاحظة قانونية: الحصول على الموافقة قبل الوصول إلى userStorage تفرض بعض البلدان لوائح تتطلّب من المطوّرين الحصول على موافقة من المستخدم قبل أن يتمكّن من الوصول إلى معلومات معيّنة (مثل المعلومات الشخصية) أو حفظها في userStorage. إذا كنت تعمل في أحد هذه البلدان وتريد الوصول إلى هذه المعلومات أو حفظها في userStorage، عليك الاستعانة بمساعد التأكيد لطلب الموافقة من المستخدم والحصول على الموافقة قبل البدء بتخزين هذه المعلومات في userStorage.

انتهاء صلاحية مساحة التخزين الخاصة بالمستخدم

عندما يتمكّن "مساعد Google" من مطابقة إحدى الهوية مع المستخدم، لا تنتهي صلاحية محتوى userStorage أبدًا، ويمكن للمستخدم أو الإجراء نفسه فقط محوه.

في حال لم يتمكّن "مساعد Google" من مطابقة هوية المستخدم، يتم محو محتوى userStorage في نهاية المحادثة. إليك بعض الأمثلة على الحالات التي لا يستطيع فيها "مساعد Google" مطابقة هوية المستخدم:

  • تم إعداد ميزة Voice Match بدون ميزة مطابقة.
  • أوقَف المستخدم البيانات الشخصية.

محو محتوى حقل userStorage

يمكنك محو محتوى الحقل userStorage من الإجراء من خلال ضبط الحقل resetUserStorage في AppResponse على "صحيح". إذا ضبطت قيمة userStorage على سلسلة فارغة، لن تتغيّر قيمة userStorage في المرحلة التالية من المحادثة. ويتيح لك ذلك تجنُّب إرسال userStorage بالكامل بالتناوب حيث لا يتغيّر المحتوى.

إذا كنت تستخدم مكتبة برامج "المهام مع مساعد Google" لنظام التشغيل Node.js، يمكنك فقط ضبط القيمة conv.user.storage على {} (عنصر فارغ).

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

تجدر الإشارة إلى أنّ تنسيق JSON أدناه يصف الردّ التلقائي على الويب.

{
  "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

تجدر الإشارة إلى أنّ تنسيق JSON أدناه يصف الردّ التلقائي على الويب.

{
  "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\":{}}"
}

بصفتك مستخدمًا، يمكنك عرض محتوى الحقل userStorage في الإجراء الذي استدعته. كما يمكنك إزالة بيانات المستخدمين المخزنة من هذا الإجراء المحدد عن طريق منع الخدمة من تذكرك.

  1. افتح تطبيق المساعد على هاتفك.
  2. انقر على رمز اللائحة.

  3. في علامة التبويب استكشاف، ابحث عن الإجراء الذي تريد عرض مساحة تخزين المستخدم أو محوه له وانقر عليه لفتح صفحة التفاصيل.
  4. انتقِل إلى أسفل الصفحة.
    • لعرض محتوى الحقل userStorage، انقر على [عرض البيانات المخزَّنة].
    • لإزالة بيانات المستخدم المخزّنة، انقر على إيقاف $action عن تذكّري.