فتح مربّعات الحوار التفاعلية

توضِّح هذه الصفحة كيفية فتح تطبيق Google Chat لمربّعات الحوار لعرض واجهات المستخدمين والردّ على المستخدمين.

في Google Chat، تظهر الإضافات للمستخدمين على أنّها تطبيقات Google Chat. لمزيد من المعلومات، راجِع نظرة عامة على توسيع نطاق Google Chat.

المحادثات هي واجهات مستندة إلى البطاقات يتم فتحها من مساحة Chat أو رسالة. لا يظهر مربّع الحوار ومقتَله سوى للمستخدم الذي فتحه.

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

المتطلبات الأساسية

Node.js

إضافة على Google Workspace تعمل على توسيع نطاق Google Chat لإنشاء تطبيق، أكمِل البدء السريع لاستخدام بروتوكول HTTP.

ملاحظة: تمّت كتابة نماذج الرموز البرمجية في هذا الدليل لتشغيلها كأحد وظائف Google Cloud لنظام التشغيل Node.js.

برمجة تطبيقات

إضافة على Google Workspace تعمل على توسيع نطاق Google Chat لإنشاء تطبيق، أكمِل الخطوات الأساسية لبدء استخدام Apps Script.

فتح مربّع حوار

الشكل 1: تطبيق Chat الذي يفتح مربّع حوار لجمع معلومات الاتصال

يوضّح هذا القسم كيفية الردّ وإعداد مربّع حوار من خلال تنفيذ ما يلي:

1. فعِّل طلب مربّع الحوار من تفاعل المستخدم.
2. يمكنك معالجة الطلب من خلال الرجوع إلى مربّع الحوار وفتحه.
3. بعد أن يرسل المستخدمون المعلومات، يمكنك معالجتها إما عن طريق إغلاق مربّع الحوار أو عرض مربّع حوار آخر.

بدء طلب حوار

لا يمكن لتطبيق Chat فتح مربّعات حوار إلا للردّ على تفاعل المستخدم، مثل أمر الشرطة المائلة أو النقر على زر من رسالة في بطاقة.

للردّ على المستخدمين من خلال مربّع حوار، يجب أن ينشئ تطبيق Chat تفاعلًا يؤدي إلى طلب مربّع الحوار، مثل ما يلي:

• الردّ على أمر يبدأ بشرطة مائلة لبدء الطلب من أمر شرطة مائلة، يجب وضع علامة في مربّع الاختيار فتح مربّع حوار عند ضبط الأمر.
• الردّ على نقرة زر في رسالة، سواءً كجزء من بطاقة أو في أسفل الرسالة لبدء الطلب من زر في رسالة، عليك ضبط إجراء onClick الزر من خلال ضبط interaction على OPEN_DIALOG.

الشكل 2: يرسل تطبيق Chat رسالة تطلب من المستخدمين استخدام الأمر /addContact.
تتضمّن الرسالة أيضًا زرًا يمكن للمستخدمين النقر عليه لتشغيل الأمر.

يوضّح تنسيق JSON التالي كيفية بدء طلب مربّع حوار من زر في رسالة بطاقة. لفتح مربّع الحوار، اضبط الحقل onClick.action.interaction للزرّ على OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

حيث يكون BUTTON_TEXT هو النص الذي يظهر في الزر وACTION_FUNCTION هي الدالة التي يتم تنفيذها لفتح مربع الحوار الأولي.

افتح مربّع الحوار الأوّلي.

عندما يشغّل مستخدم طلب مربّع حوار، يتلقّى تطبيق Chat عنصر حدث يحتوي على ملف حمولة يحدد عنصر dialogEventType على أنّه REQUEST_DIALOG.

لفتح مربّع حوار، يمكن لتطبيق Chat الردّ على الطلب من خلال عرض عنصر RenderActions مع رمز التنقّل pushCard لعرض بطاقة. يجب أن تحتوي البطاقة على أي عناصر لواجهة المستخدم، بما في ذلك تطبيقات مصغّرة واحدة أو أكثر sections[]. لجمع المعلومات من المستخدمين، يمكنك تحديد تطبيقات مصغّرة لإدخال النموذج وتطبيق مصغّر لزر. لمزيد من المعلومات عن تصميم مدخلات النماذج، يُرجى الاطّلاع على مقالة جمع المعلومات من المستخدمين ومعالجتها.

يوضّح تنسيق JSON التالي كيفية عرض تطبيق Chat لردّ يؤدي إلى فتح مربّع حوار:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

