Google Chat uygulaması için ana sayfa oluşturma

Bu sayfada, Google Chat uygulamanızla doğrudan mesajlar için nasıl ana sayfa oluşturacağınız açıklanmaktadır. Google Chat API'de uygulama ana sayfası olarak adlandırılan ana sayfa, bir kullanıcı ile Chat uygulaması arasındaki doğrudan mesaj alanlarının Ana Sayfa sekmesinde görünen özelleştirilebilir bir kart arayüzüdür.

İki widget içeren uygulama ana kartı.
Şekil 1: Bir Chat uygulamasındaki doğrudan mesajlarda görünen ana sayfa örneği

Chat uygulamasıyla etkileşime geçmeyle ilgili ipuçları paylaşmak veya kullanıcıların Chat'ten harici bir hizmete veya araca erişip bu aracı kullanmasına izin vermek için uygulama ana sayfasını kullanabilirsiniz.

Chat uygulamaları için mesajlaşma ve kullanıcı arayüzlerini tasarlamak ve önizlemek üzere Kart Oluşturucu'yu kullanın:

Kart Oluşturucu'yu açın

Ön koşullar

Node.js

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Python

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Java

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir HTTP hizmeti kullanarak etkileşimli Chat uygulaması için bu hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir Apps Komut Dosyası'ndaki etkileşimli Chat uygulaması için bu hızlı başlangıç kılavuzunu tamamlayın.

Chat uygulamanız için uygulama ana sayfasını yapılandırın

Uygulama ana sayfasını desteklemek için Chat uygulamanızı APP_HOME etkileşim etkinliklerini alacak şekilde yapılandırmanız gerekir. Chat uygulamanız, bir kullanıcı Chat uygulamasındaki doğrudan mesajdan Ana Sayfa sekmesini her tıkladığında bu etkinliği alır.

Google Cloud Console'da yapılandırma ayarlarınızı güncellemek için aşağıdakileri yapın:

  1. Google Cloud konsolunda Menü'ye gidin. > Diğer ürünler > Google Workspace > Ürün Kitaplığı > Google Chat API'yi tıklayın.

    Google Chat API'ye gidin

  2. Yönet'i ve ardından Yapılandırma sekmesini tıklayın.

  3. Uygulama ana sayfasını yapılandırmak için Etkileşimli özellikler altındaki İşlevsellik bölümüne gidin:

    1. Bire bir mesajlar al onay kutusunu işaretleyin.
    2. Destek Uygulaması Ana Sayfası onay kutusunu işaretleyin.

  4. Chat uygulamanız HTTP hizmeti kullanıyorsa şu sayfaya gidin: Bağlantı ayarlarını yapın ve Uygulama Ana Sayfa URL'si alanına girin. Google Etiket Yöneticisi'nde HTTP uç nokta URL'si alanına giriş yapın.

  5. Kaydet'i tıklayın.

Uygulama ana sayfa kartı oluşturma

Kullanıcı uygulama ana ekranını açtığında Chat uygulamanız, pushCard gezinme ve Card içeren bir RenderActions örneği döndürerek APP_HOME etkileşim etkinliğini işlemelidir. Etkileşimli bir deneyim oluşturmak için kartta, Chat uygulamasının işleyip ek kartlarla veya bir iletişim kutusuyla yanıt verebileceği düğmeler ya da metin girişleri gibi etkileşimli widget'lar bulunabilir.

Aşağıdaki örnekte Chat uygulamasında Kartın oluşturulduğu zamanı gösteren ilk uygulama ana kartı bir düğme gibi. Kullanıcı düğmeyi tıkladığında Chat uygulaması değeri, güncellenen kartın oluşturulduğu zamanı gösteren güncellenmiş bir kart döndürür.

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

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

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

Apps Komut Dosyası

Tüm APP_HOME etkileşim etkinliklerinden sonra çağrılan onAppHome işlevini uygulayın:

Bu örnek, kart JSON'unu döndürerek kart mesajı gönderir. Ayrıca şunu da kullanabilirsiniz: Apps Komut Dosyası kart hizmeti.

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

Uygulama ana ekranındaki etkileşimlere yanıt verme

İlk uygulama ana kartınız düğme veya seçim girişi gibi etkileşimli widget'lar içeriyorsa Chat uygulamanız, updateCard gezinme özelliğiyle RenderActions örneği döndürerek ilgili etkileşim etkinliklerini işlemelidir. Etkileşimli widget'ları işleme hakkında daha fazla bilgi edinmek için Kullanıcılar tarafından girilen bilgileri işleme başlıklı makaleyi inceleyin.

Yukarıdaki örnekte, ilk uygulama ana kartta bir düğme vardı. Her zaman Kullanıcı düğmeyi tıkladığında, CARD_CLICKED etkileşim etkinliği gösterildiği gibi uygulama ana kartını yenilemek için updateAppHome işlevini tetikler. ile başlar:

Node.js

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

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

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

Apps Komut Dosyası

Bu örnek, kart JSON'unu döndürerek kart mesajı gönderir. Ayrıca şunu da kullanabilirsiniz: Apps Komut Dosyası kart hizmeti.

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

Açık iletişim kutuları

Chat uygulamanız, uygulama ana ekranında iletişim kutuları açarak da etkileşimlere yanıt verebilir.

Çeşitli widget'ların yer aldığı bir iletişim kutusu.
Şekil 3: Kullanıcıdan kişi eklemesini isteyen bir iletişim kutusu.

Uygulama ana sayfasında iletişim kutusu açmak için ilgili etkileşim etkinliğini şu şekilde işleyin: Card içeren updateCard gezinme içeren renderActions döndürülüyor nesnesini tanımlayın. Aşağıdaki örnekte, bir Chat uygulaması CARD_CLICKED işleyerek uygulama ana kartından bir düğme tıklamasına etkileşim etkinliğini bulup bir iletişim kutusu açtığınızda:

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

Bir iletişim kutusunu kapatmak için aşağıdaki etkileşim etkinliklerini işleyin:

  • CLOSE_DIALOG: İletişim kutusunu kapatır ve Chat uygulamasının ilk uygulama ana kartı.
  • CLOSE_DIALOG_AND_EXECUTE: İletişim kutusunu kapatır ve uygulama ana sayfasını yeniler kartını inceleyebilirsiniz.

Aşağıdaki kod örneğinde, bir iletişim kutusunu kapatmak ve uygulama ana kartına dönmek için CLOSE_DIALOG kullanılmaktadır:

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

Kullanıcılardan bilgi toplamak için sıralı iletişim kutuları da oluşturabilirsiniz. Alıcı: sıralı iletişim kutuları oluşturmayı öğrenmek için İletişim kutularını açma ve yanıtlama.