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

ملاحظة: يوضّح هذا الدليل كيفية إنشاء تطبيق Chat تفاعلي باستخدام أحداث التفاعل في Chat API. يمكنك أيضًا إنشاء تطبيق Chat كإضافة في Google Workspace. لمعرفة المزيد حول إطار العمل الذي يجب استخدامه، يمكنك الاطّلاع على إنشاء تطبيق تفاعلي على Google Chat.

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

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

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

---

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

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

---

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

Node.js

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

Python

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

Java

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

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

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

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

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

لتعديل إعدادات الضبط في Google Cloud Console، اتّبِع الخطوات التالية:

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

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

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

3. ضمن الميزات التفاعلية، انتقِل إلى قسم الوظائف، ثم اختَر تفعيل ميزة "الصفحة الرئيسية للتطبيق".

4. إذا كان تطبيق Chat يستخدم خدمة HTTP، انتقِل إلى إعدادات الاتصال وحدِّد نقطة نهاية لحقل عنوان URL لصفحة "التطبيق" الرئيسية. يمكنك استخدام عنوان URL نفسه الذي حدّدته في حقل عنوان URL لنقطة نهاية HTTP.

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

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

للاطّلاع على المزيد من الأمثلة، يُرجى الانتقال إلى نماذج من تطبيقات Google Chat.

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

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

Node.js

node/app-home/index.js

عرض على GitHub

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

عرض على GitHub

@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

java/app-home/src/main/java/com/google/chat/app/home/App.java

عرض على GitHub

// 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"))))))))));
}

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

نفِّذ الدالة onAppHome التي يتم استدعاؤها بعد جميع أحداث التفاعل APP_HOME:

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

apps-script/app-home/app-home.gs

عرض على GitHub

/**
 * 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 أحداث التفاعل ذات الصلة من خلال عرض مثيل من RenderActions مع عملية التنقّل updateCard. لمزيد من المعلومات حول التعامل مع التطبيقات المصغّرة التفاعلية، يُرجى الاطّلاع على معالجة المعلومات التي يدخلها المستخدمون.

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

Node.js

node/app-home/index.js

عرض على GitHub

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

Python

python/app-home/main.py

عرض على GitHub

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

java/app-home/src/main/java/com/google/chat/app/home/App.java

عرض على GitHub

// 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 للبطاقة. يمكنك أيضًا استخدام خدمة البطاقات في Apps Script.

apps-script/app-home/app-home.gs

عرض على GitHub

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

فتح مربّعات الحوار

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

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

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

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

لإغلاق مربّع حوار، عالِج أحداث التفاعل التالية:

• CLOSE_DIALOG: لإغلاق مربّع الحوار والعودة إلى بطاقة الصفحة الرئيسية للتطبيق في Chat
• CLOSE_DIALOG_AND_EXECUTE: لإغلاق مربّع الحوار وإعادة تحميل بطاقة الصفحة الرئيسية للتطبيق

يستخدم نموذج الرمز البرمجي التالي CLOSE_DIALOG لإغلاق مربّع حوار والرجوع إلى بطاقة الصفحة الرئيسية للتطبيق:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

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

مواضيع ذات صلة

• عرض نماذج لتطبيق Chat تستخدم صفحة التطبيق الرئيسية
• فتح مربّعات الحوار والردّ عليها