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şim kurabilmesi için kart veya iletişim kutusu mesajlarına nasıl widget ve kullanıcı arayüzü öğeleri ekleyeceğiniz açıklanmaktadır.

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

Card Builder'ı açın

Ön koşullar

  • Google Chat'e erişimi olan bir Google Workspace hesabı.
  • Yayınlanmış bir Chat uygulamasıdır. Chat uygulaması oluşturmak için bu quickstart takip edin.

    • Düğme ekle

    ButtonList widget'ında bir dizi düğme gösterilir. Düğmeler bir metni, bir simgeyi veya hem metni hem de bir simgeyi görüntüleyebilir. Her Button, kullanıcı düğmeyi tıkladığında gerçekleşen bir 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 işlevler çalıştıran bir action çalıştırın.

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

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

    Aşağıda, iki düğmeli bir ButtonList widget'ından oluşan kart gösterilmektedir. Bir düğme, Google Chat geliştirici dokümanlarını 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 renkli ve devre dışı bırakılmış bir düğme ekleyin

    "disabled": "true" ayarlarını yaparak kullanıcıların bir düğmeyi tıklamasını engelleyebilirsiniz.

    Aşağıda, iki düğmeli bir ButtonList widget'ından oluşan bir kart gösterilmektedir. Bir düğme, düğmenin arka plan rengini özelleştirmek için Color alanını kullanır. Diğer düğme, Disabled alanıyla devre dışı bırakılır. 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 adet Button widget'ı içeren bir ButtonList widget'ından oluşan 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österilmektedir. İlk düğme bir e-posta simgesi, ikinci düğme ise bir metin gösterir. 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'ında onay kutuları, radyo düğmeleri, anahtarlar veya açılır menüler gibi bir dizi seçilebilir öğe bulunur. Kullanıcılardan tanımlanmış ve standartlaştırılmış verileri toplamak için bu widget'ı kullanabilirsiniz. Kullanıcılardan tanımlanmamış veriler toplamak için TextInput widget'ını kullanın.

    SelectionInput widget'ı, kullanıcıların tek tip veri girmelerine yardımcı olan önerileri ve değişiklik sırasında yapılan işlemleri destekler. Bu işlemler, seçim giriş alanında kullanıcının öğe seçmesi veya seçimini kaldırma gibi bir değişiklik gerçekleştiğinde gerçekleşen Actions işlemidir.

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

    Bu bölümde, SelectionInput widget'ının kullanıldığı kart örnekleri sunulmaktadır. Örneklerde farklı türde bölüm girişleri kullanılmaktadır:

    Onay kutusu ekle

    Aşağıda, onay kutuları kullanan bir SelectionInput widget'ıyla kullanıcıdan bir kişinin profesyonel, kişisel veya her ikisini de belirtmesini isteyen bir iletişim kutusu görüntülenmektedir:

    Radyo düğmesi ekle

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

    Anahtar ekle

    Aşağıda, kullanıcıdan, anahtarları kullanan bir SelectionInput widget'ıyla bir kişinin profesyonel, kişisel veya her ikisini de belirtmesini isteyen bir iletişim kutusu görüntülenir:

    Aşağıda, kullanıcıdan, açılır menü kullanan bir SelectionInput widget'ında kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu yer alır:

    Çoklu seçim menüsü ekle

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

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

    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ı

    Çoklu seçim menüsü öğelerini Google Workspace'te aşağıdaki veri kaynaklarından 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 Google Workspace kuruluşunda ait olduğu alanları görüntüleyebilir ve seçebilir.

    Google Workspace veri kaynaklarını kullanmak için platformDataSource alanını belirtirsiniz. Diğer seçim girişi türlerinin aksine SectionItem nesneleri atlanır çünkü bu seçim öğeleri dinamik olarak Google Workspace'ten alınır.

    Aşağıdaki kodda, Google Workspace kullanıcılarından oluşan ç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ını içeren çok seçimli bir menü gösterilmektedir. Seçim girişi, boşlukları doldurmak için hostAppDataSource alanını belirtir. Çoklu seçim menüsü de defaultToCurrentSpace değerini true olarak ayarlar. Bu da mevcut alanı menüde varsayılan seçim yapar:

    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 bir veri kaynağından gelen öğeleri de doldurabilir. Örneğin, kullanıcının bir müşteri ilişkileri yönetimi (CRM) sisteminden gelen satış potansiyel müşterileri listesinden seçim yapmasına yardımcı olmak için çoklu seçim menülerini kullanabilirsiniz.

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

    Harici bir veri kaynağına gönderilen istekleri azaltmak için, kullanıcılar menüye yazmadan önce çoklu seçim menüsünde görüntülenen önerilen öğeleri ekleyebilirsiniz. Örneğin, kullanıcı için yakın zamanda aranan kişileri doldurabilirsiniz. Önerilen öğeleri harici bir veri kaynağından doldurmak için SelectionItem nesneleri belirtin.

    Aşağıdaki kod, kullanıcıya yönelik harici bir kişi kümesinden öğe içeren çoklu seçim menüsünü gösterir. Menü, varsayılan olarak bir kişi görüntüler ve harici veri kaynağından öğe almak ve doldurmak için getContacts işlevini çalıştırı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ında, kullanıcıların çoklu seçim menüsünden yazmaya başladığı öğeleri otomatik olarak da tamamlayabilirsiniz. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başlarsa Chat uygulamanız, kullanıcı yazmayı tamamlamadan önce otomatik olarak Atlanta önerisinde bulunabilir. 100 adede kadar öğeyi otomatik tamamlayabilirsiniz.

    Öğeleri otomatik olarak tamamlamak için harici veri kaynağını sorgulayan ve bir kullanıcı çoklu seçim menüsünde 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şip eşleşmediğini belirleyin.
    • İşlevler eşleştiğinde harici veri kaynağından önerilen öğeleri döndürün. Kullanıcının yazdıklarına dayalı olarak öğe önermek için autocomplete_widget_query anahtarının değerini alın. Bu değer, kullanıcının menüye ne yazdığını gösterir.

    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 dayalı olarak öğ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 veriler girmelerine yardımcı olan önerileri ve değişiklik sırasında yapılan işlemleri destekler. Bunlar, metin giriş alanında bir kullanıcının metin eklemesi veya silmesi gibi bir değişiklik meydana geldiğinde çalışan Actions işlemleridir.

    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 bölümünü inceleyin.

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

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

    DateTimePicker widget'ı kullanıcıların tarih, saat veya hem tarih hem de saat girmelerine olanak tanır. Alternatif olarak, kullanıcılar tarih ve saat 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 girmelerini isteyen bir hata gösterir.

    Kullanıcıların girdiği tarih ve saat değerlerini işlemek için Form verilerini alma bölümünü inceleyin.

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

    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.