Google Chat kullanıcılarından bilgi toplama ve işleme

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.

Google Chat'te eklentiler kullanıcılara Google Chat uygulamaları olarak görünür. Daha fazla bilgi edinmek için Google Chat'i genişletme başlıklı makaleyi inceleyin.

Chat uygulamaları, Chat'te veya Chat dışında işlem yapmak için aşağıdakiler de dahil olmak üzere kullanıcılardan bilgi ister:

• Ayarları yapılandırın. Örneğin, kullanıcıların bildirim ayarlarını özelleştirmesine veya Chat uygulamasını yapılandırıp bir veya daha fazla alana 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 verme. Örneğin, bir Chat uygulaması kullanıcıların destek kaydının durumunu doğrudan Chat alanından güncellemelerine yardımcı olabilir.

Ön koşullar

Kartları kullanarak form oluşturma

Chat uygulamaları, bilgi toplamak için formları ve girişlerini tasarlayıp 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ı.
• Mesajlardan ve ana sayfalardan yeni bir pencerede açılan kartlar olan iletişim kutuları.

Chat uygulamaları, aşağıdaki widget'ları kullanarak kartları oluşturabilir:

• Kullanıcılardan bilgi isteyen form giriş widget'ları. İsteğe bağlı olarak, kullanıcıların bilgileri doğru şekilde girip biçimlendirdiğinden emin olmak için form giriş widget'larına doğrulama ekleyebilirsiniz. Chat uygulamaları aşağıdaki form giriş 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ş widget'ları, statik veya dinamik veri kaynaklarından öğelerle de doldurulabilir. Örneğin, kullanıcılar üyesi oldukları Chat alanları listesinden seçim yapabilir.
  • Tarih ve saat girişleri için tarih saat seçicileri (dateTimePicker).

• Kullanıcıların karta girdikleri değerleri gönderebilmesi için bir 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 toplar:

Bilgi toplamak için kullanabileceğiniz etkileşimli widget'lara dair daha fazla örnek için Google Chat API dokümanlarında Etkileşimli kart veya iletişim kutusu tasarlama başlıklı makaleyi inceleyin.

Etkileşimli widget'lardan veri alma

Kullanıcılar bir düğmeyi her tıkladığında, düğmenin Chat uygulamaları işlemi, etkileşimle ilgili bilgilerle birlikte tetiklenir. Etkinlik yükü commonEventObject bölümündeki 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, 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 etkinlik nesnesini yöneterek kullanıcıların widget'lara girdikleri değerleri alır. Aşağıdaki tabloda, belirli bir form giriş 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.

Verileri başka bir karta aktarma

Bir kullanıcı bir karttan bilgi gönderdikten sonra aşağıdakilerden herhangi birini yapmak için ek kartlar göndermeniz gerekebilir:

• Farklı bölümler oluşturarak kullanıcıların daha uzun formları doldurmasına yardımcı olun.
• Kullanıcıların, göndermeden önce yanıtlarını gözden geçirebilmeleri için ilk karttaki bilgileri önizlemesine ve onaylamasına izin verin.
• Formun geri kalan bölümlerini dinamik olarak doldurun. Örneğin, bir Chat uygulaması, kullanıcılardan randevu oluşturmalarını istemek için randevunun nedenini isteyen bir ilk kart gösterebilir ve ardından randevu türüne göre müsait saatleri gösteren başka bir kart doldurabilir.

İlk karttaki veri girişini 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 actionParameters ile button widget'ını oluşturabilirsiniz:

{
  "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 değeri, 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 ve örnek değer Kai O olur.

Kullanıcı düğmeyi tıkladığında Chat uygulamanız, veri alabileceğiniz bir etkinlik nesnesi alır.

Form gönderimlerine yanıt verme

Chat uygulaması, kart mesajından veya iletişim kutusunda alınan verileri aldıktan sonra, yanıtı kabul ederek veya bir hata döndürerek yanıt verir.

Aşağıdaki örnekte, bir Chat uygulaması, kart mesajından gönderilen bir formu başarıyla aldığını onaylamak için kısa mesaj göndermektedir.

/**
 * 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 events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } 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."
  }}}}};
}

/**
 * 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şlemek ve kapatmak için onay mesajı göndermek, orijinal mesajı veya kartı güncellemek ya da yalnızca iletişim kutusunu kapatmak istediğinizi belirten bir RenderActions nesnesi döndürürsünüz. 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ç verir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmeyebilir ancak Chat uygulamaları için hata günlüğü 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, hata ayıklama ve düzeltme hakkında yardım için Google Chat hatalarını giderme başlıklı makaleyi inceleyin.