یک صفحه اصلی برای برنامه Google Chat بسازید

توجه: این راهنما نحوه ساخت یک برنامه چت تعاملی با استفاده از رویدادهای تعاملی API چت را توضیح می‌دهد. همچنین می‌توانید برنامه چت خود را به عنوان یک افزونه Google Workspace بسازید. برای کسب اطلاعات در مورد اینکه از کدام چارچوب استفاده کنید، به بخش ساخت یک برنامه چت تعاملی Google مراجعه کنید.

این صفحه نحوه ساخت صفحه اصلی برای پیام‌های مستقیم با برنامه Google Chat شما را توضیح می‌دهد. صفحه اصلی، که در API Google Chat به عنوان صفحه اصلی برنامه شناخته می‌شود، یک رابط کارتی قابل تنظیم است که در برگه Home فضاهای پیام مستقیم بین کاربر و برنامه Chat ظاهر می‌شود.

شکل ۱ : نمونه‌ای از صفحه اصلی که در پیام‌های مستقیم با یک برنامه چت ظاهر می‌شود.

شما می‌توانید از صفحه اصلی برنامه برای به اشتراک گذاشتن نکاتی برای تعامل با برنامه چت یا اجازه دادن به کاربران برای دسترسی و استفاده از یک سرویس یا ابزار خارجی از چت استفاده کنید.

---

از Card Builder برای طراحی و پیش‌نمایش پیام‌رسانی و رابط‌های کاربری برای برنامه‌های چت استفاده کنید:

سازنده کارت را باز کنید

---

پیش‌نیازها

نود جی اس

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

پایتون

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

جاوا

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

اسکریپت برنامه‌ها

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی در Apps Script، این راهنمای سریع را تکمیل کنید.

پیکربندی صفحه اصلی برنامه برای برنامه چت شما

برای پشتیبانی از صفحه اصلی برنامه، باید برنامه چت خود را طوری پیکربندی کنید که رویدادهای تعاملی APP_HOME را دریافت کند. برنامه چت شما این رویداد را هر زمان که کاربر از طریق پیام مستقیم با برنامه چت روی تب Home کلیک کند، دریافت می‌کند.

برای به‌روزرسانی تنظیمات پیکربندی خود در کنسول Google Cloud، موارد زیر را انجام دهید:

1. در کنسول گوگل کلود، به منو > مشاهده همه محصولات > سایر محصولات گوگل > فضای کاری گوگل > کتابخانه محصولات > API چت گوگل بروید.

   به API چت گوگل بروید

2. روی مدیریت کلیک کنید و سپس روی برگه پیکربندی کلیک کنید.

3. در بخش ویژگی‌های تعاملی ، به بخش عملکرد بروید و صفحه اصلی برنامه پشتیبانی را انتخاب کنید.

4. اگر برنامه چت شما از سرویس HTTP استفاده می‌کند، به تنظیمات اتصال بروید و یک نقطه پایانی برای فیلد App Home URL مشخص کنید. می‌توانید از همان URL که در فیلد HTTP endpoint URL مشخص کرده‌اید، استفاده کنید.

5. روی ذخیره کلیک کنید.

یک کارت خانه برنامه بسازید

برای مثال‌های بیشتر، به نمونه‌های برنامه چت گوگل مراجعه کنید.

وقتی کاربری صفحه اصلی برنامه را باز می‌کند، برنامه چت شما باید رویداد تعامل APP_HOME را با برگرداندن نمونه‌ای از RenderActions با ناوبری pushCard و یک Card مدیریت کند. برای ایجاد یک تجربه تعاملی، کارت می‌تواند شامل ویجت‌های تعاملی مانند دکمه‌ها یا ورودی‌های متنی باشد که برنامه چت می‌تواند آنها را پردازش کرده و با کارت‌های اضافی یا یک کادر محاوره‌ای به آنها پاسخ دهد.

در مثال زیر، برنامه چت یک کارت خانه اولیه برنامه را نمایش می‌دهد که زمان ایجاد کارت و یک دکمه را نشان می‌دهد. وقتی کاربر روی دکمه کلیک می‌کند، برنامه چت یک کارت به‌روزرسانی‌شده را برمی‌گرداند که زمان ایجاد کارت به‌روزرسانی‌شده را نشان می‌دهد.

نود جی اس

گره/برنامه-خانه/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"
      }}
    }]}}
  ]}]};
}

پایتون

پایتون/برنامه-خانه/اصلی.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 استفاده کنید.

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

به تعاملات برنامه در صفحه اصلی پاسخ دهید

اگر کارت اصلی برنامه اولیه شما حاوی ویجت‌های تعاملی مانند دکمه‌ها یا ورودی‌های انتخاب باشد، برنامه چت شما باید با برگرداندن نمونه‌ای از RenderActions با ناوبری updateCard ، رویدادهای تعاملی مرتبط را مدیریت کند. برای کسب اطلاعات بیشتر در مورد مدیریت ویجت‌های تعاملی، به بخش «پردازش اطلاعات ورودی توسط کاربران» مراجعه کنید.

در مثال قبلی، کارت اصلی برنامه شامل یک دکمه بود. هر زمان که کاربر روی دکمه کلیک کند، رویداد تعاملی CARD_CLICKED تابع updateAppHome را برای به‌روزرسانی کارت اصلی برنامه فعال می‌کند، همانطور که در کد زیر نشان داده شده است:

نود جی اس

گره/برنامه-خانه/index.js

مشاهده در گیت‌هاب

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

پایتون

پایتون/برنامه-خانه/اصلی.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 استفاده کنید.

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

مشاهده در گیت‌هاب

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

پنجره‌های گفتگو را باز کنید

برنامه چت شما همچنین می‌تواند با باز کردن پنجره‌های گفتگو، به تعاملات موجود در صفحه اصلی برنامه پاسخ دهد.

شکل ۳ : پنجره‌ای که از کاربر می‌خواهد مخاطبی را اضافه کند.

برای باز کردن یک کادر محاوره‌ای از صفحه اصلی برنامه، رویداد تعاملی مرتبط را با برگرداندن renderActions به همراه ناوبری updateCard که شامل یک شیء Card است، پردازش کنید. در مثال زیر، یک برنامه چت با پردازش رویداد تعاملی 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 : پنجره گفتگو را می‌بندد و به کارت خانه اولیه برنامه چت برمی‌گردد.
• CLOSE_DIALOG_AND_EXECUTE : کادر محاوره‌ای را می‌بندد و کارت خانه برنامه را به‌روزرسانی می‌کند.

نمونه کد زیر از CLOSE_DIALOG برای بستن یک پنجره محاوره‌ای و بازگشت به کارت خانه برنامه استفاده می‌کند:

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

برای جمع‌آوری اطلاعات از کاربران، می‌توانید دیالوگ‌های ترتیبی نیز بسازید. برای یادگیری نحوه‌ی ساخت دیالوگ‌های ترتیبی، به بخش «باز کردن و پاسخ دادن به دیالوگ‌ها» مراجعه کنید.

مباحث مرتبط

• نمونه‌هایی از برنامه‌های چت که از app home استفاده می‌کنند را مشاهده کنید .
• باز کردن و پاسخ دادن به دیالوگ‌ها .