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

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

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

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


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

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

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

Python

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

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

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat التفاعلي في "برمجة تطبيقات Google"، أكمِل البدء السريع هذا.

Node.js

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

Java

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

ضبط Chat API

لإتاحة الصفحة الرئيسية للتطبيق، يجب تعديل إعدادات Chat API. في وحدة تحكُّم Google Cloud.

Python

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

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

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

  3. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

  4. في حقل عنوان URL للصفحة الرئيسية للتطبيق، أضِف عنوان URL. عادةً ما تكون هذه القيمة هي نفسها عنوان URL باعتباره عنوان URL للتطبيق. تم طلب عنوان URL هذا APP_HOME حدثًا.

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

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

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

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

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

  3. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

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

Node.js

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

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

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

  3. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

  4. في حقل عنوان URL للصفحة الرئيسية للتطبيق، أضِف عنوان URL. عادةً ما تكون هذه القيمة هي نفسها عنوان URL باعتباره عنوان URL للتطبيق. تم طلب عنوان URL هذا APP_HOME حدثًا.

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

Java

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

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

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

  3. ضَع علامة في مربّع الاختيار الصفحة الرئيسية لتطبيق الدعم.

  4. في حقل عنوان URL للصفحة الرئيسية للتطبيق، أضِف عنوان URL. عادةً ما تكون هذه القيمة هي نفسها عنوان URL باعتباره عنوان URL للتطبيق. تم طلب عنوان URL هذا APP_HOME حدثًا.

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

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

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

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

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

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

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"
      }}
    }]}}
  ]}]}

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

يمكنك تنفيذ الدالة 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"
      }}
    }]}}
  ]}]};
}

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

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * 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;
}

تعديل بطاقة رئيسية في التطبيق

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

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

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

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

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

Node.js

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

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

القيود

بشكل عام، navigation هو غير متوفّر لتطبيقات Chat. لا يمكنك إرجاع حزمة من البطاقات. فقط pushCard (للاستجابة الأولية) وupdateCard (للتحديثات) هي فقط متوفّرة لتطبيقات Chat