إرسال رسالة بطاقة الصفحة الرئيسية للتطبيق إلى تطبيق Google Chat

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

بطاقة الصفحة الرئيسية للتطبيق تتضمّن رسالتَين

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

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat، وذلك باتّباع الخطوات التالية:

فتح أداة إنشاء البطاقات

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

Python

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

الضبط في Google Cloud Console

Python

  1. في Google Cloud Console، انتقِل إلى القائمة > المزيد من المنتجات > Google Workspace > مكتبة المنتجات > Google Chat API.

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

  2. انقر على إدارة، ثم انقر على علامة التبويب ضبط.

  3. فعِّل الصفحة الرئيسية لتطبيق الدعم.

  4. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

  5. في الحقل عنوان URL للصفحة الرئيسية للتطبيق، أضِف عنوان URL. عادةً ما تكون هذه القيمة هي نفسها عنوان URL داخل عنوان URL داخل التطبيق يتم استدعاء عنوان URL هذا لأحداث APP_HOME.

  6. انقر على حفظ.

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

  1. في Google Cloud Console، انتقِل إلى القائمة > المزيد من المنتجات > Google Workspace > مكتبة المنتجات > Google Chat API.

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

  2. انقر على إدارة، ثم انقر على علامة التبويب ضبط.

  3. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

  4. انقر على حفظ.

إعداد تطبيق 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"
                            }
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }

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

في هذا المثال، يتم إرسال رسالة بطاقة من خلال عرض البطاقة 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"
                                      }
                                  },
                              }]
                          }
                      }]
                  }]
              }
          }]
      }
  }

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

في هذا المثال، يتم إرسال رسالة بطاقة من خلال عرض البطاقة 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.