Kartlara etkileşimli kullanıcı arayüzü öğeleri ekleyin

Bu sayfada, kullanıcıların Google Chat uygulamanızla etkileşimde bulunabilmesi için kartlara nasıl widget ve kullanıcı arayüzü öğesi ekleneceği (ör. düğme tıklama veya bilgi gönderme) açıklanmaktadır.

Sohbet uygulamaları, etkileşimli kartlar oluşturmak için aşağıdaki Chat arayüzlerini kullanabilir:

• Bir veya daha fazla kart içeren mesajlar.
• Chat uygulamasıyla doğrudan mesajlarda Ana Sayfa sekmesinden görünen bir kart olan Ana Sayfalar
• İletişim kutuları: İletilerden ve ana sayfalardan yeni bir pencerede açılan kartlardır.

Kullanıcılar kartlarla etkileşimde bulunduğunda Chat uygulamaları, aldıkları verileri işlemek ve buna göre yanıt vermek için kullanabilir. Ayrıntılı bilgi için Google Chat kullanıcılarından bilgi toplama ve bu bilgileri işleme başlıklı makaleyi inceleyin.

Chat uygulamaları için mesajlaşma ve kullanıcı arayüzlerini tasarlamak ve önizlemek üzere Kart Oluşturucu'yu kullanın:

Ön koşullar

Kullanıcı etkileşimlerini alıp yanıtlayacak şekilde yapılandırılmış bir Google Chat uygulaması. Etkileşimli bir Chat uygulaması oluşturmak için kullanmak istediğiniz uygulama mimarisine göre aşağıdaki hızlı başlangıçlardan birini tamamlayın:

• Google Cloud Functions ile HTTP hizmeti
• Google Apps Komut Dosyası
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

Düğme ekleme

ButtonList widget'ında bir dizi düğme gösterilir. Düğmelerde metin, simge veya hem metin hem de simge gösterilebilir. Her Button kullanıcılar düğmeyi tıkladığında gerçekleşen bir OnClick işlemi 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şlevi çalıştıran bir action çalıştırın.

Erişilebilirlik için düğmelerde alternatif metin desteği bulunur.

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

Materyal Tasarım stiline sahip bir düğme ekleme

Aşağıda, farklı Materyal Tasarım düğme stillerinde bir dizi düğme gösterilmektedir.

Materyal Tasarım stilini uygulamak için "color" özelliğini eklemeyin.

Özel renkli ve devre dışı bırakılmış bir düğme ekleme

"disabled": "true" ayarı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ı ile 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 ekleme

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

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

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

Daraltılabilir bölümün düğmesini özelleştirme

Kart içindeki bölümleri daraltıp genişleten kontrol düğmesini özelleştirin. Bölümün içeriğini görsel olarak temsil etmek için çeşitli simgeler veya resimler arasından seçim yapın. Böylece kullanıcılar bilgileri daha kolay anlayıp bunlarla etkileşime geçebilir.

Taşma menüsü ekleme

Overflow menu, ek seçenekler ve işlemler sunmak için sohbet kartlarında kullanılabilir. Bu özellik, kartın arayüzünü karıştırmadan daha fazla seçenek eklemenize olanak tanır ve temiz ve düzenli bir tasarım sağlar.

Çip listesi ekleme

ChipList widget'ı, bilgileri çok yönlü ve görsel açıdan çekici bir şekilde görüntülemenizi sağlar. Etiketleri, kategorileri veya diğer alakalı verileri temsil etmek için çip listelerini kullanarak kullanıcıların içeriğinizde gezinmesini ve içerikle etkileşim kurmasını kolaylaştırın.

Kullanıcılardan bilgi toplama

Bu bölümde, metin veya seçim gibi bilgileri toplayan widget'ları nasıl ekleyebileceğiniz açıklanmaktadır.

Kullanıcıların girdiği bilgileri nasıl işleyeceğinizi öğrenmek için Google Chat kullanıcılarından bilgi toplama ve işleme başlıklı makaleyi inceleyin.

Metin toplama

TextInput widget'ı, kullanıcıların metin girebileceği bir alan sağlar. Bu widget, kullanıcıların tek tip veriler girmesine yardımcı olan önerileri ve metin giriş alanında değişiklik olduğunda (ör. kullanıcı metin eklediğinde veya sildiğinde) çalışan Actions olan değişiklik üzerine işlemleri destekler.

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

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

Tarih veya saat toplama

