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

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

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

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

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

پیش‌نیازها

نود جی اس

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

پایتون

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

جاوا

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

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

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی در Apps Script، این راهنمای سریع را تکمیل کنید.

ساخت فرم با استفاده از کارت‌ها

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

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

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

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

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

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

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

برای مثالی از یک برنامه چت که از این فرم تماس استفاده می‌کند، کد زیر را ببینید:

نود جی اس

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

پایتون

پایتون/فرم تماس-برنامه/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

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

اسکریپت برنامه‌ها/فرم تماس-برنامه/فرم تماس.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

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

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

هر زمان که کاربران روی یک دکمه کلیک می‌کنند، برنامه‌های چت یک رویداد تعاملی وابسته به موقعیت دکمه دریافت می‌کنند:

  • اگر دکمه در یک پیام یا کادر محاوره‌ای باشد، برنامه‌های چت یک رویداد تعاملی CARD_CLICKED دریافت می‌کنند که حاوی اطلاعاتی در مورد تعامل است. محتوای رویدادهای تعاملی CARD_CLICKED شامل یک شیء common.formInputs با هر مقداری است که کاربر وارد می‌کند.

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

    تصویر زیر بخشی از رویداد تعاملی CARD_CLICKED را نشان می‌دهد که در آن کاربر مقادیری را برای هر ویجت وارد کرده است:

    اچ‌تی‌پی 

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

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

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

  • اگر دکمه در صفحه اصلی باشد، برنامه‌های چت یک رویداد تعاملی SUBMIT_FORM دریافت می‌کنند. محتوای رویداد تعاملی شامل یک شیء commonEventObject.formInputs با هر مقداری است که کاربر وارد می‌کند.

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

    تصویر زیر بخشی از رویداد تعاملی SUBMIT_FORM را نشان می‌دهد که در آن کاربر مقادیری را برای هر ویجت وارد کرده است:

    اچ‌تی‌پی 

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

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

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

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

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

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

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

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

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

نود جی اس

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

پایتون

پایتون/فرم تماس-برنامه/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

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

اسکریپت برنامه‌ها/فرم تماس-برنامه/اصلی.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

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

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

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

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

نود جی اس

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

پایتون

پایتون/فرم تماس-برنامه/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

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

اسکریپت برنامه‌ها/فرم تماس-برنامه/اصلی.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

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

عیب‌یابی

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

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