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ı, Google Workspace verilerinden (ör. Chat alanı) veya dinamik bir veri kaynağından öğeleri doldurup önerebilir. Ayrıntılar için Çoklu seçim menüsü ekleme başlıklı makaleyi inceleyin.

  • 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.

Çoklu seçim menüsü ekleme

Chat uygulamaları, seçim öğelerini özelleştirmek veya kullanıcıların dinamik bir veri kaynağından öğe seçmesine izin vermek için bir tür SelectionInput widget olan çoklu seçim menüleri 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österilmektedir:

Çoklu seçim menüsü için öğeleri aşağıdaki veri kaynaklarından doldurabilirsiniz:

• Kullanıcıları veya kullanıcının üyesi olduğu Chat alanlarını içeren Google Workspace verileri. Menü yalnızca aynı Google Workspace kuruluşundaki öğelerle doldurulur.
• İlişkisel veritabanı gibi harici veri kaynakları. Örneğin, kullanıcının bir müşteri ilişkileri yönetimi (CRM) sisteminden satış potansiyeli müşterileri listesinden seçim yapmasına yardımcı olmak için çoklu seçim menüleri 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ığından SelectionItem nesnelerini çıkarırsınız.

Aşağıdaki kodda, Google Workspace kullanıcılarının çoklu seçim menüsü gösterilmektedir. Kullanıcıları doldurmak için seçim girişi commonDataSource değerini USER olarak ayarlar:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Aşağıdaki kodda, Sohbet alanlarını içeren bir ç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 değerini true olarak da ayarlar. Bu sayede, mevcut alan menüde varsayılan seçim olur:

{
  "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, öğeleri üçüncü taraf veya harici bir veri kaynağından da doldurabilir. 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 nesneleri belirtin.

Aşağıdaki kodda, harici bir veri kaynağından öğeleri sorgulayan ve dolduran çoklu seçim menüsü gösterilmektedir:

{
  "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 tam bir örnek için Çoklu seçimli öğeler önerme bölümüne bakın.

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.

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ığına göre öğe doldurun veya önerin.
• Kullanıcının bilgilerini inceleyebileceği veya formun bir sonraki bölümüne geçebileceği şekilde 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 kart, öğeleri harici bir veri kaynağından dolduran çoklu seçim menüsü içeriyorsa Chat uygulaması, kullanıcıların menüye yazdığı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ı yazma işlemini tamamlamadan önce Atlanta'i otomatik olarak önerebilir. Chat uygulaması en fazla 100 öğe önerebilir.

Çoklu seçim menüsünde öğeleri ö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şlevin aşağıdakileri yapması gerekir:

1. Kullanıcılar menüye yazarken Chat uygulamasının aldığı bir etkinlik nesnesini işleyin.
2. Etkinlik nesnesinden, kullanıcının yazdığı ve event.commonEventObject.parameters["autocomplete_widget_query"] alanında temsil edilen değeri alın.
3. Kullanıcıya önerilecek bir veya daha fazla SelectionItems almak için kullanıcı girişi değerini kullanarak veri kaynağını sorgulayın.
4. İşlemi RenderActions bir modifyCard nesnesi ile döndürerek önerilen öğeleri döndürün.

Aşağıdaki kod örneğinde, bir Chat uygulamasının bir karttaki çoklu seçim menüsünde öğeleri dinamik olarak nasıl önerdiği gösterilmektedir. Kullanıcı menüye bir şey 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 öğeleri önerir.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

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 soran 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 button widget'ını, widget'ın name değerini ve kullanıcının girdiği değeri içeren actionParameters ile oluşturabilirsiniz. Aşağıdaki örnekte gösterildiği gibi:

{
  "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 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."
  }}}}};
}

/**
 * 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.