Etkileşimli kart veya iletişim kutusu tasarlama

Bu sayfada, kullanıcıların bir düğmeyi tıklayarak veya bilgi göndererek Google Chat uygulamanızla etkileşimde bulunabilmesi için kart veya iletişim mesajlarına widget ve kullanıcı arayüzü öğelerinin nasıl ekleneceği açıklanmaktadır.


Chat uygulamaları için JSON kart mesajları tasarlayıp önizlemek üzere Kart Oluşturucu'yu kullanın:

Kart Oluşturucu'yu açın

Ön koşullar

  • Google Chat'e erişimi olan bir Google Workspace hesabı.
  • Yayınlanan bir Chat uygulamasıdır. Chat uygulaması oluşturmak için bu quickstart takip edin.
  • Düğme ekle

    ButtonList widget'ı bir dizi düğmeyi görüntüler. Düğmeler metin, simge veya hem metin hem de simge görüntüleyebilir. Her bir Button, kullanıcılar düğmeyi tıkladığında gerçekleşen OnClick işlemini destekler. Örneğin:

    • Kullanıcılara ek bilgi sağlamak için OpenLink ile bir köprü açın.
    • API çağırma gibi özel bir işlev çalıştıran action çalıştırın.

    Erişilebilirlik için düğmeler alternatif metni destekler.

    Özel işlev çalıştıran bir düğme ekleme

    Aşağıda, iki düğmeli bir ButtonList widget'ından oluşan bir kart gösterilmektedir. Bir düğme, Google Chat geliştirici belgelerini yeni bir sekmede açar. Diğer düğme, goToView() adlı özel bir işlevi çalıştırır ve viewType="BIRD EYE VIEW" parametresini iletir.

    Özel renk ve devre dışı bırakılmış düğme içeren bir düğme ekleyin

    "disabled": "true" ayarlayarak kullanıcıların bir düğmeyi tıklamalarını engelleyebilirsiniz.

    Aşağıda, iki düğmeli ButtonList widget'ından oluşan bir kart görüntülenmektedir. Bir düğmenin arka plan rengini özelleştirmek için Color alanı kullanılır. Diğer düğme, Disabled alanıyla devre dışı bırakıldı. Bu durum, kullanıcının düğmeyi tıklamasını ve işlevi yürütmesini engeller.

    Simge içeren bir düğme ekleyin

    Aşağıda, iki simgeli Button widget'ının bulunduğu ButtonList widget'ından oluşan bir kart gösterilmektedir. Bir düğme, Google Chat'in yerleşik e-posta simgesini görüntülemek için knownIcon alanını kullanır. Diğer düğme, özel simge widget'ını görüntülemek için iconUrl alanını kullanır.

    Simge ve metin içeren bir düğme ekleyin

    Aşağıda, kullanıcıdan e-posta göndermesini isteyen ButtonList widget'ından oluşan bir kart görüntülenir. İlk düğme bir e-posta simgesini, ikinci düğmede metin görüntülenir. Kullanıcı, sendEmail işlevini çalıştırmak için simgeyi veya metin düğmesini tıklayabilir.

    Seçilebilir kullanıcı arayüzü öğeleri ekleyin

    SelectionInput widget'ı onay kutuları, radyo düğmeleri, anahtarlar veya açılır menü gibi bir dizi seçilebilir öğe sunar. Bu widget'ı, kullanıcılardan tanımlanmış ve standartlaştırılmış veriler toplamak için kullanabilirsiniz. Kullanıcılardan tanımlanmamış veriler toplamak için bunun yerine TextInput widget'ını kullanın.

    SelectionInput widget'ı, kullanıcıların tek tip veri girmesine yardımcı olan önerileri ve seçim giriş alanında bir değişiklik gerçekleştiğinde (ör. kullanıcının bir öğeyi seçmesi veya seçimini kaldırması) çalıştırılan Actions işlemlerini destekler.

    Chat uygulamaları, seçilen öğelerin değerini alıp işleyebilir. Form girişleriyle çalışma hakkında ayrıntılar için Form verilerini alma bölümüne bakın.

    Bu bölümde, SelectionInput widget'ını kullanan kartlara örnekler verilmiştir. Örneklerde farklı bölüm girişleri kullanılmaktadır:

    Onay kutusu ekle

    Aşağıdakiler, onay kutuları kullanan bir SelectionInput widget'ı ile kullanıcıdan bir kişinin profesyonel mi, kişisel mi yoksa her ikisinin birden mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntüler:

    Radyo düğmesi ekle

    Aşağıdakiler, radyo düğmeleri kullanan bir SelectionInput widget'ı ile kullanıcıdan bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntüler:

    Anahtar ekleme

    Aşağıda, anahtarlardan yararlanan bir SelectionInput widget'ı ile kullanıcıdan bir kişinin profesyonel mi, kişisel mi yoksa her ikisinin mi olduğuna karar vermesini isteyen bir iletişim kutusu görüntülenir:

    Aşağıdakiler, açılır menü kullanan bir SelectionInput widget'ı ile kullanıcıdan bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntüler:

    Çoklu seçim menüsü ekle

    Aşağıda, kullanıcıdan çoklu seçim menüsünden kişileri seçmesini isteyen bir iletişim kutusu görüntülenmektedir:

    Çoklu seçim menüleri için veri kaynaklarını kullanma

    Aşağıdaki bölümde, Google Workspace uygulaması veya harici veri kaynağı gibi dinamik kaynaklardan veri doldurmak için çoklu seçim menülerinin nasıl kullanılacağı açıklanmaktadır.

    Google Workspace'teki veri kaynakları

    Google Workspace'te aşağıdaki veri kaynaklarından çoklu seçim menüsü öğelerini doldurabilirsiniz:

    • Google Workspace kullanıcıları: Yalnızca aynı Google Workspace kuruluşundaki kullanıcıları doldurabilirsiniz.
    • Chat alanları: Çoklu seçim menüsüne öğe giren kullanıcı, yalnızca kendi Google Workspace kuruluşunda ait olduğu alanları görüntüleyip seçebilir.

    Google Workspace veri kaynaklarını kullanmak için platformDataSource alanını belirtirsiniz. Diğer seçim giriş türlerinin aksine, SectionItem nesneleri dinamik olarak Google Workspace kaynaklı olduğu için hariç tutulur.

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

    JSON

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

    Aşağıdaki kodda, Chat alanları için bir çoklu seçim menüsü gösterilmektedir. Seçim girişi, alanları doldurmak için hostAppDataSource alanını belirtir. Çoklu seçim menüsü, mevcut alanı menüdeki varsayılan seçim haline getiren defaultToCurrentSpace değerini de true olarak ayarlar:

    JSON

    {
      "selectionInput": {
        "name": "spaces",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 3,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "hostAppDataSource": {
            "chatDataSource": {
              "spaceDataSource": {
                "defaultToCurrentSpace": true
              }
            }
          }
        }
      }
    }
    
    Google Workspace dışındaki veri kaynakları

    Çoklu seçim menüleri, üçüncü taraf veya harici veri kaynağındaki öğeleri de doldurabilir. Örneğin, bir kullanıcının bir müşteri ilişkileri yönetimi (CRM) sistemindeki potansiyel müşteriler listesinden seçim yapmasına yardımcı olmak için çoklu seçim menülerini kullanabilirsiniz.

    Harici bir veri kaynağı kullanmak isterseniz veri kaynağındaki öğeleri döndüren bir işlev belirtmek için externalDataSource alanını kullanırsınız.

    Harici bir veri kaynağına gönderilen isteklerin sayısını azaltmak için, kullanıcılar menüye yazmadan önce çoklu seçim menüsünde gösterilecek önerilen öğeleri dahil edebilirsiniz. Örneğin, kullanıcı için son aranan kişileri doldurabilirsiniz. Harici bir veri kaynağından önerilen öğeleri doldurmak için SelectionItem nesneleri belirtin.

    Aşağıdaki kod, kullanıcının harici bir kişi grubundan öğelerin yer aldığı bir çoklu seçim menüsünü göstermektedir. Menüde varsayılan olarak bir kişi gösterilir ve harici veri kaynağından öğe alıp doldurmak için getContacts işlevi çalıştırılır:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

    Harici veri kaynakları için kullanıcıların çoklu seçim menüsünde yazmaya başladığı öğeleri otomatik olarak tamamlayabilirsiniz. Örneğin, bir kullanıcı ABD'deki şehirlerin doldurulduğu bir menü için Atl yazmaya başlarsa Chat uygulamanız, kullanıcı yazmayı tamamlamadan Atlanta önce otomatik olarak öneride bulunabilir. En fazla 100 öğeyi otomatik tamamlayabilirsiniz.

    Öğeleri otomatik olarak tamamlamak için harici veri kaynağını sorgulayan ve bir kullanıcı çoklu seçim menüsüne her yazdığında öğeleri döndüren bir işlev oluşturursunuz. İşlev aşağıdakileri yapmalıdır:

    • Kullanıcının menüyle etkileşimini temsil eden bir etkinlik nesnesi iletin.
    • Etkileşim etkinliğinin invokedFunction değerinin, externalDataSource alanındaki işlevle eşleştiğini belirleyin.
    • İşlevler eşleştiğinde, harici veri kaynağından önerilen öğeleri döndürün. Kullanıcının yazdıklarına göre öğe önermek için autocomplete_widget_query anahtarının değerini alın. Bu değer, kullanıcının menüde yazdığı şeyi temsil eder.

    Aşağıdaki kod, harici bir veri kaynağındaki öğeleri otomatik olarak tamamlar. Önceki örneğe göre Chat uygulaması, getContacts işlevinin tetiklendiği zamana göre öğeler önerir:

    Apps Komut Dosyası

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Kullanıcının metin girebileceği bir alan ekleyin

    TextInput widget'ı, kullanıcıların metin girebileceği bir alan sağlar. Widget, kullanıcıların tek tip veri girmesine yardımcı olan önerileri ve metin giriş alanında bir değişiklik olduğunda (kullanıcının metin eklemesi veya silmesi gibi) çalıştırılan Actions işlemlerini destekler.

    Kullanıcılardan soyut veya bilinmeyen veriler toplamanız gerektiğinde bu TextInput widget'ını kullanın. Kullanıcılardan tanımlanmış verileri toplamak için SelectionInput widget'ını kullanın.

    Kullanıcıların girdiği metni işlemek için Form verilerini alma başlıklı makaleye göz atın.

    Aşağıda, TextInput widget'ından oluşan bir kart gösterilmektedir:

    Kullanıcının tarih ve saat seçmesine izin verme

    DateTimePicker widget'ı kullanıcıların tarih, saat veya hem tarih hem de saat girmesini sağlar. Alternatif olarak, kullanıcılar tarih ve saatleri seçmek için seçiciyi kullanabilir. Kullanıcılar geçersiz bir tarih veya saat girerse seçici, kullanıcılardan bilgileri doğru şekilde girmelerini isteyen bir hata gösterir.

    Kullanıcıların girdiği tarih ve saat değerlerini işlemek için Form verilerini alma başlıklı makaleyi inceleyin.

    Aşağıda, üç farklı türde DateTimePicker widget'ından oluşan bir kart gösterilmektedir:

    Kartlara girilen verileri doğrulayın

    Bu sayfada, bir kartın action ve widget'larına girilen verilerin nasıl doğrulanacağı açıklanmaktadır. Örneğin, bir metin giriş alanına kullanıcı tarafından girilen metni veya belirli sayıda karakter içerdiğini doğrulayabilirsiniz.

    İşlemler için gerekli widget'ları ayarla

    Kartın action parçası olarak bir işlemin requiredWidgets listesine bir işlem yapması gereken widget adlarını ekleyin.

    Bu işlem çağrıldığında burada listelenen widget'lardan herhangi biri bir değere sahip değilse form işlemi gönderme işlemi iptal edilir.

    "all_widgets_are_required": "true" bir işlem için ayarlandığında, bu işlemin karttaki tüm widget'ları kullanması gerekir.

    Çoklu seçimde bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
      "sections": [
        {
          "header": "Select contacts",
          "widgets": [
            {
              "selectionInput": {
                "type": "MULTI_SELECT",
                "label": "Selected contacts",
                "name": "contacts",
                "multiSelectMaxSelectedItems": 3,
                "multiSelectMinQueryLength": 1,
                "onChangeAction": {
                  "all_widgets_are_required": true
                },
                "items": [
                  {
                    "value": "contact-1",
                    "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                    "text": "Contact 1",
                    "bottomText": "Contact one description",
                    "selected": false
                  },
                  {
                    "value": "contact-2",
                    "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                    "text": "Contact 2",
                    "bottomText": "Contact two description",
                    "selected": false
                  },
                  {
                    "value": "contact-3",
                    "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                    "text": "Contact 3",
                    "bottomText": "Contact three description",
                    "selected": false
                  },
                  {
                    "value": "contact-4",
                    "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                    "text": "Contact 4",
                    "bottomText": "Contact four description",
                    "selected": false
                  },
                  {
                    "value": "contact-5",
                    "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                    "text": "Contact 5",
                    "bottomText": "Contact five description",
                    "selected": false
                  }
                ]
              }
            }
          ]
        }
      ]
    }
    

    dateTime Picker'da bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
      "sections": [
        {
          "widgets": [
            {
              "textParagraph": {
                "text": "A datetime picker widget with both date and time:"
              }
            },
            {
              "divider": {}
            },
            {
              "dateTimePicker": {
                "name": "date_time_picker_date_and_time",
                "label": "meeting",
                "type": "DATE_AND_TIME"
              }
            },
            {
              "textParagraph": {
                "text": "A datetime picker widget with just date:"
              }
            },
            {
              "divider": {}
            },
            {
              "dateTimePicker": {
                "name": "date_time_picker_date_only",
                "label": "Choose a date",
                "type": "DATE_ONLY",
                "onChangeAction":{
                  "all_widgets_are_required": true
                }
              }
            },
            {
              "textParagraph": {
                "text": "A datetime picker widget with just time:"
              }
            },
            {
              "divider": {}
            },
            {
              "dateTimePicker": {
                "name": "date_time_picker_time_only",
                "label": "Select a time",
                "type": "TIME_ONLY"
              }
            }
          ]
        }
      ]
    }
    

    Açılır menüden bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
      "sections": [
        {
          "header": "Section Header",
          "collapsible": true,
          "uncollapsibleWidgetsCount": 1,
          "widgets": [
            {
              "selectionInput": {
                "name": "location",
                "label": "Select Color",
                "type": "DROPDOWN",
                "onChangeAction": {
                  "all_widgets_are_required": true
                },
                "items": [
                  {
                    "text": "Red",
                    "value": "red",
                    "selected": false
                  },
                  {
                    "text": "Green",
                    "value": "green",
                    "selected": false
                  },
                  {
                    "text": "White",
                    "value": "white",
                    "selected": false
                  },
                  {
                    "text": "Blue",
                    "value": "blue",
                    "selected": false
                  },
                  {
                    "text": "Black",
                    "value": "black",
                    "selected": false
                  }
                ]
              }
            }
          ]
        }
      ]
    }
    

    Metin girişi widget'ı için doğrulamayı ayarlama

    textInput widget'ının doğrulama alanında, bu metin girişi widget'ı için karakter sınırlamasını ve giriş türünü belirtebilir.

    Metin girişi widget'ı için karakter sınırlaması ayarlayın

    JSON

    {
      "sections": [
        {
          "header": "Tell us about yourself",
          "collapsible": true,
          "uncollapsibleWidgetsCount": 2,
          "widgets": [
            {
              "textInput": {
                "name": "favoriteColor",
                "label": "Favorite color",
                "type": "SINGLE_LINE",
                "validation": {"character_limit":15},
                "onChangeAction":{
                  "all_widgets_are_required": true
                }
              }
            }
          ]
        }
      ]
    }
    

    Metin girişi widget'ı için giriş türünü ayarlayın

    JSON

    {
      "sections": [
        {
          "header": "Validate text inputs by input types",
          "collapsible": true,
          "uncollapsibleWidgetsCount": 2,
          "widgets": [
            {
              "textInput": {
                "name": "mailing_address",
                "label": "Please enter a valid email address",
                "type": "SINGLE_LINE",
                "validation": {
                  "input_type": "EMAIL"
                },
                "onChangeAction": {
                  "all_widgets_are_required": true
                }
              }
            },
            {
              "textInput": {
                "name": "validate_integer",
                "label": "Please enter a number",
                  "type": "SINGLE_LINE",
                "validation": {
                  "input_type": "INTEGER"
                }
              }
            },
            {
              "textInput": {
                "name": "validate_float",
                "label": "Please enter a number with a decimal",
                "type": "SINGLE_LINE",
                "validation": {
                  "input_type": "FLOAT"
                }
              }
            }
          ]
        }
      ]
    }
    

    Sorun giderme

    Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir sorun oluştu" mesajı gösterilir. veya "İsteğiniz işlenemiyor." Bazı durumlarda Chat kullanıcı arayüzünde herhangi bir 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örüntülenmese de Chat uygulamaları için hata günlük kaydı etkinleştirildiğinde hataları düzeltmenize yardımcı olmak amacıyla açıklayıcı hata mesajları ve günlük verileri sunulur. Hataları görüntüleme, hata ayıklama ve düzeltme konusunda yardım almak için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.