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

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

بالنسبة إلى المستخدمين النهائيين، لا تتوفّر الصفحة الرئيسية للتطبيق إلا في الرسالة المباشرة الخاصة بالتطبيقات على 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 الخاص بك. وعندما يتلقّى أحد التطبيقات هذا الحدث، يتم عرض نسخة JSON لـ RenderActions مع التنقّل push_card.

يعرض المثال التالي حدثًا:

@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 "Card v2" representing App Home.

يعرض المثال التالي بطاقة تم إعدادها لتضمين رابط زر يؤدي إلى الوثائق:

{
  action: {
    navigations: [
      {
        push_card: {
          sections: [
            {
              widgets: [
                {
                  buttonList: {
                    buttons: [
                      {
                        text: "Open documentation",
                        onClick: {
                          openLink: {
                            url: "https://developers.google.com/chat"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

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

نفِّذ دالة onAppHome لعرض مثيل JSON لـ RenderActions مع التنقل في push_card:

// "onAppHome" is the pre-defined name of the callback that the Chat servers
// execute.
function onAppHome() {
  return {
    action: {
      navigations: [
        {
          push_card: getCard()
        }
      ]
    }
  };
}

function getCard() {
  return {
    sections: [
      {
        widgets: [
          {
            buttonList: {
              buttons: [
                {
                  text: "Open documentation",
                  onClick: {
                    openLink: {
                      url: "https://developers.google.com/chat"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  };
}

تعديل رسالة البطاقة الرئيسية للتطبيق

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

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': [{
                'update_card': get_update_card
              }]
            }
          }
        }

def get_update_card:
  // Return "Card v2" representing App Home.
  ...

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

// Called from elsewhere (i.e. on button press).
function updateAppHomeCard(event) {
  return {
    render_actions: {
      action: {
        navigations: [
          {
            update_card: getCard()
          }
        ]
      }
    }
  }
}

function getCard() {
  // Return "Card v2" representing App Home.
  ...
}