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

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

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

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


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

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

پیش نیازها

Node.js

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

پایتون

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

جاوا

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

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

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی در Apps Script، این شروع سریع را کامل کنید.

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

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

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

  1. در کنسول Google Cloud، به منو > محصولات بیشتر > Google Workspace > کتابخانه محصول > Google Chat API بروید.

    به Google Chat API بروید

  2. روی Manage کلیک کنید و سپس روی تب Configuration کلیک کنید.

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

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

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

یک کارت خانه اپلیکیشن بسازید

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

در مثال زیر، برنامه چت یک کارت اصلی برنامه را نمایش می دهد که زمان ایجاد کارت و یک دکمه را نشان می دهد. وقتی کاربر روی دکمه کلیک می‌کند، برنامه 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/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
 *
 * @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 یک پیام کارت ارسال می کند. همچنین می‌توانید از سرویس کارت برنامه‌های اسکریپت استفاده کنید.

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

دیالوگ ها را باز کنید

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

دیالوگی شامل انواع ویجت های مختلف.
شکل 3 : گفتگویی که از کاربر می خواهد یک مخاطب اضافه کند.

برای باز کردن یک گفتگو از صفحه اصلی برنامه، رویداد تعامل مرتبط را با بازگرداندن 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 : گفتگو را می بندد و به کارت اصلی برنامه اصلی برنامه Chat برمی گردد.
  • CLOSE_DIALOG_AND_EXECUTE : گفتگو را می بندد و کارت اصلی برنامه را تازه می کند.

نمونه کد زیر از CLOSE_DIALOG برای بستن یک گفتگو و بازگشت به کارت اصلی برنامه استفاده می کند:

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

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