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

Bu sayfada, Google Chat uygulamanızla doğrudan mesajlaşma için ana sayfa oluşturma açıklanmaktadır. Google Chat API'de Uygulama Ana Sayfası olarak adlandırılan ana sayfa, bir kullanıcı ile Chat uygulaması arasındaki bire bir doğrudan mesajlaşma alanlarının Ana Sayfa sekmesinde görünen, özelleştirilebilir bir kart arayüzüdür.

İki widget'ın bulunduğu uygulama ana ekranı kartı.
Şekil 1: Chat uygulamasıyla gönderilen doğrudan mesajlarda görünen bir ana sayfa örneği.

Chat'i genişleten eklentiler, diğer Google Workspace ana uygulamalarının aksine sağ taraftaki hızlı erişim panelinde ana sayfa göstermez ve manifest dosyasında addOns.common.homepageTrigger kullanmaz. Bunun yerine Chat, ana sayfanızı Chat uygulamasıyla bire bir doğrudan mesajın Ana Sayfa sekmesinde kart olarak gösterir ve Google Cloud Console'da yapılandırılır.

Uygulama Ana Sayfası'nı kullanarak Chat uygulamasıyla etkileşim kurma ipuçlarını paylaşabilir, kişiselleştirilmiş bir kullanıcı kontrol paneli gösterebilir veya kullanıcıların Chat'ten harici bir hizmete ya da araca erişip bu hizmeti ya da aracı yapılandırmasına olanak tanıyabilirsiniz.


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

HTTP

Kullanıcı etkileşimlerini alan ve bunlara yanıt veren bir Google Chat uygulaması. Oluşturmak için HTTP hızlı başlangıç bölümünü tamamlayın.

Apps Komut Dosyası

Kullanıcı etkileşimlerini alan ve bunlara yanıt veren bir Google Chat uygulaması. Oluşturmak için Apps Komut Dosyası hızlı başlangıç kılavuzunu tamamlayın.

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

Uygulama Ana Sayfası'nı desteklemek için Google Cloud Console'da Uygulama Ana Sayfası'nı destekle'yi etkinleştirin ve Uygulama ana sayfası tetikleyicisini yapılandırın. Kullanıcı, Chat uygulamasıyla bire bir doğrudan mesajda Ana Sayfa sekmesini her açtığında Chat uygulamanız bir Uygulama Ana Sayfası tetikleme etkinliği alır.

Google Cloud Console'da Uygulama Ana Sayfası'nı yapılandırmak için:

  1. Google Cloud Console'da Menü > API'ler ve Hizmetler > Etkin API'ler ve Hizmetler > Google Chat API > Yapılandırma'ya gidin.

    Chat API yapılandırmasına gitme

  2. Etkileşimli özellikler bölümünde Etkileşimli özellikleri etkinleştir'in açık olduğundan emin olun ve ardından İşlevsellik bölümünde Uygulama Ana Sayfası'nı destekle onay kutusunu işaretleyin.

  3. Bağlantı ayarları > Tetikleyiciler bölümünde, Chat uygulaması mimarinize göre Uygulama ana sayfası alanında uygulama ana sayfası işleyicinizi belirtin:

    • HTTP: Uygulama Ana Sayfası isteklerini işleyen HTTPS uç noktası URL'sini girin (veya ortak HTTP uç noktası URL'nizin tüm etkinlikleri alması için Tüm tetikleyiciler için ortak HTTP uç noktası URL'sini kullan'ı seçin).
    • Google Apps Komut Dosyası: Ana sayfa kartınızı oluşturan ve döndüren Google Apps Komut Dosyası geri çağırma işlevinin adını girin (varsayılan olarak onAppHome).
  4. Kaydet'i tıklayın.

App Home etkinlik nesnesini işleme

Kullanıcı, Chat uygulamanızla bire bir doğrudan mesajın Ana Sayfa sekmesini açtığında Chat, uygulama ana sayfası uç noktanıza veya geri çağırma işlevinize bir etkinlik nesnesi gönderir.

