إنشاء صفحة رئيسية لتطبيق 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 تفاعلي في Apps Script، أكمِل الخطوات الأساسية هذه.

ضبط شاشة تطبيق Chat الرئيسية

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

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

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

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

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

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

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

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

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

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

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

Node.js

العقدة/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

بايثون/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

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

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

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

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

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

Node.js

العقدة/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

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()
  }]}}};
}

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

يمكن لتطبيق 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: لإغلاق مربّع الحوار وإعادة تحميل بطاقة شاشة منزل<2fr>التطبيق

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

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

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