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

در Dialogflow کاوش کنید

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

  1. یک نام عامل وارد کنید و یک عامل Dialogflow جدید برای نمونه ایجاد کنید.
  2. پس از وارد کردن عامل، روی Go to agent کلیک کنید.
  3. از منوی پیمایش اصلی، به Fulfillment بروید.
  4. ویرایشگر درون خطی را فعال کنید، سپس روی Deploy کلیک کنید. ویرایشگر حاوی کد نمونه است.
  5. از منوی پیمایش اصلی، به Integrations بروید، سپس روی Google Assistant کلیک کنید.
  6. در پنجره مدال که ظاهر می‌شود، پیش‌نمایش خودکار تغییرات را فعال کنید و روی Test کلیک کنید تا شبیه‌ساز Actions باز شود.
  7. در شبیه ساز برای تست نمونه وارد Talk to my test app شوید!
ادامه

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

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

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

  1. تعیین کنید که آیا کاربر تأیید شده است یا مهمان.
  2. با استفاده از فیلد userStorage شی AppResponse خود، داده های کاربر را ذخیره کرده یا به آنها دسترسی داشته باشید.

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

فیلد conversationToken رشته‌ای است که حاوی یک نشانه غیر شفاف است که در هر نوبت مکالمه به Action بازگردانده می‌شود. به عنوان مثال، اگر مقدار "count=1" در AppResponse خود برای نوبت اول مکالمه تنظیم کنید، AppRequest دریافت شده توسط Action شما برای نوبت دوم مکالمه حاوی "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?`);
index.js

جاوا

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

توجه داشته باشید که JSON زیر یک پاسخ webhook را توضیح می‌دهد که از 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 شما رشته‌ای است که حاوی یک نشانه مات است که توسط Action ارائه می‌شود و در بین مکالمات برای یک کاربر خاص ذخیره می‌شود. به عنوان مثال، یک بازی می تواند بالاترین امتیاز یک کاربر را در userStorage ذخیره کند و هر بار که کاربر مکالمه جدیدی را شروع می کند، از مقدار آن در پیام خوشامدگویی استفاده کند.

تعیین و رسیدگی به وضعیت تأیید کاربر

وضعیت تأیید یک کاربر می‌تواند مقدار GUEST یا VERIFIED داشته باشد. در شروع هر مکالمه، Actions on Google وضعیت تأیید کاربر را بر اساس شاخص‌های مختلفی هنگام شروع مکالمه تنظیم می‌کند. به عنوان یک مثال، کاربری که در دستگاه تلفن همراه خود وارد Google Assistant شده است، وضعیت تأیید VERIFIED دارد.

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

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

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

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

جاوا

@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

جاوا

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

توجه داشته باشید که 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 هرگز منقضی نمی‌شود و فقط کاربر یا خود Action می‌توانند آن را پاک کنند.

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

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

محتوای قسمت userStorage را پاک کنید

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

اگر از Actions On Google Client Library برای 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?`);
});
index.js

جاوا

@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

جاوا

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

توجه داشته باشید که 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 را در یک اقدامی که فراخوانی کرده اید مشاهده کنید. همچنین می‌توانید با جلوگیری از به خاطر سپردن سرویس، داده‌های کاربر ذخیره‌شده خود را از آن Action خاص حذف کنید.

  1. برنامه Assistant را در گوشی خود باز کنید.
  2. روی نماد کشو ضربه بزنید.

  3. در برگه کاوش ، اقدامی را که می‌خواهید مشاهده کنید یا فضای ذخیره‌سازی کاربر را پاک کنید، پیدا کنید و روی آن ضربه بزنید تا صفحه جزئیات باز شود.
  4. به پایین صفحه رجوع کنید.
    • برای مشاهده محتوای قسمت userStorage ، روی [مشاهده داده های ذخیره شده] ضربه بزنید.
    • برای حذف داده‌های ذخیره‌شده کاربر، روی Stop $action از به خاطر سپردن من ضربه بزنید.