양방향 카드 또는 대화상자 디자인

이 페이지에서는 카드 또는 대화상자 메시지에 위젯 및 UI 요소를 추가하는 방법을 설명합니다. 이를 통해 사용자는 다음과 같이 Google Chat 앱과 상호작용할 수 있습니다. 버튼을 클릭하거나 정보를 제출하는 것과 같습니다.

카드 빌더를 사용하여 채팅 앱용 JSON 카드 메시지를 디자인하고 미리 봅니다.

카드 빌더 열기

기본 요건

  • Google Workspace 계정 액세스 권한이 있는 사용자 Google Chat
  • 게시된 채팅 앱 새로운 채팅 앱, 팔로우하기 빠른 시작:

    • 버튼 추가

    이 ButtonList 위젯 버튼 집합을 표시합니다. 버튼은 텍스트, 아이콘 또는 텍스트와 아이콘을 모두 사용할 수 있습니다. 각 Button 는 작업 OnClick개 사용자가 버튼을 클릭하면 발생하는 프로세스입니다. 예를 들면 다음과 같습니다.

    • 다음으로 하이퍼링크 열기 OpenLink님, 을 통해 사용자에게 추가 정보를 제공할 수 있습니다.
    • 다음을 실행합니다. action 커스텀 함수를 실행하는 API입니다.

    접근성을 위해 버튼은 대체 텍스트를 지원합니다.

    맞춤 함수를 실행하는 버튼 추가

    다음은 두 개의 버튼이 있는 ButtonList 위젯으로 구성된 카드입니다. 버튼 하나로 Google Chat 개발자 문서가 새 탭에서 열립니다. 이 goToView()라는 맞춤 함수를 실행하고 viewType="BIRD EYE VIEW" 매개변수

    맞춤 색상 및 비활성화된 버튼이 있는 버튼 추가

    "disabled": "true"를 설정하여 사용자가 버튼을 클릭하지 못하게 할 수 있습니다.

    다음은 두 개의 ButtonList 위젯으로 구성된 카드를 보여줍니다. 버튼을 클릭합니다. 버튼 하나로는 Color 필드 버튼의 배경을 맞춤설정할 수 있습니다. color[색상] 다른 버튼은 Disabled 필드로 비활성화됩니다. 사용자가 버튼을 클릭하여 기능을 실행하지 못하게 합니다.

    아이콘이 있는 버튼 추가

    다음은 두 개의 아이콘이 있는 ButtonList 위젯으로 구성된 카드를 보여줍니다. Button 위젯 버튼 하나로는 knownIcon 필드를 클릭하여 Google Chat에 내장된 이메일 아이콘을 표시합니다. 다른 버튼은 iconUrl 필드를 사용하여 맞춤 아이콘 위젯입니다.

    아이콘과 텍스트가 있는 버튼 추가

    다음은 메시지를 표시하는 ButtonList 위젯으로 구성된 카드를 보여줍니다. 이메일을 보낼 수 있습니다 첫 번째 버튼은 이메일 아이콘과 두 번째 버튼은 텍스트를 표시합니다. 사용자가 아이콘 또는 텍스트를 클릭할 수 있음 버튼을 클릭하여 sendEmail 함수를 실행합니다.

    선택 가능한 UI 요소 추가

    SelectionInput 위젯 체크박스, 라디오 버튼, 스위치, 드롭다운 메뉴를 선택할 수 있습니다 이 위젯을 사용하여 정의되고 표준화된 데이터를 수집할 수 있습니다. 정의되지 않은 데이터 수집 대신 TextInput 위젯을 사용하세요.

    SelectionInput 위젯은 사용자가 유니폼을 입력하는 데 도움이 되는 추천을 지원합니다. 데이터, 변경 시 작업(즉, Actions 입력 필드가 변경될 때 실행되는 실행되며, 항목 선택 또는 선택 취소입니다.

    채팅 앱은 선택된 항목의 값을 수신하고 처리할 수 있습니다. 양식 입력 작업에 관한 자세한 내용은 다음을 참고하세요. 사용자가 입력한 정보를 처리합니다.

    이 섹션에서는 SelectionInput 위젯을 사용하는 카드의 예를 제공합니다. 예에서는 다양한 유형의 섹션 입력을 사용합니다.

    체크박스 추가

    다음은 사용자에게 연락처는 직업, 개인 또는 둘 다에 해당하며 다음과 같은 SelectionInput 위젯을 사용합니다. 체크박스를 사용합니다.

    라디오 버튼 추가

    다음은 사용자에게 다음을 사용하는 SelectionInput 위젯을 통해 업무적인 또는 개인적인 연락처 사용 라디오 버튼:

    스위치 추가

    다음은 사용자에게 직장 연락처, 개인 연락처 등 둘 다에 사용할 수 있는 SelectionInput 위젯입니다. 스위치 사용:

    다음은 사용자에게 다음을 사용하는 SelectionInput 위젯을 통해 업무적인 또는 개인적인 연락처 사용 드롭다운 메뉴:

    다중 선택 메뉴 추가

    다음은 사용자에게 연락처를 선택하도록 요청하는 대화상자를 표시합니다. 를 여러 개 선택할 수 있습니다.

    다중 선택 메뉴에 데이터 소스 사용

    다음 섹션에서는 다중 선택 메뉴를 사용하여 데이터를 채우는 방법을 설명합니다. Google Workspace 애플리케이션과 같은 동적 소스 또는 외부 데이터 있습니다.

    Google Workspace의 데이터 소스

    다음 데이터 소스에서 다중 선택 메뉴의 항목을 채울 수 있습니다. Google Workspace

    • Google Workspace 사용자: 동일한 Google Workspace 조직에 액세스할 수 있습니다
    • Chat 스페이스: 사용자가 다중 선택 항목에 항목을 입력하는 경우 메뉴는 그룹 내에서 자신이 속한 스페이스만 보고 선택할 수 Google Workspace 조직입니다.

    Google Workspace 데이터 소스를 사용하려면 platformDataSource 필드를 확인합니다. 다른 선택 입력 유형과 달리 SectionItem 이러한 선택 항목은 Google Workspace

    다음 코드는 Google Workspace 사용자의 다중 선택 메뉴를 보여줍니다. 사용자를 채우기 위해 선택 입력은 commonDataSource를 USER로 설정합니다.

    JSON

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

    다음 코드는 Chat의 다중 선택 메뉴를 보여줍니다. 스페이스. 공백을 채우기 위해 선택 입력은 hostAppDataSource 필드 또한 다중 선택 메뉴는 defaultToCurrentSpace에서 true로 변경: 현재 스페이스를 기본값으로 설정 선택할 수 있습니다.

    JSON

    {
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
    Google Workspace 외부의 데이터 소스

    다중 선택 메뉴에서 서드 파티 데이터 또는 외부 데이터의 항목을 채울 수도 있습니다. 있습니다. 예를 들어 다중 선택 메뉴를 사용하면 사용자가 고객 관계 관리 (CRM) 시스템의 판매 리드 목록

    외부 데이터 소스를 사용하려면 externalDataSource 필드를 사용하여 다음을 수행합니다. 데이터 소스에서 항목을 반환하는 함수를 지정합니다.

    외부 데이터 소스에 대한 요청을 줄이려면 다음을 포함할 수 있습니다. 사용자가 입력하기 전에 다중 선택 메뉴에 표시되는 추천 항목 메뉴 예를 들어 있습니다. 외부 데이터 소스에서 추천 항목을 채우려면 다음을 지정합니다. SelectionItem 객체입니다.

    다음 코드는 사용자의 외부 연락처입니다. 메뉴에 기본적으로 연락처 1개가 표시됩니다. 그런 다음 getContacts 함수를 실행하여 외부 데이터 소스:

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

    외부 데이터 소스의 경우 사용자가 시작하는 항목을 자동 완성할 수도 있습니다. 여러 옵션을 선택할 수도 있습니다 예를 들어 사용자가Atl 미국 도시를 채우는 메뉴, 채팅 앱이 사용자보다 먼저 Atlanta를 자동 제안할 수 있음 입력을 완료할 수 있습니다. 최대 100개의 항목을 자동 완성할 수 있습니다.

    항목을 자동 완성하려면 외부 데이터를 쿼리하는 함수를 만듭니다. 사용자가 다중 선택 메뉴에 입력할 때마다 항목을 반환하고 반환합니다. 이 함수는 다음을 실행해야 합니다.

    • 메뉴와의 사용자 상호작용을 나타내는 이벤트 객체를 전달합니다.
    • 상호작용 이벤트의 invokedFunction 값은 externalDataSource 필드의 함수와 일치합니다.
    • 함수가 일치하면 외부 데이터에서 추천 항목을 반환합니다. 있습니다. 사용자 입력을 바탕으로 항목을 제안하려면 autocomplete_widget_query 키. 이 값은 사용자가 입력하는 내용을 나타냅니다. 를 클릭합니다.

    다음 코드는 외부 데이터 리소스에서 항목을 자동 완성합니다. 이전 예에서 채팅 앱은 getContacts 함수가 트리거될 때:

    Apps Script

    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
            },
          ]
        }
      }
    }
  };
}

    사용자가 텍스트를 입력할 수 있는 필드 추가

    TextInput 위젯 사용자가 텍스트를 입력할 수 있는 입력란을 제공합니다. 이 위젯은 사용자가 균일한 데이터 및 변경 시 입력하도록 도와주는 추천을 지원합니다. 발생하는데 Actions 텍스트 입력란에 변경사항이 발생할 때(예: 사용자가 텍스트를 삭제할 수 있습니다.

    사용자로부터 추상적이거나 알 수 없는 데이터를 수집해야 하는 경우 TextInput 위젯 사용자로부터 정의된 데이터를 수집하려면 SelectionInput 위젯을 사용하세요.

    사용자가 입력한 텍스트를 처리하려면 사용자가 입력한 정보를 처리합니다.

    다음은 TextInput 위젯으로 구성된 카드입니다.

    사용자가 날짜와 시간을 선택하도록 허용

    이 DateTimePicker 위젯 사용자가 날짜, 시간 또는 날짜와 할 수 있습니다. 또는 사용자가 선택 도구를 사용하여 날짜와 시간을 선택할 수도 있습니다. 사용자가 날짜나 시간이 잘못된 경우 선택 도구에 사용자에게 입력을 요청하는 오류가 표시됩니다. 도움이 될 수 있습니다

    사용자가 입력하는 날짜 및 시간 값을 처리하려면 다음을 참고하세요. 사용자가 입력한 정보를 처리합니다.

    다음은 세 가지 유형의 거래로 구성된 카드를 보여줍니다. DateTimePicker 위젯:

    카드에 입력된 데이터의 유효성 검사

    이 페이지에서는 카드의 action에 입력된 데이터를 확인하는 방법을 설명합니다. 살펴보겠습니다 예를 들어 텍스트 입력란에 특정 수의 문자가 포함되어 있는지 확인합니다.

    작업에 필요한 위젯 설정

    카드의 action에 포함되어 있으며, 작업에 필요한 위젯의 이름을 requiredWidgets 목록에 추가합니다.

    이 작업을 호출할 때 여기에 나열된 위젯에 값이 없는 경우 양식 작업 제출이 취소됩니다.

    작업에 "all_widgets_are_required": "true"를 설정하면 모든 위젯이 이 작업에서는 카드에 나와 있는 정보가 필요합니다.

    다중 선택에서 all_widgets_are_required 작업 설정

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

    dateTimePicker에서 all_widgets_are_required 작업 설정

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

    드롭다운 메뉴에서 all_widgets_are_required 작업 설정

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

    텍스트 입력 위젯의 유효성 검사 설정

    textInput 위젯의 유효성 검사 필드에서 글자 수 제한 및 입력 유형을 지정할 수 있습니다. 이 텍스트 입력 위젯을 사용할 수 있습니다.

    텍스트 입력 위젯의 글자 수 제한 설정

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

    텍스트 입력 위젯의 입력 유형 설정

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

    문제 해결

    Google Chat 앱 또는 card가 오류를 반환하는 경우 Chat 인터페이스에 '문제가 발생했습니다'라는 메시지가 표시됨 또는 '요청을 처리할 수 없습니다'와 같은 메시지가 표시됩니다. 채팅 UI가 오류 메시지가 표시되지 않지만 채팅 앱 또는 카드에서 예기치 않은 결과가 발생합니다. 예를 들어 카드 메시지가 나타납니다.

    채팅 UI에 오류 메시지가 표시되지 않을 수도 있지만 오류 해결에 도움이 되는 오류 메시지 및 로그 데이터를 사용할 수 있음 채팅 앱의 오류 로깅이 사용 설정된 경우 보는 데 도움이 필요한 경우 오류를 수정하는 방법에 대한 자세한 내용은 Google Chat 오류 문제 해결하기