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
.
Chat uygulamaları için JSON kartı mesajlarını tasarlamak ve önizlemek üzere Kart Oluşturucu'yu kullanın:
Card Builder'ı açınKullanı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:
İş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 birActionResponse
parametresiyle yanıt verin. - Hata döndürmek için
"actionStatus": "ERROR MESSAGE"
içeren birActionResponse
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ı
Bu örnekte, kart JSON hatası döndürerek bir kart mesajı gönderilmektedir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz.
/**
* 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 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 bir 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 bölümünü inceleyin.