جمع جهات الاتصال وإدارتها في Google Chat

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

إليك طريقة عمل تطبيق Chat:

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

• حساب Google Workspace تابع لـ Business أو Enterprise مع إمكانية الوصول إلى Google Chat
• أنشئ مشروعًا على Google Cloud.

الأهداف

• تصميم واجهات المستخدم وإنشاؤها كعناصر card وعرضها في الرسائل ومربّعات الحوار
• تلقّي ومعالجة المعلومات التي يرسلها المستخدمون باستخدام عناصر واجهة مستخدم لإدخال النماذج
• الردّ على الطلبات برسائل تحتوي على نصوص وبطاقات وأدوات ملحقة

الهندسة المعمارية

تم إنشاء تطبيق Chat باستخدام برمجة تطبيقات Google (كإضافة في Google Workspace توسّع نطاق Google Chat)، ويتفاعل مع تفاعلات المستخدمين (onMessage وonAppCommand والنقر على الأزرار التي تستدعي openInitialDialog وopenConfirmationDialog وsubmitForm) لمعالجة طلبات مستخدمي Chat والرد عليها.

يوضّح ما يلي كيف يمكن للمستخدم التفاعل عادةً مع تطبيق Chat:

1. يفتح مستخدم رسالة مباشرة باستخدام تطبيق Chat، أو يضيف تطبيق Chat إلى مساحة حالية.

2. يطلب تطبيق Chat من المستخدم إضافة جهة اتصال من خلال إنشاء نموذج تواصل وعرضه ككائن card. لعرض نموذج التواصل، يستجيب تطبيق Chat للمستخدمين بالطرق التالية:

   • يردّ على الإشارات التي تستخدم الرمز "@" والرسائل المباشرة (onMessage) برسالة بطاقة تتضمّن نموذج التواصل.
   • يستجيب للأمر الذي يبدأ بشرطة مائلة /addContact (onAppCommand) من خلال فتح مربّع حوار يتضمّن نموذج معلومات الاتصال.
   • يستجيب للأمر المائل /about (onAppCommand) برسالة نصية تتضمّن زر إضافة جهة اتصال يمكن للمستخدمين النقر عليه لتفعيل openInitialDialog وفتح مربّع حوار يتضمّن نموذج جهة الاتصال.

3. عندما يظهر نموذج التواصل، يُدخل المستخدم معلومات الاتصال في الحقول وعناصر واجهة المستخدم التالية:

   • الاسم الأول واسم العائلة: أداة textInput تقبل السلاسل.
   • تاريخ الميلاد: هو dateTimePicker تطبيق مصغّر يقبل التواريخ فقط.
   • نوع جهة الاتصال: عنصر واجهة مستخدم selectionInput يتضمّن أزرار اختيار تتيح للمستخدمين اختيار قيمة سلسلة واحدة وإرسالها (إما Personal أو Work).
   • زر المراجعة والإرسال: هو عبارة عن buttonList مصفوفة تتضمّن أداة button ينقر عليها المستخدم لإرسال القيم التي أدخلها.

4. يستدعي تطبيق Google Chat الدالة openConfirmationDialog لمعالجة القيم التي يدخلها المستخدم، ويعرض القيم في بطاقة تأكيد.

5. يراجع المستخدم بطاقة التأكيد وينقر على الزر إرسال لتفعيل submitForm وإكمال معلومات الاتصال.

6. سيرسل تطبيق Google Chat رسالة نصية خاصة تؤكّد عملية الإرسال.

تجهيز البيئة

يوضّح هذا القسم كيفية إعداد مشروع على Google Cloud لتطبيق Chat.

فتح مشروعك على السحابة الإلكترونية في "وحدة تحكّم Google API"

افتح مشروع على السحابة الإلكترونية الذي تريد استخدامه لهذا النموذج إذا لم يكن مفتوحًا من قبل:

1. في Google API Console، انتقِل إلى صفحة اختيار مشروع.

   اختيار مشروع على السحابة الإلكترونية

2. اختَر مشروع Google Cloud الذي تريد استخدامه. يمكنك أيضًا النقر على إنشاء مشروع واتّباع التعليمات الظاهرة على الشاشة. في حال إنشاء مشروع على Google Cloud، قد تحتاج إلى تفعيل الفوترة للمشروع.

إعداد المصادقة والتفويض

تتطلّب تطبيقات Google Chat إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth ليتمكّن المستخدمون من منح الإذن لتطبيقك في تطبيقات Google Workspace، بما في ذلك Google Chat.

في هذا البرنامج التعليمي، ستنشئ تطبيق Chat مخصّصًا للاختبار والاستخدام الداخلي فقط، لذا لا بأس من استخدام معلومات العنصر النائب لشاشة طلب الموافقة. قبل نشر تطبيق Chat، عليك استبدال أي معلومات نائبة بمعلومات حقيقية.

