ذخیره کردن داده‌ها در مکالمه (Dialogflow)

کاوش در Dialogflow

روی ادامه کلیک کنید تا نمونه داده‌های «ذخیره» ما را در Dialogflow وارد کنید. سپس، مراحل زیر را برای استقرار و آزمایش نمونه دنبال کنید:

  1. نام عاملی را وارد کنید و عامل Dialogflow جدیدی برای نمونه ایجاد کنید.
  2. پس‌از اینکه وارد کردن عامل تمام شد، روی رفتن به عامل کلیک کنید.
  3. از منو پیمایش اصلی، به تکمیل بروید.
  4. ویرایشگر درون‌خطی را فعال کنید، سپس روی استقرار کلیک کنید. ویرایشگر حاوی کد نمونه است.
  5. از منو پیمایش اصلی، به ادغام‌ها بروید، سپس روی دستیار Google کلیک کنید.
  6. در پنجره مقیدی که ظاهر می‌شود، پیش‌نمایش خودکار تغییرات را فعال کنید و روی آزمایش کلیک کنید تا شبیه‌ساز «کنش‌ها» باز شود.
  7. در شبیه‌ساز، Talk to my test app را برای آزمایش نمونه وارد کنید!
ادامه

بخشی از ارائه یک تجربه کاربری عالی اغلب توانایی ذخیره داده‌ها بین نوبت‌های یک مکالمه یا در چندین مکالمه با یک کاربر است. این کار زمانی مفید است که بخواهید در یک مکالمه، بازدرخواست‌های مفیدی ارائه دهید، امتیازهای بازی را در جلسه‌های مختلف ذخیره کنید، یا بخش‌های کوچکی از اطلاعات را برای کاربر به‌خاطر بسپارید.

الزامات بسته به اینکه لازم باشد داده‌ها را در یک مکالمه یا در مکالمه‌های مختلف ذخیره کنید کمی متفاوت است. برای ذخیره کردن داده‌ها در مکالمه، می‌توانید از فیلد conversationToken شیء AppResponse استفاده کنید.

برای ذخیره کردن داده‌ها در مکالمه‌ها، مراحل زیر را دنبال کنید:

  1. مشخص کنید کاربر درستی‌سنجی‌شده است یا مهمان.
  2. داده‌های کاربر را بااستفاده از فیلد userStorage شیء AppResponse ذخیره کنید یا به آن‌ها دسترسی پیدا کنید.

ذخیره کردن داده‌ها بین نوبت‌های مکالمه

فیلد conversationToken رشته‌ای است که حاوی یک کد غیرشفاف است که در هر نوبت مکالمه به «کنش» بازگردانده می‌شود. برای مثال، اگر مقدار را در AppResponse برای اولین نوبت مکالمه روی "count=1" تنظیم کنید، AppRequest که «کنش» شما برای نوبت دوم مکالمه دریافت می‌کند حاوی "count=1" در conversationToken آن است.

در شروع مکالمه، این کد همیشه با رشته‌ای خالی مقداردهی اولیه می‌شود. اگر از کتابخانه مشتری Actions on Google Node.js استفاده می‌کنید، می‌توانید بااستفاده از conv.data با کد مکالمه به‌عنوان شیء JSON ارتباط برقرار کنید، که در آن 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?`);

جاوا

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 داشته باشد. در شروع هر مکالمه، Actions on Google وضعیت درستی‌سنجی کاربر را براساس شاخص‌های مختلفی در شروع مکالمه تنظیم می‌کند. برای مثال، کاربری که به سیستم «دستیار Google» در دستگاه همراهش وارد شده است، وضعیت درستی‌سنجی VERIFIED دارد.

دلایل احتمالی برای اینکه کاربر وضعیت درستی‌سنجی GUEST داشته باشد عبارتند از:

  • کاربر نتایج شخصی را خاموش کرده است.
  • کاربر فعالیت‌ها در وب و برنامه خود را غیرفعال کرده است. به‌خاطر داشته باشید که برخی‌از کاربران ممکن است این تنظیم را در سطح دامنه غیرفعال کرده باشند.
  • اگر Voice Match در دستگاهی فعال باشد و مطابقت ناموفق باشد یا کاربر بدون استفاده از صدایش (مثلاً با فشار طولانی روی Google Home) «دستیار» را فراخوانی کند.
  • کاربر به سیستم وارد نشده است.

همیشه قبل‌از ذخیره کردن داده‌ها با userStorage یا شروع کردن جریان پیوند دادن حساب، وضعیت درستی‌سنجی کاربر را بررسی کنید تا از تعامل کاربران مهمان با ویژگی‌ای که برای آن‌ها کار نخواهد کرد جلوگیری شود.

اگر از کتابخانه کارخواه Actions On Google برای Node.js استفاده می‌کنید، می‌توانید بااستفاده از conv.user.storage، که conv نمونه شما از Conversation است، با فضای ذخیره‌سازی کاربر به‌عنوان شیء JSON ارتباط برقرار کنید. نمونه زیر نشان می‌دهد که چگونه یک شمارنده را در فیلد 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!`);
  }
});

جاوا

@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!`);
}

جاوا

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 ذخیره کنید، رضایت او را کسب کنید.

انقضای فضای ذخیره‌سازی کاربر

وقتی «دستیار» بتواند هویت را با کاربر مطابقت دهد، محتوای userStorage هرگز منقضی نمی‌شود و فقط کاربر یا خود «کنش» می‌تواند آن را پاک کند.

وقتی «دستیار» نتواند هویت را با کاربر مطابقت دهد، محتوای userStorage در پایان مکالمه پاک می‌شود. در اینجا چند نمونه از مواردی که «دستیار» نمی‌تواند هویت را با کاربر مطابقت دهد آورده شده است:

  • Voice Match راه‌اندازی شده است و تطابقی وجود ندارد.
  • کاربر داده‌های شخصی را غیرفعال کرده است.

پاک کردن محتوای فیلد userStorage

می‌توانید محتوای فیلد userStorage «کنش» خود را با تنظیم فیلد resetUserStorage AppResponse روی true پاک کنید. اگر مقدار userStorage را روی رشته‌ای خالی تنظیم کنید، مقدار userStorage در نوبت بعدی مکالمه بدون تغییر باقی می‌ماند. این کار به شما امکان می‌دهد از ارسال مجدد کل userStorage در نوبت‌هایی که محتوای آن تغییر نکرده است اجتناب کنید.

اگر از Actions On Google Client Library for 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?`);
});

جاوا

@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?`);

جاوا

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 از به‌خاطر سپردن من ضربه بزنید.