Boşluk veya ileti etkileşimi etkinliklerinin aksine, ilk uygulama ana sayfası etkinlik nesnesi bir birleşim etkileşimi yükü (ör. messagePayload) içermez. Aşağıdaki alanları içerir:

  • commonEventObject: clientPlatform, hostApp ("CHAT"), userLocale ve userTimezone değerlerini içerir.
  • chat.user: Ana Sayfa sekmesini açan Chat kullanıcısı.
  • chat.eventTime: Kullanıcının Ana Sayfa sekmesini açtığı zaman damgası.

Uygulama ana sayfası kartı oluşturma

Kullanıcı Ana Sayfa sekmesini açtığında App Home tetikleyici etkinliğini işlemek için pushCard gezinme işlemi ve Card RenderActions nesnesi döndürün. Kart, etkileşimli bir deneyim oluşturmak için düğmeler veya metin girişleri gibi etkileşimli widget'lar içerebilir.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Komut Dosyası

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection()
              .addWidget(
                  CardService.newTextParagraph().setText(
                      'Manage your settings and view your dashboard here.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Uygulama ana sayfası etkileşimlerine yanıt verme

Uygulama Ana Sayfası kartınızda düğmeler veya form girişleri gibi etkileşimli widget'lar varsa bir düğmeyi tıkladığınızda, düğmenin yapılandırılmış işlem işlevine veya uç noktasına chat.buttonClickedPayload (commonEventObject.parameters ve commonEventObject.formInputs ile birlikte) içeren bir etkinlik nesnesi gönderilir.

Kullanıcı etkileşimine yanıt olarak uygulama ana sayfası kartını güncellemek için updateCard gezinme işlemi içeren bir RenderActions nesnesi döndürün. Etkileşimli widget'lardan form girişlerini okuma hakkında daha fazla bilgi edinmek için Kartlarda kullanıcılar tarafından girilen form verilerini okuma başlıklı makaleyi inceleyin.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Komut Dosyası

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

Uygulama ana sayfasından iletişim kutularını açma

Chat uygulamanız, iletişim kutularını açarak Uygulama Ana Sayfası'ndaki etkileşimlere de yanıt verebilir.

Çeşitli widget'ların yer aldığı bir iletişim kutusu.
Şekil 2: Kullanıcıyı kişi eklemeye yönlendiren iletişim kutusu.

RenderActions (pushCard, updateCard ve endNavigation: "CLOSE_DIALOG") kullanarak iletişim kutularını açma, güncelleme ve kapatma hakkında bilgi edinmek için Etkileşimli iletişim kutularını açma başlıklı makaleyi inceleyin.

Eklenti olmayan Chat uygulamaları: Chat uygulaması için ana sayfa oluşturma

Google Workspace eklentisi olmayan bir Chat uygulaması kullanıyorsanız Chat, kullanıcı Ana Sayfa sekmesini açtığında APP_HOME etkileşim etkinliği gönderir ve kullanıcı Uygulama Ana Sayfası kartındaki widget'larla etkileşime girdiğinde CARD_CLICKED veya SUBMIT_FORM etkileşim etkinlikleri gönderir.

Eklenti olmayan bir Chat uygulamasını Google Workspace eklenti çerçevesine yükseltmek için Google Chat uygulamasını Google Workspace eklentisine dönüştürme başlıklı makaleyi inceleyin.

Eklenti olmayan bir Chat uygulamasında uygulama ana sayfası kartı oluşturma

Eklenti olmayan bir Chat uygulamasında, üst düzey APP_HOME alanı içeren bir yanıt döndürerek renderActions etkileşim etkinliğini işleyin. pushCard gezinme:

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
@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"))))))))));
}

Apps Komut Dosyası

Bu örnek, card JSON döndürerek kart mesajı gönderir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz.

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

Eklenti olmayan bir Chat uygulamasında uygulama ana sayfası etkileşimlerine yanıt verme

Eklenti olmayan bir Chat uygulamasında, bir Uygulama Ana Sayfası kartından gelen CARD_CLICKED veya SUBMIT_FORM etkileşim etkinliklerini, updateCard gezinme içeren üst düzey bir renderActions alanı içeren bir yanıt döndürerek işleyin:

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, card JSON döndürerek kart mesajı gönderir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz.

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