1. في Google API Console، انتقِل إلى "القائمة" menu > منصة Google Auth > العلامة التجارية.

   الانتقال إلى "هوية العلامة التجارية"

2. إذا سبق لك ضبط منصة Google Auth، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة لم يتم إعداد منصة Google Auth بعد، انقر على البدء:

   1. ضمن معلومات التطبيق، في اسم التطبيق، اكتب Contact Manager.
   2. في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريدك الإلكتروني أو مجموعة Google مناسبة.
   3. انقر على التالي.
   4. ضمن الجمهور، اختَر داخلي. إذا لم تتمكّن من اختيار داخلي، اختَر خارجي.
   5. انقر على التالي.
   6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات عليه بشأن أي تغييرات تطرأ على مشروعك.
   7. انقر على التالي.
   8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، ثم ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API" إذا كنت موافقًا.
   9. انقر على متابعة.
   10. انقر على إنشاء.
   11. إذا اخترت خارجي لنوع المستخدم، أضِف مستخدمين اختباريين:
       1. انقر على الجمهور.
       2. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
       3. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين آخرين معتمَدين للاختبار، ثم انقر على حفظ.

إنشاء تطبيق Chat ونشره

في القسم التالي، يمكنك إنشاء مشروع في برمجة تطبيقات وتعديله باستخدام الرمز البرمجي للتطبيق (Code.gs وappsscript.json) لتطبيق Chat.

يمكنك اختياريًا الاطّلاع على المشروع بأكمله على GitHub.

عرض على GitHub

في ما يلي نظرة عامة على كل ملف:

Code.gs

تتعامل هذه الحزمة مع جميع منطق التطبيق، بما في ذلك تفاعلات المستخدم (onMessage وonAppCommand وopenInitialDialog وopenConfirmationDialog وsubmitForm) وعناصر واجهة المستخدم الخاصة بإدخال النماذج المعروضة في البطاقات ضمن الرسائل ومربّعات الحوار.

عرض رمز واحد (Code.gs)

apps-script/chat/contact-form-app/Code.gs

عرض على GitHub

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * 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"
    }},
    { 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 }
      ]
    }},
    { 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];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * 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 or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

بيان "برمجة تطبيقات Google" الذي يحدّد مشروع "برمجة تطبيقات Google" ويضبطه لتطبيق Chat

عرض رمز واحد (appsscript.json)

apps-script/chat/contact-form-app/appsscript.json

عرض على GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

إنشاء مشروع "برمجة تطبيقات Google"

لإنشاء مشروع في "برمجة تطبيقات Google" من الملفين Code.gs وappsscript.json، اتّبِع الخطوات التالية:

1. انتقِل إلى برمجة تطبيقات Google وانقر على مشروع جديد.

2. أدخِل اسمًا لمشروعك في "برمجة تطبيقات Google":

   1. انقر على مشروع بلا عنوان.

   2. في عنوان المشروع، اكتب Contact Manager - Google Chat app.

   3. انقر على إعادة تسمية.

3. استبدِل محتوى Code.gs بنموذج الرمز Code.gs أعلاه.

4. انقر على إعدادات المشروع واختَر عرض ملف البيان "appsscript.json" في المحرّر.

5. ارجع إلى المحرّر واستبدِل محتوى appsscript.json برمز بيان appsscript.json أعلاه، ثم احفظ مشروعك.

في المستقبل، إذا أردت استخدام Google APIs معيّنة أو نشر تطبيقك، عليك ربط مشروعك على السحابة الإلكترونية بمشروعك على "برمجة التطبيقات". ليس عليك إجراء ذلك في هذا الدليل. لمزيد من المعلومات، راجِع دليل مشاريع Google Cloud.

إنشاء عملية تفعيل في "برمجة تطبيقات Google"

بعد الانتهاء من إعداد الرمز البرمجي، يمكنك نشر مشروع "برمجة تطبيقات Google". يتم استخدام معرّف النشر عند ضبط تطبيق Chat في Google Cloud.

1. في برمجة تطبيقات، افتح مشروع تطبيق Chat.

   الانتقال إلى برمجة تطبيقات

2. انقر على نشر > عملية نشر جديدة.

3. إذا لم يكن خيار إضافة محدّدًا، انقر على أنواع النشر بجانب اختيار النوع، ثم اختَر إضافة.

4. في الوصف، أدخِل وصفًا لهذا الإصدار، مثل Test of Contact Manager.

5. انقر على نشر. تسجّل "برمجة التطبيقات" عملية النشر الناجحة وتوفّر رقم تعريف عملية النشر.

6. انقر على content_copy نسخ لنسخ رقم تعريف عملية النشر، ثم انقر على تم.

ضبط تطبيق Chat في "وحدة تحكّم Google API"

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

1. في Google API Console، انقر على القائمة menu > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API > الإعدادات.

   الانتقال إلى إعدادات Chat API

