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.

Çeşitli widget'ların yer aldığı bir iletişim kutusu.
Şekil 1: İletişim bilgilerini toplamak için iletişim kutusu açan örnek bir Chat uygulaması.

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

Node.js

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Python

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Java

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Apps Komut Dosyası'nda etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

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 mesajlar
  • Chat uygulamasındaki doğrudan mesajlarda Ana Sayfa sekmesinde görünen bir kart olan Ana sayfalar.
  • 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:

Bu iletişim formunu kullanan bir Chat uygulaması örneği için aşağıdaki koda bakın:

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Komut Dosyası

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Bilgi toplamak için kullanabileceğiniz etkileşimli widget'lar hakkında daha fazla örnek için 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 tıkladığında Chat uygulamaları, etkileşimle ilgili bilgileri içeren bir CARD_CLICKED etkileşim etkinliği alır. CARD_CLICKED etkileşim etkinliklerinin yükü, kullanıcının girdiği tüm değerleri içeren bir common.formInputs nesnesi içerir.

Değerleri common.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 (Inputs nesnesi olarak temsil edilir).

Aşağıda, kullanıcının her widget için değer girdiği bir CARD_CLICKED etkileşim etkinliğinin bir kısmı gösterilmektedir:

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Komut Dosyası 

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

Chat uygulamanız, kullanıcıların widget'lara girdikleri değerleri almak için etkileşim etkinliğini yöneterek verileri 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 etkileşim etkinliğinde depolandığı yer ve örnek bir değer gösterilir.

Form girişi widget'ı Giriş verisinin türü Etkileşim etkinliğinden alınan giriş değeri Örnek değer
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs İlk veya tek değeri almak için event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker yalnızca tarihleri kabul eder. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

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 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:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Komut Dosyası

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Kullanıcı düğmeyi tıkladığında Chat uygulamanız bir CARD_CLICKED etkileşim etkinliği alır. Bu etkinlikten veri alabilirsiniz.

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ı, bir iletişim kutusundan veya kart mesajından gönderilen bir formu başarıyla aldığını onaylamak için kısa mesaj göndermektedir.

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps Komut Dosyası

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

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