توضّح هذه الصفحة كيفية إنشاء وإرسال رسالة بطاقة الصفحة الرئيسية في التطبيق لتطبيق Chat. و"الصفحة الرئيسية للتطبيق" هي رسالة بطاقة قابلة للتخصيص يرسلها تطبيق Chat إلى مستخدم عند فتح رسالة مباشرة باستخدام تطبيق Chat.
على سبيل المثال، يمكنك ضبط رسالة بطاقة الصفحة الرئيسية للتطبيق لتضمين نصائح للتفاعل مع تطبيق Chat باستخدام الأوامر التي تبدأ بشرطة مائلة. بالنسبة إلى المستخدمين النهائيين، لا تتوفّر الصفحة الرئيسية للتطبيق إلا في الرسالة المباشرة لتطبيق Chat إذا أتاح مطوّر التطبيق هذه الميزة.
يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat، وذلك باتّباع الخطوات التالية:
فتح أداة إنشاء البطاقاتالمتطلبات الأساسية
Python
- حساب على Google Workspace يمكنه الوصول إلى Google Chat
- تطبيق Chat منشور. يمكنك الاطّلاع على quickstart لإنشاء تطبيق Chat.
- تطبيق Google Chat تم إعداده للتفاعل. لمزيد من المعلومات، راجِع ضبط تطبيق Google Chat لتلقّي أحداث التفاعل.
Apps Script
- حساب على Google Workspace يمكنه الوصول إلى Google Chat
- هو تطبيق Chat منشور. لإنشاء تطبيق في Chat، اتّبِع quickstart.
- تطبيق Google Chat تم إعداده للتفاعل. لمزيد من المعلومات، راجِع ضبط تطبيق Google Chat لتلقّي أحداث التفاعل.
الضبط في Google Cloud Console
Python
في Google Cloud Console، انتقِل إلى القائمة > المزيد من المنتجات > Google Workspace > مكتبة المنتجات > Google Chat API.
انقر على إدارة، ثم انقر على علامة التبويب ضبط.
فعِّل الصفحة الرئيسية لتطبيق الدعم.
ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.
في الحقل عنوان URL للصفحة الرئيسية للتطبيق، أضِف عنوان URL. عادةً ما تكون هذه القيمة هي نفسها عنوان URL داخل عنوان URL داخل التطبيق يتم استدعاء عنوان URL هذا لأحداث
APP_HOME
.انقر على حفظ.
Apps Script
في Google Cloud Console، انتقِل إلى القائمة > المزيد من المنتجات > Google Workspace > مكتبة المنتجات > Google Chat API.
انقر على إدارة، ثم انقر على علامة التبويب ضبط.
ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.
انقر على حفظ.
إعداد تطبيق Chat
اضبط تطبيق Chat لإرسال رسالة بطاقة جديدة للصفحة الرئيسية للتطبيق.
Python
عندما يفتح مستخدم رسالة مباشرة من تطبيق في Chat، يتم إرسال
حدث APP_HOME
إلى تطبيق Chat. وعندما
يتلقّى أحد تطبيقات Chat هذا الحدث، يتم عرض نسخة JSON من
RenderActions
مع التنقّل pushCard
.
@app.route('/', methods=['POST'])
def on_event():
event = request.get_json()
chat = event.get('chat')
if chat is not None:
return handle_chat_event(event)
def handle_chat_event(event):
if event['chat'].get('type') == 'APP_HOME':
return get_app_home_card()
def get_app_home_card():
return {
"action": {
"navigations": [
{
"pushCard": {
"sections": [
{
"widgets": [
{
"buttonList": {
"buttons": [
{
"text": "Open documentation",
"onClick": {
"openLink": {
"url": "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
}
}
]
}
}
Apps Script
في هذا المثال، يتم إرسال رسالة بطاقة من خلال عرض البطاقة JSON. يمكنك أيضًا استخدام خدمة بطاقة "برمجة تطبيقات Google".
نفِّذ دالة onAppHome
لعرض مثيل JSON لـ
RenderActions
مع التنقل في pushCard
:
// "onAppHome" is the pre-defined name of the callback that the Chat servers
// execute.
function onAppHome() {
return {
action: {
navigations: [
{
pushCard: getCard()
}
]
}
};
}
function getCard() {
return {
sections: [
{
widgets: [
{
buttonList: {
buttons: [
{
text: "Open documentation",
onClick: {
openLink: {
url: "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
};
}
تعديل رسالة البطاقة الرئيسية للتطبيق
يمكن تحديث رسالة البطاقة الرئيسية للتطبيق عندما يرسل المستخدم معلومات في رسالة بطاقة أو يغلق مربع حوار. على سبيل المثال، رسالة بطاقة الصفحة الرئيسية الأولية
للتطبيق هي رسالة ترحيب تطلب من المستخدم ملء نموذج بالمعلومات. بعد إكمال المستخدم للنموذج، يتم
إرسال رسالة محدثة عن بطاقة الصفحة الرئيسية للتطبيق. يجب
عرض التحديث مع مثيل
RenderActions
الذي يحتوي على شريط تنقّل updateCard
.
Python
بالنسبة إلى تطبيقات HTTP، يشبه تعديل رسالة البطاقة الرئيسية للتطبيق معالجة المعلومات التي أدخلها المستخدمون، ولكن يجب عرض RenderActions
. يمثّل invokedFunction
اسم الدالة التي تم استدعاؤها المرتبطة بالأداة Card
. لمزيد من المعلومات،
يُرجى الاطّلاع على
CommonEventObject
.
في المثال التالي، توضّح علامة التبويب submitForm
أنّ المستخدم قد أرسل بيانات النموذج:
@app.route('/', methods=['POST'])
def on_event():
event = request.get_json()
chat = event.get('chat')
if chat is not None:
return handle_chat_event(event)
def handle_chat_event(event):
if event['chat'].get('type') == 'SUBMIT_FORM':
event_object = event.get('commonEventObject')
if event_object is not None:
// Forms
if 'submitForm' == event_object.get('invokedFunction'):
return {
'render_actions': {
'action': {
'navigations': [{
'updateCard': get_update_card()
}]
}
}
}
def get_update_card():
return {
"action": {
"navigations": [{
"pushCard": {
"sections": [{
"widgets": [{
"buttonList": {
"buttons": [{
"text": "Open documentation",
"onClick": {
"openLink": {
"url": "https://developers.google.com/chat"
}
},
}]
}
}]
}]
}
}]
}
}
Apps Script
في هذا المثال، يتم إرسال رسالة بطاقة من خلال عرض البطاقة JSON. يمكنك أيضًا استخدام خدمة بطاقة "برمجة تطبيقات Google".
// Called from elsewhere (i.e. on button press).
function updateAppHomeCard(event) {
return {
render_actions: {
action: {
navigations: [
{
updateCard: getCard()
}
]
}
}
}
}
function getCard() {
return {
sections: [
{
widgets: [
{
buttonList: {
buttons: [
{
text: "Open documentation",
onClick: {
openLink: {
url: "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
};
}
القيود
بشكل عام، لا يتوفّر navigation
لتطبيقات Chat. لا يمكنك إرجاع حزمة من البطاقات.
لا يتوفّر سوى pushCard
(للرد الأولي) وupdateCard
(للتحديثات) لتطبيقات Chat.
مواضيع ذات صلة
لفتح مربّع حوار، استخدِم التفاعل
OPEN_DIALOG
. لمزيد من المعلومات، راجِع فتح مربّع حوار استجابةً لرسالة بطاقة الصفحة الرئيسية للتطبيق.لإغلاق مربّع حوار، استخدِم تفاعل
CLOSE_DIALOG
لإغلاق مربّع الحوار وعُد إلى رسالة بطاقة الصفحة الرئيسية في التطبيق أو استخدِم التفاعلCLOSE_DIALOG_EXECUTE
لإغلاق مربّع الحوار وإعادة تحميل رسالة بطاقة الصفحة الرئيسية للتطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على الرد على مربّع حوار لرسائل بطاقة الصفحة الرئيسية للتطبيق.للحصول على مثال حول كيفية إنشاء رسالة بطاقة الصفحة الرئيسية للتطبيق وإرسالها، يمكنك الاطّلاع على تطبيق Chat الخاص بإدارة المشاكل في الدرس التطبيقي حول الترميز إنشاء تطبيقات في Google Chat باستخدام Gemini.