یک صفحه اصلی برای برنامه 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 که در قسمت URL نقطه پایانی HTTP مشخص کرده‌اید استفاده کنید.

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

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

برای مثال‌های بیشتر، نمونه‌های برنامه Google Chat را ببینید.

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

در مثال زیر، برنامه چت یک کارت اصلی برنامه را نمایش می دهد که زمان ایجاد کارت و یک دکمه را نشان می دهد. وقتی کاربر روی دکمه کلیک می‌کند، برنامه 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/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/app-home/src/main/java/com/google/chat/app/home/App.java

در GitHub مشاهده کنید

// 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

در 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/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/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/app-home/app-home.gs

در GitHub مشاهده کنید

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

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

موضوعات مرتبط

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