يوضّح هذا الدليل كيف يمكن لتطبيقات Google Chat جمع المعلومات من المستخدمين ومعالجتها من خلال إنشاء إدخالات نماذج في واجهات مستندة إلى البطاقات.
تطلب تطبيقات المحادثات معلومات من المستخدمين لتنفيذ إجراءات داخل Chat أو خارجه، بما في ذلك بالطرق التالية:
- اضبط الإعدادات. على سبيل المثال، للسماح للمستخدمين بتخصيص إعدادات الإشعارات أو ضبط تطبيق Chat وإضافته إلى مساحة واحدة أو أكثر.
- إنشاء معلومات أو تعديلها في تطبيقات Google Workspace الأخرى على سبيل المثال، السماح للمستخدمين بإنشاء حدث في "تقويم Google".
- السماح للمستخدمين بالوصول إلى الموارد وتعديلها في تطبيقات أو خدمات ويب أخرى على سبيل المثال، يمكن أن يساعد تطبيق Chat المستخدمين في تعديل حالة طلب الدعم مباشرةً من مساحة في Chat.
المتطلبات الأساسية
HTTP
تطبيق Google Chat يتلقّى تفاعلات المستخدمين ويردّ عليها. لإنشاء أحدها، أكمل البداية السريعة لبروتوكول HTTP.
برمجة التطبيقات
تطبيق Google Chat يتلقّى تفاعلات المستخدمين ويردّ عليها. لإنشاء تطبيق، عليك إكمال دليل البدء السريع في برمجة تطبيقات.
إنشاء نماذج باستخدام البطاقات
لجمع المعلومات، تصمّم تطبيقات Chat نماذج ومدخلاتها، وتنشئها في بطاقات. لعرض البطاقات للمستخدمين، يمكن لتطبيقات Chat استخدام واجهات Chat التالية:
- الرسائل التي تحتوي على بطاقة واحدة أو أكثر
- الصفحات الرئيسية: وهي بطاقة تظهر من علامة التبويب الصفحة الرئيسية في الرسائل المباشرة مع تطبيق Chat.
- مربّعات الحوار، وهي بطاقات تفتح في نافذة جديدة من الرسائل وصفحات البداية
يمكن لتطبيقات الدردشة إنشاء البطاقات باستخدام التطبيقات المصغّرة التالية:
عناصر واجهة مستخدم لإدخال النماذج تطلب معلومات من المستخدمين يمكنك اختياريًا إضافة التحقّق من الصحة إلى أدوات إدخال النماذج للتأكّد من أنّ المستخدمين يدخلون المعلومات وينسّقونها بشكل صحيح. يمكن لتطبيقات الدردشة استخدام عناصر التحكّم التالية لإدخال النماذج:
- إدخالات نصية
(
textInput) لنص حر أو مقترَح - عناصر إدخال التحديد
(
selectionInput) هي عناصر واجهة مستخدم قابلة للتحديد، مثل مربّعات الاختيار وأزرار الاختيار والقوائم المنسدلة. يمكن أيضًا أن تملأ أدوات إدخال الاختيار العناصر وتقترحها من بيانات Google Workspace (مثل مساحة في Chat) أو مصدر بيانات ديناميكي. للاطّلاع على التفاصيل، راجِع القسمَين التاليَين إضافة قائمة منسدلة وإضافة قائمة اختيار متعدّد. - أدوات اختيار التاريخ والوقت
(
dateTimePicker) لإدخالات التاريخ والوقت
- إدخالات نصية
(
أداة زر ليتمكّن المستخدمون من إرسال القيم التي أدخلوها في البطاقة بعد أن ينقر المستخدم على الزر، يمكن لتطبيق Chat معالجة المعلومات التي يتلقّاها.
في المثال التالي، تجمع بطاقة معلومات الاتصال باستخدام حقل إدخال نصي وأداة اختيار التاريخ والوقت وحقل إدخال اختيار:
للاطّلاع على المزيد من الأمثلة على الأدوات التفاعلية التي يمكنك استخدامها لجمع المعلومات، راجِع تصميم بطاقة أو مربّع حوار تفاعلي.
إضافة قائمة منسدلة
لتخصيص عناصر التحديد أو السماح للمستخدمين باختيار عنصر واحد من مصدر بيانات ديناميكي، يمكن لتطبيقات Chat استخدام القوائم المنسدلة، وهي نوع من عناصر واجهة المستخدم SelectionInput. على سبيل المثال، تعرض البطاقة التالية قائمة منسدلة يمكن للمستخدمين من خلالها الاختيار بشكل ديناميكي من قائمة جهات الاتصال:
يمكنك ملء عناصر قائمة منسدلة من مصادر البيانات التالية:
- بيانات Google Workspace، والتي تشمل المستخدمين أو مساحات Chat
- مصادر البيانات الخارجية، مثل قاعدة بيانات ارتباطية
ملء العناصر من مصدر بيانات Google Workspace
لملء العناصر من مصادر بيانات Google Workspace، مثل مستخدمي Google Workspace، حدِّد الحقل platformDataSource ضمن العنصر DataSourceConfig. على عكس أنواع إدخال التحديد الأخرى، يمكنك حذف عناصر SelectionItem، لأنّ عناصر التحديد هذه يتم الحصول عليها بشكل ديناميكي من Google Workspace.
يعرض الرمز التالي قائمة منسدلة بمستخدمي Google Workspace:
JSON
{
"sections": [
{
"header": "Section Header",
"widgets": [
{
"selectionInput": {
"name": "contacts",
"type": "DROPDOWN",
"label": "Select contact from organization",
"data_source_configs": [
{
"platformDataSource": {
"commonDataSource": "USER"
},
"min_characters_trigger": 1
}
]
}
}
]
}
]
}
ملء العناصر من مصدر بيانات خارجي
يمكن أيضًا أن تملأ القوائم المنسدلة العناصر من مصدر بيانات تابع لجهة خارجية أو مصدر بيانات خارجي. لاستخدام مصدر بيانات خارجي، عليك تحديد حقل
remoteDataSource
ضمن عنصر
DataSourceConfig
يحتوي على الدالة التي تستعلم عن العناصر وتعرضها من مصدر البيانات.
للحدّ من الطلبات المُرسَلة إلى مصدر بيانات خارجي، يمكنك تضمين العناصر المقترَحة التي تظهر في القائمة المنسدلة قبل أن يكتب المستخدمون في القائمة. لملء العناصر المقترَحة من مصدر بيانات خارجي، حدِّد عناصر ثابتة
SelectionItem.
يعرض الرمز التالي قائمة منسدلة تستعلم عن العناصر وتملأها من مصدر بيانات خارجي:
JSON
{
"sections": [
{
"header": "Section Header",
"widgets": [
{
"selectionInput": {
"name": "crm_leads",
"type": "DROPDOWN",
"label": "Select CRM Lead",
"data_source_configs": [
{
"remoteDataSource": {
"function": "getCrmLeads"
},
"min_characters_trigger": 2
}
],
"items": [
{
"text": "Suggested Lead 1",
"value": "lead-1"
}
]
}
}
]
}
]
}
للاطّلاع على مثال كامل يوضّح كيفية عرض العناصر المقترَحة، راجِع القسم اقتراح عناصر التحديد.
إضافة قائمة اختيار متعدّد
لتخصيص عناصر التحديد أو السماح للمستخدمين بتحديد عناصر من مصدر بيانات ديناميكي، يمكن لتطبيقات Chat استخدام قوائم الاختيار المتعدد، وهي نوع من عناصر واجهة المستخدم SelectionInput. على سبيل المثال، تعرض البطاقة التالية قائمة اختيار متعدّد
يمكن للمستخدمين من خلالها الاختيار بشكل ديناميكي من قائمة جهات الاتصال:
يمكنك ملء عناصر قائمة اختيار متعدّد من مصادر البيانات التالية:
- بيانات Google Workspace، والتي تشمل المستخدمين أو مساحات Chat التي يكون المستخدم عضوًا فيها لا تعرض القائمة سوى العناصر من مؤسسة Google Workspace نفسها.
- مصادر البيانات الخارجية، مثل قاعدة بيانات ارتباطية على سبيل المثال، يمكنك استخدام قوائم الاختيار المتعدد لمساعدة المستخدم في الاختيار من قائمة بعملاء محتملين من نظام إدارة علاقات العملاء (CRM).
ملء العناصر من مصدر بيانات Google Workspace
لاستخدام مصادر بيانات Google Workspace، حدِّد الحقل
platformDataSource
في أداة SelectionInput. على عكس أنواع إدخال التحديد الأخرى، يمكنك حذف عناصر SelectionItem، لأنّ عناصر التحديد هذه يتم الحصول عليها بشكل ديناميكي من Google Workspace.
يعرض الرمز التالي قائمة اختيار متعدّد لمستخدمي Google Workspace.
لملء المستخدمين، يضبط إدخال التحديد commonDataSource على USER:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
يعرض الرمز التالي قائمة اختيار متعدّد لمساحات Chat. لملء المساحات، يحدّد إدخال التحديد الحقل hostAppDataSource. تضبط قائمة الاختيار المتعدد أيضًا
defaultToCurrentSpace على true، ما يجعل المساحة الحالية هي الخيار التلقائي
في القائمة:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
ملء العناصر من مصدر بيانات خارجي
يمكن أيضًا أن تملأ قوائم الاختيار المتعدد العناصر من مصدر بيانات خارجي أو تابع لجهة خارجية. لاستخدام مصدر بيانات خارجي، عليك تحديد حقل
externalDataSource
في أداة SelectionInput التي تحتوي على الدالة التي تستعلم عن العناصر من مصدر البيانات وتعرضها.
للحدّ من الطلبات المُرسَلة إلى مصدر بيانات خارجي، يمكنك تضمين العناصر المقترَحة التي تظهر في قائمة الاختيار المتعدّد قبل أن يكتب المستخدمون في القائمة. على سبيل المثال، يمكنك ملء جهات الاتصال التي بحث عنها المستخدم مؤخرًا. لملء العناصر المقترَحة من مصدر بيانات خارجي، حدِّد عناصر ثابتة
SelectionItem.
تعرض عيّنة الرمز البرمجي التالية قائمة اختيار متعدّد تستعلم عن العناصر وتملأها من مصدر بيانات خارجي:
Node.js
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
Python
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
جافا
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
برمجة التطبيقات
يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".
للاطّلاع على مثال كامل يوضّح كيفية عرض العناصر المقترَحة، راجِع القسم اقتراح عناصر التحديد.
تلقّي البيانات من التطبيقات المصغّرة التفاعلية
عندما ينقر المستخدمون على زر، يتم تشغيل الإجراء الخاص به في تطبيقات Chat مع معلومات حول التفاعل. في
commonEventObject
للحمولة الخاصة بالحدث، يحتوي العنصر formInputs على أي قيم يُدخلها المستخدم.
يمكنك استرداد القيم من العنصر
event.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 |
بعد أن يتلقّى تطبيق Chat البيانات، يمكنه إجراء أيّ مما يلي:
- بالنسبة إلى البطاقات التي تحتوي على قائمة اختيار متعدّد، يمكنك ملء العناصر أو اقتراحها استنادًا إلى ما يكتبه المستخدم في القائمة.
- نقل البيانات إلى بطاقة أخرى ليتمكّن المستخدم من مراجعة معلوماته أو الانتقال إلى القسم التالي من النموذج
- الردّ على المستخدم لتأكيد أنّه أكمل النموذج بنجاح
اقتراح عناصر التحديد
إذا كانت البطاقة تحتوي على قائمة اختيار متعدّد أو قائمة منسدلة
تتضمّن عناصر من مصدر بيانات خارجي،
يمكن لتطبيق Chat عرض عناصر مقترَحة استنادًا إلى ما يكتبه المستخدمون في القائمة. على سبيل المثال، إذا بدأ المستخدم بكتابة Atl لقائمة
تتضمّن مدنًا في الولايات المتحدة، يمكن لتطبيق
Chat أن يقترح تلقائيًا Atlanta قبل أن ينهي المستخدم
الكتابة. يمكن أن يقترح تطبيق Chat ما يصل إلى 100 عنصر.
لاقتراح عناصر وملء حقل إدخال الاختيار بشكل ديناميكي، يجب أن تحدّد الأداة SelectionInput في البطاقة دالة تستعلم عن مصدر البيانات الخارجي. بالنسبة إلى القوائم المتعددة الاختيارات، عليك تحديد حقل
externalDataSource. بالنسبة إلى القوائم المنسدلة، عليك تحديد الحقل
remoteDataSource
ضمن عنصر
DataSourceConfig.
يمكنك أيضًا ضبط عدد الأحرف التي يكتبها المستخدم قبل أن تعرض القائمة اقتراحات. بالنسبة إلى قوائم الاختيار المتعدد، اضبط الحقل multiSelectMinQueryLength. بالنسبة إلى القوائم المنسدلة، اضبط الحقل min_characters_trigger ضمن DataSourceConfig.
لعرض العناصر المقترَحة، يجب أن تنفّذ الدالة ما يلي:
- التعامل مع عنصر حدث يتلقّاه تطبيق Chat عندما يكتب المستخدمون في القائمة
- من عنصر الحدث، احصل على القيمة التي يكتبها المستخدم، والتي يتم تمثيلها في الحقل
event.commonEventObject.parameters["autocomplete_widget_query"]. - استعلم عن مصدر البيانات باستخدام بيانات أدخلها المستخدم للحصول على
SelectionItemsواحد أو أكثر لاقتراحه على المستخدم. - يمكنك عرض العناصر المقترَحة من خلال عرض الإجراء
RenderActionsمع العنصرmodifyCard.
يوضّح نموذج الرمز البرمجي التالي كيفية اقتراح تطبيق Chat بشكل ديناميكي لعناصر في قائمة الاختيار المتعدد ضمن بطاقة. عندما يكتب المستخدم في القائمة، تستعلم الدالة أو نقطة النهاية المقدَّمة في حقل externalDataSource للأداة عن مصدر بيانات خارجي، وتقترح عناصر يمكن للمستخدم اختيارها.
Node.js
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
Python
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
جافا
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تجري طلب بحث في مصدر البيانات الخارجي.
برمجة التطبيقات
يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".
نقل البيانات إلى بطاقة أخرى
بعد أن يرسل المستخدم معلومات من بطاقة، قد تحتاج إلى عرض بطاقات إضافية لتنفيذ أي مما يلي:
- ساعد المستخدمين في إكمال النماذج الأطول من خلال إنشاء أقسام مميزة.
- اسمح للمستخدمين بمعاينة المعلومات وتأكيدها من البطاقة الأولية، حتى يتمكّنوا من مراجعة إجاباتهم قبل إرسالها.
- ملء الأجزاء المتبقية من النموذج بشكل ديناميكي على سبيل المثال، لتشجيع المستخدمين على إنشاء موعد، يمكن لتطبيق Chat عرض بطاقة أولية تطلب سبب الموعد، ثم ملء بطاقة أخرى تعرض الأوقات المتاحة استنادًا إلى نوع الموعد.
لنقل إدخال البيانات من البطاقة الأولية، يمكنك إنشاء أداة button
باستخدام
actionParameters
التي تحتوي على name للأداة والقيمة التي يدخلها المستخدم، كما هو موضّح
في المثال التالي:
Node.js
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تعالج نقرات الأزرار.
Python
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تعالج نقرات الأزرار.
جافا
استبدِل FUNCTION_URL بنقطة نهاية HTTP التي تعالج نقرات الأزرار.
برمجة التطبيقات
يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".
عندما ينقر المستخدم على الزر، يتلقّى تطبيق Chat عنصر حدث يمكنك من خلاله تلقّي البيانات.
الردّ على نموذج تم إرساله
بعد تلقّي البيانات من رسالة بطاقة أو مربّع حوار، يردّ تطبيق Chat إما بتأكيد الاستلام أو بعرض خطأ.
في المثال التالي، يرسل تطبيق Chat رسالة نصية لتأكيد استلامه بنجاح نموذجًا تم إرساله من رسالة بطاقة.
Node.js
Python
جافا
برمجة التطبيقات
يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".
لمعالجة مربّع حوار وإغلاقه، عليك عرض عنصر
RenderActions
يحدّد ما إذا كنت تريد إرسال رسالة تأكيد أو تعديل الرسالة أو البطاقة الأصلية أو إغلاق مربّع الحوار فقط. للاطّلاع على الخطوات، يُرجى قراءة المقالة
إغلاق مربّع حوار.
تحديد المشاكل وحلّها
يقدّم هذا القسم خطوات تحديد المشاكل وحلّها لرموز أخطاء معيّنة وسلوكيات وقت التشغيل عند التفاعل مع مربّعات الحوار في Chat.
تعرض تفاعلات مربّع الحوار الخطأ "حدث خطأ غير محدَّد أثناء استدعاء الإضافة"
عند التفاعل مع مربّع حوار، إذا ظهرت لك سجلّات أخطاء تتضمّن الرسالة "حدث خطأ غير محدّد عند استدعاء الإضافة" والرمز 13، يشير ذلك عادةً إلى حدوث خطأ داخلي أو تعذُّر معالجة طلب أو عرض ردّ صالح من خلال نقطة نهاية HTTP لتطبيق Chat.
لتحديد هذه المشكلة وحلّها، يُرجى اتّباع الخطوات التالية:
- راجِع سجلّات نقطة نهاية HTTP بحثًا عن أي استثناءات أو أعطال لم تتم معالجتها.
- تأكَّد من أنّ نقطة النهاية تستجيب للطلبات في غضون 30 ثانية. إذا استغرق تشغيل نقطة النهاية أكثر من 30 ثانية، لن يتمكّن Chat من معالجة الردّ وستتعذّر عملية التفاعل. لمزيد من التفاصيل، يُرجى الاطّلاع على حدود المعدّل وأفضل الممارسات.
- تأكَّد من أنّ نقطة النهاية تعرض ردًا صالحًا. بالنسبة إلى عمليات إرسال مربّعات الحوار، يجب أن يعرض نقطة النهاية كائن
RenderActionsبتنسيق JSON صحيح. إذا كانت الاستجابة غير صالحة أو لا تحتوي على الحقول المطلوبة، قد يتعذّر التفاعل مع مربّع الحوار.
عندما يعرض تطبيق أو بطاقة في Google Chat خطأً، تعرض واجهة Chat رسالة "حدث خطأ". أو "تعذّرت معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن قد ينتج عن تطبيق Chat أو البطاقة نتيجة غير متوقّعة، مثلاً قد لا تظهر رسالة البطاقة.
على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات سجلّات لمساعدتك في إصلاح الأخطاء عند تفعيل تسجيل الأخطاء لتطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتحديد المشاكل فيها، يُرجى الاطّلاع على تحديد المشاكل في Google Chat وحلّها.
المواضيع ذات الصلة
- عرض نموذج "إدارة جهات الاتصال"، وهو تطبيق في Chat يطلب من المستخدمين ملء نموذج تواصل من رسائل البطاقات ومربّعات الحوار
- فتح مربّعات الحوار التفاعلية
تطبيقات Chat التي ليست إضافات: قراءة بيانات النماذج التي أدخلها المستخدمون في البطاقات
تنطبق المستندات التالية على تطبيقات Chat التي ليست إضافات Google Workspace. لنقل تطبيق Chat ليس إضافة، يُرجى الاطّلاع على تحويل تطبيق Google Chat إلى إضافة Google Workspace.
إنشاء نماذج باستخدام البطاقات
للاطّلاع على مثال لتطبيق Chat ليس إضافة ويستخدم نموذج اتصال يتضمّن إدخال نصي وأداة اختيار التاريخ والوقت وأداة اختيار، راجِع الرمز التالي:
Node.js
Python
جافا
برمجة التطبيقات
تلقّي البيانات من التطبيقات المصغّرة التفاعلية
عندما ينقر المستخدمون على زر، تتلقّى تطبيقات Chat التي ليست إضافات حدث تفاعل يعتمد على موقع الزر:
إذا كان الزرّ في رسالة أو مربّع حوار، تتلقّى تطبيقات Chat التي ليست إضافات حدث تفاعل
CARD_CLICKEDيتضمّن معلومات حول التفاعل. تحتوي حمولة أحداث التفاعلCARD_CLICKEDعلى عنصرcommon.formInputs(event.common.formInputs) يتضمّن أي قيم يُدخلها المستخدم.يمكنك استرداد القيم من العنصر
common.formInputs.WIDGET_NAME، حيث WIDGET_NAME هو الحقلnameالذي حدّدته للأداة. يتم عرض القيم كنوع بيانات محدّد للأداة (يتم تمثيله ككائنInputs).يوضّح ما يلي جزءًا من حدث تفاعُل
CARD_CLICKEDحيث أدخل المستخدِم قيمًا لكل أداة:HTTP
{ "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"] }}} }} }إذا كان الزرّ على الصفحة الرئيسية، تتلقّى تطبيقات Chat التي ليست إضافات حدث تفاعل
SUBMIT_FORM. يحتوي حمولة حدث التفاعل على عنصرcommonEventObject.formInputs(event.commonEventObject.formInputs) مع أي قيم يُدخلها المستخدم.يمكنك استرداد القيم من العنصر
commonEventObject.formInputs.WIDGET_NAME، حيث WIDGET_NAME هو الحقلnameالذي حدّدته للأداة. يتم عرض القيم كنوع بيانات محدّد للأداة (يتم تمثيله ككائنInputs).يوضّح ما يلي جزءًا من حدث تفاعُل
SUBMIT_FORMحيث أدخل المستخدِم قيمًا لكل أداة:HTTP
{ "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"] }}} }} }
لتلقّي البيانات، يعالج تطبيق Chat غير المضاف حدث التفاعل للحصول على القيم التي يدخلها المستخدمون في الأدوات. يوضّح الجدول التالي كيفية الحصول على قيمة عنصر إدخال نموذج معيّن. بالنسبة إلى كل أداة، يعرض الجدول نوع البيانات الذي تقبله الأداة، والمكان الذي يتم فيه تخزين القيمة في حدث التفاعل، وقيمة مثال.
| تطبيق مصغّر لإدخال النموذج | نوع البيانات المُدخَلة | قيمة الإدخال من حدث التفاعل | مثال على القيمة |
|---|---|---|---|
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 |
نقل البيانات إلى بطاقة أخرى
لنقل البيانات المُدخَلة من البطاقة الأولية في تطبيق Chat ليس إضافة، أنشئ أداة button باستخدام actionParameters التي تحتوي على name للأداة والقيمة التي يدخلها المستخدم، كما هو موضّح في المثال التالي:
Node.js
Python
جافا
برمجة التطبيقات
عندما ينقر المستخدم على الزر، يتلقّى تطبيق Chat الذي ليس إضافة حدث تفاعل CARD_CLICKED يمكنك من خلاله تلقّي البيانات.
الردّ على نموذج تم إرساله
في المثال التالي، يرسل تطبيق Chat غير إضافي رسالة نصية لتأكيد استلامه بنجاح نموذجًا تم إرساله من مربّع حوار أو رسالة بطاقة:
Node.js
Python
جافا
برمجة التطبيقات
لمعالجة مربّع حوار وإغلاقه في تطبيق Chat ليس إضافة، عليك عرض عنصر ActionResponse يحدّد ما إذا كنت تريد إرسال رسالة تأكيد أو تعديل الرسالة أو البطاقة الأصلية أو إغلاق مربّع الحوار فقط. للاطّلاع على الخطوات، يُرجى قراءة المقالة
إغلاق مربّع حوار.