2. في حقل اسم التطبيق، اكتب Contact Manager.

3. في عنوان URL الخاص بالأفاتار، اكتب https://developers.google.com/chat/images/contact-icon.png.

4. في حقل الوصف، اكتب Manage your personal and business contacts.

5. انقر على مفتاح التبديل تفعيل الميزات التفاعلية لتفعيل هذا الإعداد.

6. ضمن الوظائف، اختَر الانضمام إلى المساحات والمحادثات الجماعية.

7. ضِمن إعدادات الربط، اختَر Apps Script.

8. في حقل معرّف النشر، الصِق معرّف نشر "برمجة تطبيقات Google" الذي نسخته في القسم السابق عند إنشاء عملية نشر "برمجة تطبيقات Google".

9. ضمن المشغّلات، اضبط الدوال التي تستجيب لتفاعلات المستخدمين:

   • بالنسبة إلى مشغّل الرسالة، أدخِل onMessage.
   • بالنسبة إلى مشغّل أمر التطبيق، أدخِل onAppCommand.

10. ضمن الأوامر، اضبط الأوامر التي تبدأ بشرطة مائلة /about و/addContact:

    1. انقر على إضافة أمر لإعداد الأمر الأول الذي يبدأ بشرطة مائلة.
    2. في معرّف الأمر، اكتب 1.
    3. في حقل الوصف، اكتب Learn how to use this Chat app to manage your contacts.
    4. ضمن نوع الأمر، اختَر Slash command.
    5. في اسم الأمر الذي يبدأ بشرطة مائلة، اكتب /about.
    6. انقر على تم.
    7. انقر على إضافة أمر يبدأ بشرطة مائلة لإعداد أمر آخر يبدأ بشرطة مائلة.
    8. في معرّف الأمر، اكتب 2.
    9. في حقل الوصف، اكتب Submit information about a contact.
    10. ضمن نوع الأمر، اختَر Slash command.
    11. في اسم الأمر الذي يبدأ بشرطة مائلة، اكتب /addContact.
    12. اختَر يفتح مربّع حوار.
    13. انقر على تم.

11. ضمن إذن الوصول، ضَع علامة في مربّع الاختيار إتاحة تطبيق Chat هذا لمستخدمين ومجموعات محدّدين في YOUR DOMAIN وأدخِل عنوان بريدك الإلكتروني.

12. ضمن السجلات، اختَر تسجيل الأخطاء في خدمة "التسجيل".

13. انقر على حفظ. ستظهر رسالة "تم حفظ الإعدادات".

تطبيق Chat جاهز للتثبيت والاختبار في Chat.

اختبار تطبيق Chat

لاختبار تطبيق Chat، افتح مساحة رسالة مباشرة باستخدام تطبيق Chat وأرسِل رسالة:

1. افتح Google Chat باستخدام حساب Google Workspace الذي قدّمته عند إضافة نفسك كمختبِر موثوق به.

   الانتقال إلى Google Chat

2. انقر على add محادثة جديدة.
3. في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.

4. اختَر تطبيق Chat من النتائج. سيتم فتح رسالة مباشرة.

1. في الرسالة المباشرة الجديدة مع تطبيق Chat، اكتب /addContact واضغط على Enter.

2. في مربّع الحوار الذي يفتح، أدخِل معلومات الاتصال:

   1. في حقل النص الاسم الأول واسم العائلة، أدخِل اسمًا.
   2. في أداة اختيار التاريخ تاريخ الميلاد، اختَر تاريخًا.
   3. ضمن نوع جهة الاتصال، انقر على زر الاختيار العمل أو شخصي.

3. انقر على المراجعة والإرسال.

4. في مربّع حوار التأكيد، راجِع المعلومات التي أرسلتها وانقر على إرسال. يرد تطبيق Chat برسالة نصية تقول ✅ CONTACT NAME has been added to your contacts..

5. يمكنك أيضًا اختياريًا اختبار نموذج التواصل وإرساله بالطرق التالية:

   • استخدِم الأمر /about الذي يبدأ بشرطة مائلة. يرد تطبيق المحادثة برسالة نصية وزر أداة ملحقة مكتوب عليه Add a contact. يمكنك النقر على الزرّ لفتح مربّع حوار يتضمّن نموذج تواصل.
   • أرسِل رسالة مباشرة إلى تطبيق Chat بدون استخدام أمر يبدأ بشرطة مائلة، مثل Hello. يردّ تطبيق Chat بنص وبطاقة تحتوي على نموذج تواصل.

تَنظيم

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

1. في Google API Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة menu > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.

   الانتقال إلى "إدارة الموارد"

2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف delete.
3. في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

المواضيع ذات الصلة

• الردّ على الأوامر
• جمع المعلومات ومعالجتها من مستخدمي Google Chat
• فتح مربّعات الحوار التفاعلية
• استكشاف نماذج أخرى من تطبيقات Google Chat