حيث يكون BUTTON_TEXT هو النص الذي يظهر في الزر (مثل Next أو Submit)، ويمثّل WIDGETS واحدًا أو أكثر من تطبيقات مصغّرة لإدخال البيانات في النموذج، وACTION_FUNCTION هو دالة الاستدعاء للإجراء التي يتم تنفيذها عندما ينقر المستخدمون على زر.

معالجة إرسال مربّع الحوار

عندما ينقر المستخدمون على زر يُرسِل مربّع حوار، يتلقّى تطبيق Chat عنصر حدث يتضمّن عنصرًا ButtonClickedPayload. في الحمولة، تم ضبط dialogEventType على SUBMIT_DIALOG.

يجب أن يعالج تطبيق Chat عنصر الحدث من خلال تنفيذ أحد الإجراءات التالية:

• ارجع إلى مربّع حوار آخر لتعبئة بطاقة أو نموذج آخر.
• أغلِق مربّع الحوار بعد التحقّق من صحة البيانات التي أرسلها المستخدم، و يمكنك اختياريًا إرسال رسالة تأكيد.

اختياري: عرض مربّع حوار آخر

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

لمعالجة البيانات التي يُدخلها المستخدمون، يعالج تطبيق Chat البيانات في عنصر commonEventObject.formInputs الحدث. للاطّلاع على مزيد من المعلومات عن استرداد القيم من التطبيقات المصغّرة لإدخال البيانات، يُرجى الاطّلاع على مقالة جمع المعلومات من المستخدمين ومعالجتها.

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

في هذا المثال، يفتح تطبيق Chat مربّع حوار أوليًا يؤدي إلى مربّع حوار ثانٍ للتأكيد قبل الإرسال:

Node.js

يتم تشغيل هذا النموذج كـ وظيفة Google Cloud.

/**
 * 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;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

برمجة تطبيقات

يُرسِل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة بطاقات Apps Script.

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

حيث يمثّل WIDGETS أيّ تطبيقات مصغّرة لإدخال البيانات في النماذج أخرى.

إغلاق مربّع الحوار

عندما ينقر المستخدمون على زر إرسال في مربّع حوار، ينفذ تطبيق Chat الإجراء المرتبط به ويقدّم عنصر الحدث مع ضبط buttonClickedPayload على ما يلي:

• isDialogEvent هي true.
• dialogEventType هي SUBMIT_DIALOG.

من المفترض أن يعرِض تطبيق Chat عنصرًا RenderActions بقيمة EndNavigation CLOSE_DIALOG.

اختياري: عرض إشعار

عند إغلاق مربّع الحوار، يمكنك أيضًا عرض إشعار نصي.

لعرض إشعار، أعِد العنصر RenderActions مع ضبط الحقل notification.

يتحقّق المثال التالي من صلاحية المَعلمات ويغلِق مربّع الحوار مع إشعار نصي استنادًا إلى النتيجة:

Node.js

يتم تشغيل هذا النموذج كـ وظيفة Google Cloud.

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

برمجة تطبيقات

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

لمعرفة تفاصيل عن تمرير المَعلمات بين مربّعات الحوار، يُرجى الاطّلاع على مقالة نقل البيانات إلى بطاقة أخرى.

اختياري: إرسال رسالة تأكيد

عند إغلاق مربّع الحوار، يمكنك أيضًا إرسال رسالة جديدة أو تعديل رسالة حالية.

لإرسال رسالة جديدة، أعِد عنصرًا DataActions يحتوي على الحقل CreateMessageAction الذي تم ضبطه بالرسالة الجديدة. على سبيل المثال، لإغلاق مربّع الحوار وإرسال رسالة نصية، أدخِل ما يلي:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

لتعديل رسالة بعد أن يرسل المستخدم مربّع حوار، يجب عرض DataActions عنصر يحتوي على أحد الإجراءات التالية:

• UpdateMessageAction: تعديل رسالة أرسلها تطبيق Chat، مثل الرسالة التي طلب المستخدم من خلالها الحوار
• UpdateInlinePreviewAction: تعديل البطاقة من ملف معاينة الرابط

تحديد المشاكل وحلّها

عندما يعرض تطبيق Google Chat أو بطاقة خطأ، تظهر في واجهة Chat رسالة تفيد بأنّ "حدث خطأ". أو "تعذّرت معالجة طلبك". في بعض الأحيان، لا يعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج عن تطبيق Chat أو البطاقة نتيجة غير متوقّعة. على سبيل المثال، قد لا تظهر رسالة البطاقة .

على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات السجلّ لمساعدتك في حلّ الأخطاء عند تفعيل تسجيل الأخطاء في تطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتصحيح الأخطاء، يُرجى الاطّلاع على مقالة تحديد مشاكل Google Chat وحلّها.