Google Chat arayüzleri oluşturma

Bu sayfada, Google Chat'i genişleten Google Workspace eklentileri için kullanıcı arayüzlerinin (UI) nasıl oluşturulacağı hakkında genel bilgiler verilmektedir.

Chat uygulamaları için arayüz oluşturmak üzere aşağıdaki eklenti bileşenlerini kullanırsınız:

  • Tetikleyiciler: Google Chat kullanıcılarının bir Chat uygulamasını çağırma yöntemleri (ör. uygulamayı bir alana ekleme veya uygulamaya mesaj gönderme).
  • Etkinlik nesneleri: Chat uygulamalarının tetikleyicilerden veya kullanıcı arayüzü etkileşimlerinden aldığı veriler.
  • İşlemler: Chat uygulamalarının etkileşimlere yanıt verme şekilleri (ör. mesaj gönderme veya kart tabanlı kullanıcı arayüzü döndürme).
Chat uygulaması, "Alana eklendi" tetikleyicisinden bir etkinlik nesnesi alır.
Şekil 1: Bir kullanıcı bir alana Chat uygulaması eklediğinde Alana eklendi tetikleyicisi etkinleşir ve bir etkinlik nesnesi gönderir. Mesajla yanıt vermek için Chat uygulaması etkinlik nesnesini işler ve mesajı oluşturan bir işlem döndürür.

Chat uygulamaları aşağıdaki arayüzlerde kart oluşturup gösterebilir:

  • Metin, statik veya etkileşimli kartlar ve düğmeler içerebilen mesajlar.
  • Chat uygulamasıyla bire bir doğrudan mesajların Ana Sayfa sekmesinde gösterilen ana sayfalar.
  • Yeni bir pencerede açılan ve genellikle kullanıcılardan bilgi göndermelerini isteyen kartlar olan iletişim kutuları.
  • Harici bir hizmetle ilgili bilgileri önizleyen kartlar olan bağlantı önizlemeleri.

Tetikleyiciler

Bu bölümde, Google Workspace eklentilerinin Chat'te kullandığı tetikleyiciler açıklanmaktadır.

Tetikleyiciler, kullanıcıların Chat kullanıcı arayüzünü kullanarak Chat uygulamasını çağırmasının belirli yollarıdır. Örneğin, @bahsetme veya uygulama komutlarını kullanma.

Aşağıdaki tabloda Chat tetikleyicileri, açıklamaları ve Chat uygulamalarının genellikle nasıl yanıt verdiği gösterilmektedir:

Tetikleyici Açıklama Normal yanıt
Alana eklendi

Bir kullanıcı, Chat uygulamasını bir alana ekler veya bir Google Workspace yöneticisi, kuruluşundaki kullanıcılar için Chat uygulamasını doğrudan mesaj alanlarına yükler. Yöneticiler tarafından yüklenen Chat uygulamaları hakkında bilgi edinmek için Google Workspace Yönetici Yardım Dokümanları'ndaki Marketplace uygulamalarını alanınıza yükleme başlıklı makaleyi inceleyin.

 Chat uygulaması, ne yaptığını ve alandaki kullanıcıların uygulamayla nasıl etkileşim kurabileceğini açıklayan bir ilk katılım mesajı gönderir.
Mesaj

Bir kullanıcı, Chat uygulamasında aşağıdaki yöntemlerden biriyle etkileşimde bulunur:

  • Chat uygulamasıyla doğrudan mesaj (DM) alanında mesaj gönderir.
  • Herhangi bir alanda Chat uygulamasından @bahsederse
  • Bağlantı önizlemeleri için URL kalıbıyla eşleşen bir bağlantı içeren mesaj gönderir.
  • Bir selectionInput widget'ının çoklu seçim menüsüne metin yazar.
 Chat uygulaması, mesajın içeriğine göre yanıt verir. Örneğin, bir Chat uygulaması, eğik çizgi komutu /about'ya Chat uygulamasının yapabileceği görevleri açıklayan bir mesajla yanıt verir.
