Bu kılavuzda, Google Chat uygulamalarının kart tabanlı arayüzlerde form girişleri oluşturarak kullanıcılardan nasıl bilgi toplayıp işleyebileceği açıklanmaktadır.
Chat uygulamaları, Chat'te veya Chat dışında işlem yapmak için kullanıcılardan bilgi ister. Örneğin:
- Ayarları yapılandırın. Örneğin, kullanıcıların bildirim ayarlarını özelleştirmesine veya Chat uygulamasını bir ya da daha fazla alana yapılandırıp eklemesine izin vermek için.
- Diğer Google Workspace uygulamalarında bilgi oluşturma veya güncelleme Örneğin, kullanıcıların Google Takvim etkinliği oluşturmasına izin verin.
- Kullanıcıların diğer uygulamalardaki veya web hizmetlerindeki kaynaklara erişmesine ve bunları güncellemesine izin verin. Örneğin, bir Chat uygulaması, kullanıcıların destek kaydının durumunu doğrudan bir Chat alanından güncellemesine yardımcı olabilir.
Ön koşullar
HTTP
Google Chat'i genişleten bir Google Workspace eklentisi Oluşturmak için HTTP hızlı başlangıç kılavuzunu tamamlayın.
Apps Komut Dosyası
Google Chat'i genişleten bir Google Workspace eklentisi Bunu oluşturmak için Apps Komut Dosyası hızlı başlangıç kılavuzunu tamamlayın.
Kartları kullanarak form oluşturma
Chat uygulamaları, bilgi toplamak için formlar ve girişler tasarlayıp bunları kartlara yerleştirir. Chat uygulamaları, kullanıcılara kart göstermek için aşağıdaki Chat arayüzlerini kullanabilir:
- Bir veya daha fazla kart içeren sohbet mesajları
- İletişim kutuları: İletilerden ve ana sayfalardan yeni bir pencerede açılan kartlardır.
Sohbet uygulamaları, aşağıdaki widget'ları kullanarak kart oluşturabilir:
Kullanıcılardan bilgi isteyen form girişi widget'ları. İsteğe bağlı olarak, kullanıcıların bilgileri doğru şekilde girip biçimlendirmesini sağlamak için form girişi widget'larına doğrulama ekleyebilirsiniz. Sohbet uygulamaları aşağıdaki form girişi widget'larını kullanabilir:
- Serbest biçimli veya önerilen metin için metin girişleri
(
textInput). Seçim girişleri (
selectionInput) onay kutuları, radyo düğmeleri ve açılır menüler gibi seçilebilir kullanıcı arayüzü öğeleridir. Seçim girişi widget'ları, Google Workspace verilerindeki (ör. Chat alanı) veya dinamik bir veri kaynağındaki öğeleri de doldurup önerebilir. Ayrıntılar için Çoklu seçim menüsü ekleme başlıklı bölümü inceleyin.Tarih ve saat girişleri için tarih ve saat seçiciler (
dateTimePicker)
- Serbest biçimli veya önerilen metin için metin girişleri
(
Kullanıcıların karta girdikleri değerleri gönderebilmeleri için düğme widget'ı. Kullanıcı düğmeyi tıkladıktan sonra Chat uygulaması aldığı bilgileri işleyebilir.
Aşağıdaki örnekte, bir kart metin girişi, tarih/saat seçici ve seçim girişi kullanarak iletişim bilgilerini topluyor:
Bilgi toplamak için kullanabileceğiniz etkileşimli widget'larla ilgili daha fazla örnek için Google Chat API belgelerindeki Etkileşimli kart veya iletişim kutusu tasarlama başlıklı makaleyi inceleyin.
Çoklu seçim menüsü ekleme
Chat uygulamaları, seçim öğelerini özelleştirmek veya kullanıcıların dinamik bir veri kaynağındaki öğeleri seçmesine izin vermek için SelectionInput türünde bir widget olan çoklu seçim menülerini kullanabilir. Örneğin, aşağıdaki kartta kullanıcıların bir kişi listesinden dinamik olarak seçim yapabileceği çoklu seçim menüsü gösteriliyor:
Çoklu seçim menüsündeki öğeleri aşağıdaki veri kaynaklarından doldurabilirsiniz:
- Google Workspace verileri (kullanıcıların veya kullanıcının üyesi olduğu Chat alanları dahil). Menüye yalnızca aynı Google Workspace kuruluşundaki öğeler eklenir.
- İlişkisel veritabanı gibi harici veri kaynakları. Örneğin, bir kullanıcının müşteri ilişkileri yönetimi (CRM) sistemindeki satış potansiyel müşterileri listesinden seçim yapmasına yardımcı olmak için çoklu seçim menülerini kullanabilirsiniz.
Google Workspace veri kaynağından öğe doldurma
Google Workspace veri kaynaklarını kullanmak için SelectionInput widget'ında platformDataSource alanını belirtin. Diğer seçim girişi türlerinin aksine, bu seçim öğeleri Google Workspace'ten dinamik olarak alındığı için SelectionItem nesneleri atlıyorsunuz.
Aşağıdaki kod, Google Workspace kullanıcılarının çoklu seçim menüsünü gösterir.
Kullanıcıları doldurmak için seçim girişi commonDataSource değerini USER olarak ayarlar:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Aşağıdaki kodda, sohbet alanlarının çoklu seçim menüsü gösterilmektedir. Boşlukları doldurmak için seçim girişi hostAppDataSource alanını belirtir. Çoklu seçim menüsü, defaultToCurrentSpace öğesini true olarak da ayarlar. Bu sayede, geçerli alan menüdeki varsayılan seçim olur:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Öğeleri harici bir veri kaynağından doldurma
Çoklu seçim menüleri, üçüncü taraf veya harici veri kaynaklarındaki öğelerle de doldurulabilir. Harici bir veri kaynağı kullanmak için SelectionInput widget'ında, veri kaynağındaki öğeleri sorgulayan ve döndüren işlevi içeren externalDataSource alanını belirtirsiniz.
Harici bir veri kaynağına yapılan istekleri azaltmak için kullanıcılar menüye yazmadan önce çoklu seçim menüsünde görünen önerilen öğeleri ekleyebilirsiniz. Örneğin, kullanıcı için son aranan kişileri doldurabilirsiniz. Önerilen öğeleri harici bir veri kaynağından doldurmak için statik SelectionItem nesnelerini belirtin.
Aşağıdaki kod, öğeleri harici bir veri kaynağından sorgulayan ve dolduran çoklu seçim menüsünü gösterir:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"externalDataSource": { "function": "FUNCTION" },
// Suggested items loaded by default.
// The list is static here but it could be dynamic.
"items": [FUNCTION]
}
}
FUNCTION yerine, harici veritabanını sorgulayan HTTP URL'sini veya Apps Komut Dosyası işlev adını yazın. Önerilen öğelerin nasıl döndürüleceğini gösteren eksiksiz bir örnek için Birden fazla öğe önerme bölümüne bakın.
Etkileşimli widget'lardan veri alma
Kullanıcılar bir düğmeyi tıkladığında etkileşimle ilgili bilgilerle birlikte Chat uygulamalarının işlemi tetiklenir. Etkinlik yükünün commonEventObject bölümünde, formInputs nesnesi kullanıcının girdiği tüm değerleri içerir.
Değerleri, commonEventObject.formInputs.WIDGET_NAME nesnesinden alabilirsiniz. Burada WIDGET_NAME, widget için belirttiğiniz name alanıdır.
Değerler, widget için belirli bir veri türü olarak döndürülür.
Aşağıda, bir kullanıcının her widget için değer girdiği bir etkinlik nesnesinin bir bölümü gösterilmektedir:
{
"commonEventObject": { "formInputs": {
"contactName": { "stringInputs": {
"value": ["Kai 0"]
}},
"contactBirthdate": { "dateInput": {
"msSinceEpoch": 1000425600000
}},
"contactType": { "stringInputs": {
"value": ["Personal"]
}}
}}
}
Chat uygulamanız, verileri almak için kullanıcıların widget'lara girdiği değerleri almak üzere etkinlik nesnesini işler. Aşağıdaki tabloda, belirli bir form girişi widget'ının değerinin nasıl alınacağı gösterilmektedir. Tabloda, her widget için widget'ın kabul ettiği veri türü, değerin etkinlik nesnesinde depolandığı yer ve örnek bir değer gösterilir.
| Form girişi widget'ı | Giriş verilerinin türü | Etkinlik nesnesinden giriş değeri | Örnek değer |
|---|---|---|---|
textInput |
stringInputs |
event.commonEventObject.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
İlk veya tek değeri almak için event.commonEventObject.formInputs.contactType.stringInputs.value[0] |
Personal |
Yalnızca tarihleri kabul eden dateTimePicker. |
dateInput |
event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. |
1000425600000 |
Chat uygulaması verileri aldıktan sonra aşağıdakilerden herhangi birini yapabilir:
- Çoklu seçim menüsü içeren kartlarda, kullanıcının menüye yazdıklarına göre öğeleri doldurun veya önerin.
- Kullanıcının bilgilerini inceleyebilmesi veya formun bir sonraki bölümüne geçebilmesi için verileri başka bir karta aktarın.
- Kullanıcının formu başarıyla doldurduğunu onaylamak için kullanıcıya yanıt verin.
Çoklu seçim öğeleri önerme
Bir kartta öğeleri harici bir veri kaynağından dolduran çoklu seçim menüsü varsa Chat uygulaması, kullanıcıların menüye yazdıklarına göre önerilen öğeleri döndürebilir. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başlarsa Chat uygulamanız, kullanıcı yazmayı bitirmeden önce Atlanta otomatik olarak önerebilir. Sohbet uygulaması en fazla 100 öğe önerebilir.
Çoklu seçim menüsünde öğe önermek ve dinamik olarak doldurmak için karttaki SelectionInput widget'ında harici veri kaynağını sorgulayan bir işlev belirtilmelidir. Önerilen öğeleri döndürmek için işlev aşağıdakileri yapmalıdır:
- Kullanıcılar menüye yazdığında Chat uygulamasının aldığı etkinlik nesnesini işleyin.
- Etkinlik nesnesinden, kullanıcının yazdığı değeri alın. Bu değer,
event.commonEventObject.parameters["autocomplete_widget_query"]alanında gösterilir. - Kullanıcıya önerilecek bir veya daha fazla
SelectionItemsalmak için kullanıcı girişi değerini kullanarak veri kaynağını sorgulayın. - İşlem
RenderActionsöğesinimodifyCardnesnesiyle birlikte döndürerek önerilen öğeleri döndürün.
Aşağıdaki kod örneğinde, bir Chat uygulamasının karttaki çoklu seçim menüsünde öğeleri nasıl dinamik olarak önerdiği gösterilmektedir. Kullanıcı menüye yazdığında, widget'ın externalDataSource alanında sağlanan işlev veya uç nokta, harici bir veri kaynağını sorgular ve kullanıcının seçebileceği öğeler önerir.
Node.js
FUNCTION_URL kısmını, harici veri kaynağını sorgulayan HTTP uç noktasıyla değiştirin.
Python
FUNCTION_URL kısmını, harici veri kaynağını sorgulayan HTTP uç noktasıyla değiştirin.
Java
FUNCTION_URL kısmını, harici veri kaynağını sorgulayan HTTP uç noktasıyla değiştirin.
Apps Komut Dosyası
Verileri başka bir karta aktarma
Bir kullanıcı karttan bilgi gönderdikten sonra aşağıdakilerden herhangi birini yapmak için ek kartlar döndürmeniz gerekebilir:
- Farklı bölümler oluşturarak kullanıcıların daha uzun formları tamamlamasına yardımcı olun.
- Kullanıcıların, yanıtlarını göndermeden önce inceleyebilmesi için ilk karttaki bilgileri önizlemelerine ve onaylamalarına izin verin.
- Formun kalan kısımlarını dinamik olarak doldurun. Örneğin, kullanıcıları randevu oluşturmaya yönlendirmek için bir Chat uygulaması, randevu nedenini soran bir başlangıç kartı gösterebilir ve ardından randevu türüne göre uygun zamanları sağlayan başka bir kartı doldurabilir.
İlk karttan girilen verileri aktarmak için aşağıdaki örnekte gösterildiği gibi, widget'ın name değerini ve kullanıcının girdiği değeri içeren button
widget'ını actionParameters ile oluşturabilirsiniz:
Node.js
{
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "FUNCTION_URL", // Must be an `https` endpoint.
"parameters": [
{
"key": "WIDGET_NAME",
"value": "USER_INPUT_VALUE"
},
// Can specify multiple parameters
]
}}
}]}
}
Apps Komut Dosyası
{
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submitForm",
"parameters": [
{
"key": "WIDGET_NAME",
"value": "USER_INPUT_VALUE"
},
// Can specify multiple parameters
]
}}
}]}
}
Burada WIDGET_NAME, widget'ın name, USER_INPUT_VALUE ise kullanıcının girdiği değerdir. Örneğin, bir kişinin adını toplayan bir metin girişi için widget adı contactName, örnek değer ise Kai O olur.
Kullanıcı düğmeyi tıkladığında Chat uygulamanız, veri alabileceğiniz bir etkinlik nesnesi alır.
Form gönderimine yanıt verme
Chat uygulaması, kart mesajından veya iletişim kutusundan verileri aldıktan sonra, alındığını onaylayarak ya da hata döndürerek yanıt verir.
Aşağıdaki örnekte, bir sohbet uygulaması, kart mesajından gönderilen bir formu başarıyla aldığını onaylamak için kısa mesaj gönderiyor.
Node.js
/**
* Google Cloud Function that handles all Google Workspace Add On events for
* the contact manager app.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.contactManager = function contactManager(req, res) {
const chatEvent = req.body.chat;
const chatMessage = chatEvent.messagePayload.message;
// Handle message payloads in the event object
if(chatEvent.messagePayload) {
return res.send(handleMessage(chatMessage, chatEvent.user));
// Handle button clicks on the card
} else if(chatEvent.buttonClickedPayload) {
switch(req.body.commonEventObject.parameters.actionName) {
case "openDialog":
return res.send(openDialog());
case "openNextCard":
return res.send(openNextCard(req.body));
case "submitForm":
return res.send(submitForm(req.body));
}
}
};
/**
* Submits information from a dialog or card message.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Apps Komut Dosyası
/**
* Sends private text message that confirms submission.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Bir iletişim kutusunu işleyip kapatmak için onay mesajı göndermek, orijinal mesajı veya kartı güncellemek ya da yalnızca iletişim kutusunu kapatmak isteyip istemediğinizi belirten bir RenderActions nesnesi döndürürsünüz. İlgili adımlar için İletişim kutusunu kapatma başlıklı makaleyi inceleyin.
Sorun giderme
Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" mesajı gösterilir. veya "İsteğiniz işlenemiyor." Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç üretir. Örneğin, kart mesajı görünmeyebilir.
Chat kullanıcı arayüzünde hata mesajı gösterilmese de Chat uygulamaları için hata günlüğü kaydı etkinleştirildiğinde hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hataları ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.