Kullanıcıların girdiği işlem bilgileri

Bu kılavuzda, kullanıcıların kart mesajlarına ve iletişim kutularına girdiği bilgileri nasıl alacakları ve okuyacakları açıklanmaktadır. Kullanıcılar, Chat uygulamalarının aldığı, okuduğu ve yanıtladığı verileri girebilir. Kullanıcıların bilgi girmesine olanak tanıyan widget'lar aşağıdakileri içerir:

  • Önerileri de destekleyen serbest biçimli metin girişi için TextInput.
  • Onay kutuları, radyo düğmeleri ve açılır menüler gibi liste öğeleri ve menüler için SelectionInput.
  • Tarih ve saat girişleri için DateTimePicker.


Kart Oluşturucu ile kartları tasarlayın ve önizleyin.

Card Builder'ı açın

Kullanıcılardan veri girişi alınması Chat uygulamalarının aşağıdakiler gibi işlemleri yapabilmesini sağlar:

  • Müşteri hizmetleri destek kayıtlarını güncelleme.
  • İş siparişleri oluşturma.
  • Web hizmetleriyle kimlik doğrulayın.

Veri almanın işleyiş şekli

Chat uygulamaları, bilgileri kullanıcıya iletişim kutusu veya kart mesajı olarak sunar. Bu örnekte, kullanıcıdan TextInput ve SelectionInput widget'larını kullanarak kişi hakkında bilgi girmesi istenen bir iletişim kutusu:

Çeşitli widget'ların yer aldığı iletişim kutusu.

İşlem tamamlandığında Chat uygulaması, kullanıcıların iletişim kutusuna girdiği verileri JSON biçiminde alır ve aşağıdaki durumlarda bir etkileşim etkinliği alır:

  • EventType CARD_CLICKED tarihinde.
  • DialogEventType, SUBMIT_DIALOG değerine eşittir (yalnızca iletişim kutuları için).

Kullanıcıların girdileri hakkında veri almak için etkinlik yükündeki Event.common.formInputs alanını kullanın. formInputs alanı, anahtarların her bir widget'a atanan dize kimlikleri olduğu ve değerlerin her widget için kullanıcı girişini temsil ettiği bir haritadır. Farklı nesneler farklı giriş verisi türlerini temsil eder. Örneğin Event.common.formInputs.stringInputs dize girişlerini temsil eder.

Uygulamanız, kullanıcı tarafından girilen ilk değere event.common.formInputs.NAME.stringInputs.value[0] üzerinden erişebilir. Burada NAME, TextInput widget'ının name alanıdır.

Kartlardan veri alma

Kullanıcı, kart mesajına veri girdiğinde Chat uygulamanız aşağıdaki örneğe benzer bir Chat uygulaması etkileşim etkinliği alır:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

İletişim kutularından veri alma

Bir kullanıcı iletişim kutusunda veri gönderdiğinde Chat uygulamanız aşağıdaki örnekteki gibi başka bir Chat uygulaması etkileşim etkinliği alır:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Bir kart mesajından veya iletişim kutusundan toplanan verilere yanıt verme

Bir kart mesajından veya iletişim kutusundan veriler alındıktan sonra Chat uygulaması, makbuzu onaylayarak veya bir hata döndürerek yanıt verir. Her iki işlem de bir ActionResponse döndürerek yapılır:

  • Makbuzun başarıyla alındığını onaylamak için "actionStatus": "OK" içeren bir ActionResponse parametresiyle yanıt verin.
  • Hata döndürmek için "actionStatus": "ERROR MESSAGE" içeren bir ActionResponse parametresiyle yanıt verin.

Örnek

Aşağıdaki örnekte, name değerinin mevcut olup olmadığı kontrol edilir. Bu yoksa uygulama hata döndürür. Varsa uygulama, form verilerinin alındığını onaylar ve iletişim kutusunu kapatır.

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Apps Komut Dosyası

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

Sorun giderme

Bir Google Chat uygulaması veya kart hata döndürdüğünde Chat arayüzünde "Bir sorun oluştu." veya "İsteğiniz işleme alınamıyor" mesajı gösterilir. 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ük kaydı etkinken hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri mevcuttur. Hataları görüntüleme, hata ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.