تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

بطاقة الصفحة الرئيسية للتطبيق تتضمّن تطبيقَين مصغّرَين — **الشكل 1**: مثال على صفحة رئيسية تظهر في الرسائل المباشرة باستخدام تطبيق 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، عليك إجراء ما يلي:

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

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

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

عندما يفتح المستخدم الصفحة الرئيسية للتطبيق، يجب أن يعالج تطبيق 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
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@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() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

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

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

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

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 التي تستخدم الصفحة الرئيسية للتطبيق.
فتح مربّعات الحوار والردّ عليها

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

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

Node.js

Python

Java

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

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

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

Node.js

Python

Java

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

الاستجابة للتفاعلات مع شاشة التطبيق الرئيسية

Node.js

Python

Java

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

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

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