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

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

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

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


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

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

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

Node.js

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

Python

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

جافا

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

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

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

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

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

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

  1. في Google Cloud Console، انقر على القائمة > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API > الضبط. الانتقال إلى إعدادات Chat API
  2. ضمن الميزات التفاعلية ، انتقِل إلى قسم الوظائف ، واختَر استخدام الصفحة الرئيسية للتطبيق.
  3. إذا كان تطبيق Chat يستخدم خدمة HTTP، انتقِل إلى إعدادات الاتصال وحدِّد نقطة نهاية لحقل عنوان URL للصفحة الرئيسية للتطبيق. يمكنكم استخدام عنوان URL نفسه الذي حدّدتموه في حقل عنوان URL لنقطة نهاية HTTP.
  4. انقر على حفظ.

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

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

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

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

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

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

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

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 عملية التنقّل. لمزيد من المعلومات حول التعامل مع الأدوات التفاعلية ، يُرجى الاطّلاع على مقالة معالجة المعلومات التي يُدخلها المستخدمون.

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

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

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: يؤدي هذا الحدث إلى إغلاق مربّع الحوار وتحديث بطاقة الصفحة الرئيسية للتطبيق.

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

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

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