DateTimePicker widget'ı, kullanıcıların tarih, saat veya hem tarih hem de saat girmesine olanak tanır. Kullanıcılar tarih ve saat seçmek için seçiciyi de kullanabilir. Kullanıcılar geçersiz bir tarih veya saat girerse seçicide, bilgileri doğru şekilde girmelerini isteyen bir hata gösterilir.

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

Kullanıcıların öğe seçmesine izin verme

SelectionInput widget'ı onay kutuları, radyo düğmeleri, anahtarlar veya açılır menü gibi bir dizi seçilebilir öğe sağlar. Bu widget'ı kullanarak kullanıcılardan tanımlanmış ve standartlaştırılmış veriler toplayabilirsiniz. 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 bir seçim giriş alanında değişiklik olduğunda (ör. kullanıcının bir öğeyi seçmesi veya seçimini kaldırması) çalışan Actions olan değişiklik üzerine işlemleri destekler.

Sohbet uygulamaları, seçilen öğelerin değerini alıp işleyebilir. Form girişleriyle çalışma hakkında ayrıntılı bilgi için Kullanıcılar tarafından girilen bilgileri işleme başlıklı makaleyi inceleyin.

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

• Onay kutuları
• Radyo düğmeleri
• Anahtarlar
• Açılır menü
• Çoklu seçim menüsü

Onay kutusu ekleme

Aşağıda, kullanıcının bir kişinin profesyonel, kişisel veya her ikisi de olup olmadığını belirtmesini isteyen bir kart gösterilmektedir. Bu kartta onay kutularını kullanan bir SelectionInput widget'ı bulunur:

Radyo düğmesi ekleme

Aşağıda, kullanıcının bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir kart gösteriliyor. Bu kartta radyo düğmelerini kullanan bir SelectionInput widget'ı yer alıyor:

Anahtar ekleme

Aşağıda, kullanıcının bir kişinin profesyonel mi, kişisel mi yoksa her ikisiyle de mi ilgili olduğunu belirtmesini isteyen bir kart gösterilmektedir. Bu kartta, açma/kapatma düğmelerini kullanan bir SelectionInput widget'ı yer alır:

Açılır menü ekleme

Aşağıda, kullanıcının bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir kart gösterilmektedir. Bu kartta, açılır menü kullanan bir SelectionInput widget'ı yer alır:

Açılır menüleri dinamik olarak doldurma

Google Chat uygulamalarında kullanılabilir.

Açılır menüdeki öğeleri Google Workspace'teki veri kaynaklarından veya harici bir veri kaynağından dinamik olarak doldurabilirsiniz. Dinamik veri kaynaklarını kullanmak için DataSourceConfig nesnelerinden oluşan bir dizi olan data_source_configs alanını belirtirsiniz. Her DataSourceConfig, platformDataSource veya remoteDataSource içerebilir. Şu anda yalnızca bir DataSourceConfig desteklenmektedir.

Google Workspace'teki öğeleri doldurma

Google Workspace kullanıcıları gibi Google Workspace veri kaynaklarındaki öğeleri doldurmak için DataSourceConfig içinde platformDataSource alanını belirtirsiniz. Statik items kullanmanın aksine, bu seçim öğeleri Google Workspace'ten dinamik olarak alındığı için SelectionItem nesnelerini atlıyorsunuz.

Aşağıdaki kodda, Google Workspace kullanıcılarıyla doldurulan bir açılır menü gösterilmektedir:

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "data_source_configs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "min_characters_trigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

Öğeleri harici bir veri kaynağından doldurma

Müşteri ilişkileri yönetimi (CRM) sistemi gibi üçüncü taraf veya harici bir veri kaynağından öğe doldurmak için remoteDataSourceDataSourceConfig alanını kullanarak veri kaynağından öğe döndüren bir işlev belirtebilirsiniz.

Aşağıdaki kodda, getCrmLeads işlevi çalıştırılarak öğeleri harici bir kişi grubundan dolduran bir açılır menü gösterilmektedir:

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "data_source_configs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "min_characters_trigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Dinamik veri kaynağına yapılan istekleri azaltmak için kullanıcılar yazmaya başlamadan önce açılır menüde görünen önerilen öğeleri ekleyebilirsiniz. Ayrıca, min_characters_trigger bölümünde DataSourceConfig ayarını yaparak kullanıcıların yazdıklarına göre öğeleri otomatik olarak tamamlayacak şekilde açılır listeyi de yapılandırabilirsiniz. Kullanıcı, min_characters_trigger içinde belirtilen karakter sayısını yazdığında remoteDataSource içinde belirtilen işlev tetiklenir. İşlevinize iletilen etkinlik nesnesi, kullanıcının girişini autocomplete_widget_query anahtarında içerir.