Alandan kaldırıldı

Bir kullanıcı Chat uygulamasını alandan kaldırdığında veya bir Google Workspace yöneticisi, kuruluşundaki bir kullanıcı için Chat uygulamasını kaldırdığında

Kullanıcılar, yöneticileri tarafından yüklenen Chat uygulamalarını kaldıramaz. Kullanıcı daha önce Chat uygulamasını yüklediyse Google Workspace yöneticisi kaldırmaya çalışsa bile Chat uygulaması yüklü kalır.

 Chat uygulaması, alan için yapılandırılmış tüm gelen bildirimleri (ör. webhook'u silme) kaldırır ve dahili depolama birimini temizler. Sohbet uygulamaları, artık alanın üyesi olmadıkları için bu tetikleyiciye mesajla yanıt veremez.
Uygulama komutu

Kullanıcı bir Chat uygulaması komutu kullanır.

 Chat uygulaması komuta yanıt verir. Örneğin, mesajla yanıt verme veya iletişim kutusu açma.
Uygulama Ana Sayfası

Bir kullanıcı, Chat uygulamasıyla bire bir doğrudan mesaj (DM) alanında Ana Sayfa sekmesini açar veya ana sayfa kartındaki bir widget'la etkileşime girer.

 Chat uygulaması, ana sayfa kartı gönderen (pushCard) veya gösterilen ana sayfa kartını güncelleyen (updateCard) bir RenderActions nesnesi döndürür.

Diğer eklentilerin aksine, bu tetikleyiciler için geri çağırma işlevlerini Google Chat API'yi kullanarak yapılandırmanız gerekir. Yardım için Sohbet uygulaması yapılandırma başlıklı makaleyi inceleyin.

Bir tetikleyiciye yanıt vermek için aşağıdaki kılavuzlara bakın:

Etkinlik nesneleri

Chat uygulamaları, bir Chat tetikleyicisi çalıştırıldığında veya Chat kullanıcıları Chat uygulamasının kullanıcı arayüzüyle (ör. bir düğmeyi tıklayarak) etkileşimde bulunduğunda etkinlik nesneleri alır. Etkinlik nesnesi, etkileşim verilerini kullanarak bir kullanıcı arayüzüne yanıt vermenize veya kullanıcı arayüzünü güncellemenize olanak tanır.

Etkinlik nesnesi yükleri

Her Chat etkinliği nesnesi, ana makine ve platform ayrıntılarını (hostApp: "CHAT", clientPlatform, userLocale, userTimezone ve formInputs) içeren bir commonEventObject ile Chat'e özgü bağlamı içeren bir chat nesnesi içerir:

  • Uygulama ana sayfası tetikleyicisi için (kullanıcı, Chat uygulamasıyla bire bir doğrudan mesajda Ana Sayfa sekmesini açtığında) chat nesnesi, bir birleşim payload alanı olmadan chat.user ve chat.eventTime içerir. Kullanıcı ana sayfa kartındaki bir düğmeyi tıkladığında etkinlik nesnesi commonEventObject.parameters (ve kartta form girişleri varsa commonEventObject.formInputs) de içerir.
  • Alan ve mesaj etkileşimleri (Alana eklendi, Mesaj, Alandan kaldırıldı, Uygulama komutu veya düğme ve widget etkileşimleri) için chat nesnesi chat.user, chat.space, chat.eventTime ve karşılık gelen etkileşim yükünü (messagePayload, addedToSpacePayload, removedFromSpacePayload, buttonClickedPayload, widgetUpdatedPayload veya appCommandPayload) içerir.

Etkinlik nesnelerini işleme hakkında bilgi edinmek için aşağıdaki kılavuzlara bakın:

Chat ve diğer Google Workspace uygulamalarındaki eklenti etkinlik nesneleri hakkında bilgi edinmek için Etkinlik nesneleri başlıklı makaleyi inceleyin.

Sohbet işlemleri

Bu bölümde, Chat uygulamalarının kullanıcı etkileşimlerine yanıt vermek için eklenti işlemlerini nasıl kullanabileceği açıklanmaktadır.

Eklenti işlemiyle yanıt vermek için bir sohbet uygulamasının 30 saniye içinde yanıt vermesi ve yanıtın etkileşimin gerçekleştiği alanda yayınlanması gerekir. Aksi takdirde, Chat uygulaması kimlik doğrulama ayarlamalı ve yanıt vermek için Google Chat API'yi çağırmalıdır.

Sohbet uygulamaları, etkileşimleri birçok şekilde ele alabilir ve yanıtlayabilir. Çoğu durumda, Chat uygulamaları mesajla yanıt verir. Sohbet uygulamaları, bir veri kaynağından bazı bilgileri arayabilir, etkinlik nesnesi bilgilerini kaydedebilir veya başka herhangi bir işlemi yapabilir. Bu işleme davranışı, Google Chat uygulamasını tanımlayan temel özelliktir.

Chat uygulamaları, kullanıcı etkileşimlerine yanıt vermek için ilgili etkinlik nesnesini işlemeli ve aşağıdaki JSON nesnelerinden birini döndürmelidir:

Aşağıdaki tabloda, Chat uygulamalarının işlemlerle nasıl yanıt verebileceği gösterilmektedir. Chat uygulamaları JSON nesneleri döndürebilir veya Apps Komut Dosyası'nın AddOnResponseService özelliğini kullanarak yanıt oluşturabilir.

Sohbet uygulaması yanıtı Döndürmek için gereken işlem (JSON) Döndürmek için gerekli işlem (Apps Komut Dosyası)
Mesaj gönderme veya güncelleme DataActions DataActionsResponse
Doğrudan mesajın Ana Sayfa sekmesinde bir ana sayfa oluşturma veya güncelleme RenderActions ActionResponse
İletişim kutusunu açma, güncelleme veya kapatma RenderActions ActionResponse
Bir karttan veya iletişim kutusundan bilgi toplamak için kullanıcıların çoklu seçim menüsüne yazdıklarına göre seçim öğeleri önerin. RenderActions ActionResponse
Chat kullanıcılarının bir alanda gönderdiği mesajlardaki bağlantıları önizleme DataActions DataActionsResponse

Google Chat API'yi kullanarak yanıt verme

Eklenti işlemi döndürmek yerine, Chat uygulamalarının etkileşime yanıt vermek için Google Chat API'yi kullanması gerekebilir. Örneğin, Chat uygulamalarının aşağıdakilerden herhangi birini yapabilmek için Google Chat API'yi çağırması gerekir:

  • 30 saniye sonra bir etkileşime yanıt verme
  • Etkileşimin gerçekleştiği alanın dışında görevler gerçekleştirme.
  • Chat'te, eklenti işlemleri olarak kullanılamayan görevleri gerçekleştirme Örneğin, bir kullanıcının veya Chat uygulamasının üyesi olduğu alanları listeleme ya da alana kullanıcı ekleme.
  • Sohbet kullanıcısı adına görev gerçekleştirme (kullanıcı kimlik doğrulaması gerektirir).

Bir etkileşim etkinliğine 30 saniye sonra yanıt verirken, kullanıcıya "Sohbet uygulamanız yanıt vermiyor" şeklinde bir hata mesajı gösterilmesini önlemek için etkileşim etkinliğinin alındığını 30 saniye içinde boş bir yanıt göndererek onaylamanız gerekir.

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Komut Dosyası

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Chat API'nin kimliğini doğrulama ve Chat API'yi çağırma hakkında bilgi edinmek için Chat API'ye genel bakış başlıklı makaleyi inceleyin.