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

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

بطاقة الصفحة الرئيسية للتطبيق مع تطبيقَين مصغّرَين
الشكل 1: مثال على صفحة رئيسية تظهر في الرسائل المباشرة مع تطبيق Chat.

على عكس تطبيقات المضيفة الأخرى في Google Workspace، لا تعرض الإضافات التي توسّع Chat صفحة رئيسية في لوحة الوصول السريع على يسار الشاشة، ولا تستخدم addOns.common.homepageTrigger في ملف البيان. بدلاً من ذلك، يعرض Chat صفحتك الرئيسية كبطاقة في علامة التبويب الصفحة الرئيسية ضمن رسالة مباشرة على الخاص مع تطبيق Chat، ويتم إعدادها في وحدة تحكّم Google Cloud.

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


استخدِم "أداة إنشاء البطاقات" لتصميم واجهات المستخدم والمراسلة ومعاينتها لتطبيقات Chat:

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

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

HTTP

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

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

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

ضبط إعدادات "الصفحة الرئيسية للتطبيق" في تطبيق Chat

لتفعيل ميزة "صفحة التطبيق الرئيسية"، فعِّل الخيار تفعيل ميزة "صفحة التطبيق الرئيسية" واضبط المشغّل الخاص بصفحة التطبيق الرئيسية في Google Cloud Console. يتلقّى تطبيق Chat حدث تشغيل صفحة التطبيق الرئيسية عندما يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة على الخاص مع تطبيق Chat.

لضبط إعدادات "مركز التطبيقات" في Google Cloud Console، اتّبِع الخطوات التالية:

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

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

  2. ضِمن الميزات التفاعلية، تأكَّد من تفعيل تفعيل الميزات التفاعلية، ثم ضَع علامة في المربّع إتاحة "الصفحة الرئيسية للتطبيق" ضِمن الوظائف.

  3. ضمن إعدادات الاتصال > المشغّلات، حدِّد معالج "الصفحة الرئيسية للتطبيق" في حقل الصفحة الرئيسية للتطبيق استنادًا إلى بنية تطبيق Chat:

    • HTTP: أدخِل عنوان URL لنقطة نهاية HTTPS التي تعالج طلبات "الصفحة الرئيسية للتطبيق" (أو ضَع علامة في المربّع بجانب استخدام عنوان URL لنقطة نهاية HTTP الشائعة لجميع المشغّلات لكي يتلقّى عنوان URL لنقطة نهاية HTTP الشائعة جميع الأحداث).
    • برمجة تطبيقات Google: أدخِل اسم دالة رد الاتصال في "برمجة تطبيقات Google" التي تنشئ بطاقة الصفحة الرئيسية وتعرضها (القيمة التلقائية هي onAppHome).
  4. انقر على حفظ.

التعامل مع عنصر حدث "الصفحة الرئيسية للتطبيق"

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

على عكس أحداث التفاعل مع المساحة أو الرسالة، لا يتضمّن عنصر حدث "الصفحة الرئيسية للتطبيق" الأوّلي حمولة تفاعل موحّدة (مثل messagePayload). ويتضمّن الحقول التالية:

  • commonEventObject: يشمل clientPlatform وhostApp ("CHAT") وuserLocale وuserTimezone.
  • chat.user: مستخدم Chat الذي فتح علامة التبويب الصفحة الرئيسية
  • chat.eventTime: الطابع الزمني الذي فتح فيه المستخدم علامة التبويب الصفحة الرئيسية.

إنشاء بطاقة "شاشة التطبيق الرئيسية"

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

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

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

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection()
              .addWidget(
                  CardService.newTextParagraph().setText(
                      'Manage your settings and view your dashboard here.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

الردّ على تفاعلات "الصفحة الرئيسية للتطبيق"

إذا كانت بطاقة "الصفحة الرئيسية للتطبيق" تحتوي على تطبيقات مصغّرة تفاعلية، مثل الأزرار أو إدخالات النماذج، يؤدي النقر على زر إلى إرسال عنصر حدث يحتوي على chat.buttonClickedPayload (بالإضافة إلى commonEventObject.parameters وcommonEventObject.formInputs) إلى وظيفة الإجراء أو نقطة النهاية التي تم ضبطها للزر.

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

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

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

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

فتح مربّعات الحوار من "الصفحة الرئيسية للتطبيق"

يمكن لتطبيق Chat أيضًا الردّ على التفاعلات في "مركز التطبيقات" من خلال فتح مربّعات حوار.

مربّع حوار يعرض مجموعة متنوعة من التطبيقات المصغّرة المختلفة
الشكل 2: مربّع حوار يطلب من المستخدم إضافة جهة اتصال.

للتعرّف على كيفية فتح مربّعات الحوار وتعديلها وإغلاقها باستخدام RenderActions (pushCard وupdateCard وendNavigation: "CLOSE_DIALOG")، يُرجى الاطّلاع على فتح مربّعات الحوار التفاعلية.

تطبيقات Chat التي ليست إضافات: إنشاء صفحة رئيسية لتطبيق Chat

إذا كنت تحتفظ بتطبيق Chat ليس إضافة في Google Workspace، يرسل Chat حدث تفاعل APP_HOME عندما يفتح المستخدم علامة التبويب الصفحة الرئيسية، ويرسل أحداث تفاعل CARD_CLICKED أو SUBMIT_FORM عندما يتفاعل المستخدم مع التطبيقات المصغّرة في بطاقة "الصفحة الرئيسية للتطبيق".

لترقية تطبيق Chat ليس إضافة إلى إطار عمل إضافات Google Workspace، يُرجى الاطّلاع على تحويل تطبيق Google Chat إلى إضافة Google Workspace.

إنشاء بطاقة "الصفحة الرئيسية للتطبيق" في تطبيق Chat ليس إضافة

في تطبيق Chat ليس إضافة، عالِج حدث التفاعل APP_HOME من خلال عرض ردّ يتضمّن الحقل renderActions ذو المستوى الأعلى مع pushCard navigation:

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

جافا

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

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

يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

الردّ على تفاعلات "صفحة التطبيق الرئيسية" في تطبيق Chat ليس إضافة

في تطبيق Chat ليس إضافة، عالِج أحداث التفاعل CARD_CLICKED أو SUBMIT_FORM من بطاقة "الصفحة الرئيسية للتطبيق" من خلال عرض ردّ يحتوي على حقل renderActions ذي مستوى أعلى مع عملية التنقّل updateCard:

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

جافا

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

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

يرسل هذا المثال رسالة بطاقة من خلال عرض ملف JSON للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في "برمجة تطبيقات Google".

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}