Çoklu seçim menüsü ekleme

Aşağıda, kullanıcının çoklu seçim menüsünden kişiler seçmesini isteyen bir kart gösterilmektedir:

Çoklu seçim menüsündeki öğeleri Google Workspace'teki 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üleyip seçebilir.

Google Workspace veri kaynaklarını kullanmak için platformDataSource alanını belirtirsiniz. Diğer seçim girişi türlerinden farklı olarak, bu seçim öğeleri Google Workspace'ten dinamik olarak alındığı için SelectionItem nesnelerini atlıyorsunuz.

Aşağıdaki kod, Google Workspace kullanıcılarının çoklu seçim menüsünü gösterir. Kullanıcıları doldurmak için seçim girişi, commonDataSource değerini USER olarak ayarlar:

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

Aşağıdaki kodda, sohbet alanlarının çoklu seçim menüsü gösterilmektedir. Boşlukları doldurmak için seçim girişi hostAppDataSource alanını belirtir. Çoklu seçim menüsü, defaultToCurrentSpace öğesini true olarak da ayarlar. Bu sayede, mevcut alan menüdeki varsayılan seçim olur:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Çoklu seçim menüleri, üçüncü taraf veya harici veri kaynaklarındaki öğelerle de doldurulabilir. Örneğin, bir kullanıcının müşteri ilişkileri yönetimi (CRM) sistemindeki 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 için externalDataSource alanını kullanarak veri kaynağından öğeler döndüren bir işlev belirtirsiniz.

Harici bir veri kaynağına yapılan istekleri azaltmak için kullanıcılar menüye yazmadan önce çoklu seçim menüsünde görünen ö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 objects değerini belirtin.

Aşağıdaki kod örneğinde, harici bir veri kaynağından öğeleri sorgulayan ve dolduran çoklu seçim menüsü gösterilmektedir:

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Önerilen öğeleri dinamik bir veri kaynağından doldurma

Harici veri kaynakları için, kullanıcıların çoklu seçim menüsüne veya açılır menüye yazmaya başladığı öğeleri otomatik olarak tamamlayıp önerebilirsiniz. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başladığında Chat uygulamanız, kullanıcı yazmayı bitirmeden önce Atlanta ifadesini otomatik olarak önerebilir. En fazla 100 öğe önerebilirsiniz.

Önerilen öğeleri döndürmek için harici veri kaynağını sorgulayan işlevin aşağıdakileri yapması gerekir:

1. Kullanıcılar menüye yazdığında Chat uygulamasının aldığı etkinlik nesnesini işleyin.
2. Etkinlik nesnesinden, kullanıcının yazdığı değeri alın. Bu değer, event.commonEventObject.parameters["autocomplete_widget_query"] alanında gösterilir.
3. Kullanıcıya önerilecek bir veya daha fazla SelectionItems almak için kullanıcı girişi değerini kullanarak veri kaynağını sorgulayın.
4. modifyCard nesnesiyle birlikte action RenderActions döndürerek önerilen öğeleri döndürün.

Aşağıdaki kod örneğinde, bir Chat uygulamasının karttaki çoklu seçim menüsünde öğeleri nasıl dinamik olarak önerdiği gösterilmektedir. Kullanıcı menüye yazdığında, widget'ın externalDataSource alanında sağlanan işlev veya uç nokta, harici bir veri kaynağını sorgular ve kullanıcının seçebileceği öğeler önerir:

/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Kartlara girilen verileri doğrulama

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 metin girildiğini veya belirli sayıda karakter girildiğini doğrulayabilirsiniz.

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

Kartın action bölümünde, bir işlemin ihtiyaç duyduğu widget'ların adlarını requiredWidgets listesine ekleyin.

Bu işlem çağrıldığında burada listelenen widget'lardan herhangi birinin değeri yoksa form işlemi gönderimi iptal edilir.

Bir işlem için "all_widgets_are_required": "true" ayarlandığında karttaki tüm widget'lar bu işlem için gereklidir.

Çoklu seçimde all_widgets_are_required işlemi ayarlama

{
  "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
              }
            ]
          }
        }
      ]
    }
  ]
}

dateTimePicker'da all_widgets_are_required işlemi ayarlama

{
  "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üde all_widgets_are_required işlemi ayarlama

{
  "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ğrulama ayarlama

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

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

{
  "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ü ayarlama

{
  "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

Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" veya "İsteğiniz işlenemiyor" 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üğü kaydı 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üzeltmeyle ilgili yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.

İlgili konular

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• DateTimePicker widget'ı

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}