اطلاعات کاربران چت گوگل را جمع آوری و پردازش کنید

این راهنما توضیح می‌دهد که چگونه برنامه‌های چت Google می‌توانند اطلاعات کاربران را با ایجاد ورودی‌های فرم در رابط‌های مبتنی بر کارت جمع‌آوری و پردازش کنند.

در Google Chat، افزونه‌ها به عنوان برنامه‌های Google Chat برای کاربران ظاهر می‌شوند. برای کسب اطلاعات بیشتر، به نمای کلی Extend Google Chat مراجعه کنید.

دیالوگی شامل انواع ویجت های مختلف.
شکل 1 : یک برنامه چت که یک گفتگو برای جمع آوری اطلاعات تماس باز می کند.

برنامه‌های گپ اطلاعاتی را از کاربران برای انجام اقداماتی در داخل یا خارج از گپ از جمله به روش‌های زیر درخواست می‌کنند:

  • تنظیمات را پیکربندی کنید. به عنوان مثال، به کاربران اجازه دهید تنظیمات اعلان را سفارشی کنند یا برنامه Chat را به یک یا چند فضا پیکربندی و اضافه کنند.
  • اطلاعات را در سایر برنامه‌های Google Workspace ایجاد یا به‌روزرسانی کنید. به عنوان مثال، به کاربران اجازه دهید یک رویداد Google Calendar ایجاد کنند.
  • به کاربران اجازه دسترسی و به‌روزرسانی منابع موجود در سایر برنامه‌ها یا سرویس‌های وب را بدهید. به عنوان مثال، یک برنامه چت می تواند به کاربران کمک کند تا وضعیت بلیط پشتیبانی را مستقیماً از فضای چت به روز کنند.

پیش نیازها

Node.js

یک افزونه Google Workspace که در Google Chat کار می کند. برای ایجاد یک، شروع سریع HTTP را تکمیل کنید.

اسکریپت برنامه ها

یک افزونه Google Workspace که در Google Chat کار می کند. برای ایجاد یکی، شروع سریع Apps Script را تکمیل کنید.

فرم ها را با استفاده از کارت بسازید

برای جمع‌آوری اطلاعات، برنامه‌های چت فرم‌ها و ورودی‌های آن‌ها را طراحی کرده و آن‌ها را در کارت‌ها می‌سازند. برای نمایش کارت‌ها به کاربران، برنامه‌های چت می‌توانند از رابط‌های چت زیر استفاده کنند:

  • پیام‌های گپ حاوی یک یا چند کارت.
  • دیالوگ ها ، کارت هایی هستند که در یک پنجره جدید از پیام ها و صفحات اصلی باز می شوند.

برنامه های چت می توانند کارت ها را با استفاده از ویجت های زیر بسازند:

  • ویجت های ورودی را تشکیل دهید که اطلاعاتی را از کاربران درخواست می کنند. به صورت اختیاری، می‌توانید اعتبارسنجی را برای ویجت‌های ورودی اضافه کنید تا اطمینان حاصل کنید که کاربران اطلاعات را به درستی وارد کرده و قالب‌بندی می‌کنند. برنامه های چت می توانند از ویجت های ورودی فرم زیر استفاده کنند:

    • ورودی های متن ( textInput ) برای متن آزاد یا پیشنهادی.
    • ورودی‌های انتخاب ( selectionInput ) عناصر رابط کاربری قابل انتخاب مانند کادرهای انتخاب، دکمه‌های رادیویی و منوهای کشویی هستند. ویجت های ورودی انتخابی همچنین می توانند موارد را از منابع داده ایستا یا پویا پر کنند. برای مثال، کاربران می‌توانند از فهرستی از فضاهای چت که عضو آن هستند، انتخاب کنند.

  • ویجت دکمه ای که کاربران می توانند مقادیری را که در کارت وارد کرده اند ارسال کنند. بعد از اینکه کاربر روی دکمه کلیک کرد، برنامه Chat می‌تواند اطلاعاتی را که دریافت می‌کند پردازش کند .

در مثال زیر، یک کارت اطلاعات تماس را با استفاده از ورودی متن، انتخابگر زمان تاریخ و ورودی انتخاب جمع‌آوری می‌کند:

برای نمونه‌های بیشتر از ویجت‌های تعاملی که می‌توانید برای جمع‌آوری اطلاعات از آنها استفاده کنید، به طراحی یک کارت یا گفتگوی تعاملی در اسناد Google Chat API مراجعه کنید.

داده ها را از ویجت های تعاملی دریافت کنید

هر زمان که کاربران روی دکمه‌ای کلیک می‌کنند، عملکرد برنامه‌های چت آن با اطلاعات مربوط به تعامل فعال می‌شود. در commonEventObject از رویداد payload، شی formInputs حاوی مقادیری است که کاربر وارد می کند.

می توانید مقادیر را از شی commonEventObject.formInputs. WIDGET_NAME ، که در آن WIDGET_NAME فیلد name است که برای ویجت تعیین کرده اید. مقادیر به عنوان یک نوع داده خاص برای ویجت برگردانده می شوند.

شکل زیر بخشی از یک شی رویداد را نشان می دهد که در آن کاربر مقادیری را برای هر ویجت وارد می کند:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

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

ویجت ورودی فرم نوع داده های ورودی مقدار ورودی از شی رویداد ارزش نمونه
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs برای دریافت اولین یا تنها مقدار، event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker که فقط تاریخ ها را می پذیرد. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch . 1000425600000

انتقال اطلاعات به کارت دیگر

پس از اینکه کاربر اطلاعاتی را از یک کارت ارسال کرد، ممکن است برای انجام هر یک از موارد زیر نیاز به بازگرداندن کارت های اضافی داشته باشید:

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

برای انتقال داده های ورودی از کارت اولیه، می توانید ویجت button با actionParameters بسازید که حاوی name ویجت و مقداری که کاربر وارد می کند، همانطور که در مثال زیر نشان داده شده است:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

جایی که WIDGET_NAME name ویجت است و USER_INPUT_VALUE چیزی است که کاربر وارد می کند. به عنوان مثال، برای ورودی متنی که نام یک شخص را جمع‌آوری می‌کند، نام ویجت contactName و مقدار نمونه آن Kai O است.

وقتی کاربر روی دکمه کلیک می‌کند، برنامه Chat شما یک شی رویداد دریافت می‌کند که می‌توانید از آن داده دریافت کنید .

به فرم ارسالی پاسخ دهید

پس از دریافت داده‌ها از پیام کارت یا گفتگو، برنامه چت با تأیید دریافت یا برگرداندن خطا پاسخ می‌دهد.

در مثال زیر، یک برنامه چت یک پیام متنی ارسال می کند تا تأیید کند که فرم ارسال شده از یک پیام کارت را با موفقیت دریافت کرده است.

Node.js 

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

اسکریپت برنامه ها

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

برای پردازش و بستن یک گفتگو، یک شی RenderActions را برمی‌گردانید که مشخص می‌کند آیا می‌خواهید یک پیام تأیید ارسال کنید، پیام یا کارت اصلی را به‌روزرسانی کنید یا فقط گفتگو را ببندید. برای مراحل، بستن یک گفتگو را ببینید.

عیب یابی

وقتی یک برنامه یا کارت Google Chat خطایی را برمی‌گرداند، رابط Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمده است». یا "نمی توان به درخواست شما رسیدگی کرد." گاهی اوقات Chat UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامه‌های گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکال‌زدایی و رفع خطاها، به عیب‌یابی و رفع خطاهای Google Chat مراجعه کنید.