Google Chat 사용자로부터 정보 수집 및 처리

이 가이드에서는 Google Chat 앱이 카드 기반 인터페이스에서 양식 입력을 빌드하여 사용자로부터 정보를 수집하고 처리하는 방법을 설명합니다.

Google Chat에서 부가기능은 사용자에게 Google Chat 앱으로 표시됩니다. 자세한 내용은 Google Chat 확장 개요를 참고하세요.

Chat 앱은 다음과 같은 방법을 포함하여 Chat 안팎에서 작업을 실행하기 위해 사용자에게 정보를 요청합니다.

• 설정을 구성합니다. 예를 들어 사용자가 알림 설정을 맞춤설정하거나 하나 이상의 스페이스에 Chat 앱을 구성하고 추가할 수 있도록 허용할 수 있습니다.
• 다른 Google Workspace 애플리케이션에서 정보를 만들거나 업데이트합니다. 예를 들어 사용자가 Google Calendar 일정을 만들 수 있도록 허용합니다.
• 사용자가 다른 앱 또는 웹 서비스의 리소스에 액세스하고 업데이트할 수 있도록 허용합니다. 예를 들어 Chat 앱을 사용하면 사용자가 Chat 스페이스에서 직접 지원 티켓의 상태를 업데이트할 수 있습니다.

기본 요건

카드를 사용하여 양식 만들기

정보를 수집하기 위해 Chat 앱은 양식과 입력란을 설계하고 카드에 빌드합니다. 사용자에게 카드를 표시하기 위해 Chat 앱은 다음 Chat 인터페이스를 사용할 수 있습니다.

• 카드가 하나 이상 포함된 채팅 메시지
• 대화상자: 메시지 및 홈페이지에서 새 창으로 열리는 카드입니다.

Chat 앱은 다음 위젯을 사용하여 카드를 빌드할 수 있습니다.

• 사용자에게 정보를 요청하는 양식 입력 위젯 원하는 경우 양식 입력 위젯에 유효성 검사를 추가하여 사용자가 정보를 올바르게 입력하고 형식을 지정하도록 할 수 있습니다. 채팅 앱은 다음과 같은 양식 입력 위젯을 사용할 수 있습니다.

  • 자유 형식 또는 추천 텍스트용 텍스트 입력(textInput)
  • 선택 입력(selectionInput)은 체크박스, 라디오 버튼, 드롭다운 메뉴와 같이 선택 가능한 UI 요소입니다. 선택 입력 위젯은 정적 또는 동적 데이터 소스의 항목을 채울 수도 있습니다. 예를 들어 사용자는 자신이 참여 중인 Chat 스페이스 목록에서 선택할 수 있습니다.
  • 날짜 및 시간 항목의 날짜 시간 선택기(dateTimePicker)

• 사용자가 카드에 입력한 값을 제출할 수 있는 버튼 위젯입니다. 사용자가 버튼을 클릭하면 채팅 앱에서 수신한 정보를 처리할 수 있습니다.

다음 예에서 카드는 텍스트 입력란, 날짜 시간 선택 도구, 선택 입력란을 사용하여 연락처 정보를 수집합니다.

정보를 수집하는 데 사용할 수 있는 대화형 위젯의 더 많은 예는 Google Chat API 문서의 대화형 카드 또는 대화상자 디자인을 참고하세요.

양방향 위젯에서 데이터 수신

사용자가 버튼을 클릭할 때마다 상호작용에 관한 정보와 함께 Chat 앱 작업이 트리거됩니다. 이벤트 페이로드의 commonEventObject에서 formInputs 객체에는 사용자가 입력한 값이 포함됩니다.

commonEventObject.formInputs.WIDGET_NAME 객체에서 값을 검색할 수 있습니다. 여기서 WIDGET_NAME는 위젯에 지정한 name 필드입니다. 값은 위젯의 특정 데이터 유형으로 반환됩니다.

다음은 사용자가 각 위젯의 값을 입력한 이벤트 객체의 일부를 보여줍니다.

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

데이터를 수신하기 위해 Chat 앱은 이벤트 객체를 처리하여 사용자가 위젯에 입력한 값을 가져옵니다. 다음 표는 지정된 양식 입력 위젯의 값을 가져오는 방법을 보여줍니다. 각 위젯의 경우 위젯이 허용하는 데이터 유형, 값이 이벤트 객체에 저장되는 위치, 예시 값이 표에 표시됩니다.

다른 카드로 데이터 전송하기

사용자가 카드 정보를 제출한 후 다음 작업을 수행하려면 추가 카드를 반품해야 할 수 있습니다.

• 구분된 섹션을 만들어 사용자가 긴 양식을 작성할 수 있도록 지원합니다.
• 사용자가 제출하기 전에 답변을 검토할 수 있도록 초기 카드의 정보를 미리 보고 확인할 수 있도록 합니다.
• 양식의 나머지 부분을 동적으로 채웁니다. 예를 들어 사용자에게 약속을 만들라는 메시지를 표시하기 위해 Chat 앱은 약속 이유를 요청하는 첫 번째 카드를 표시한 다음 약속 유형에 따라 사용 가능한 시간을 제공하는 다른 카드를 채울 수 있습니다.

초기 카드에서 데이터 입력을 전송하려면 다음 예와 같이 위젯의 name 및 사용자가 입력한 값이 포함된 actionParameters를 사용하여 button 위젯을 빌드하면 됩니다.

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

여기서 WIDGET_NAME는 위젯의 name이고 USER_INPUT_VALUE는 사용자가 입력한 내용입니다. 예를 들어 사용자 이름을 수집하는 텍스트 입력의 경우 위젯 이름은 contactName이고 예시 값은 Kai O입니다.

사용자가 버튼을 클릭하면 Chat 앱은 데이터를 수신할 수 있는 이벤트 객체를 수신합니다.

양식 제출에 응답

카드 메시지 또는 대화상자에서 데이터를 수신한 후 Chat 앱은 수신 확인 또는 오류 반환으로 응답합니다.

다음 예에서는 Chat 앱이 카드 메시지에서 제출된 양식을 수신했음을 확인하는 텍스트 메시지를 전송합니다.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

대화상자를 처리하고 닫으려면 확인 메시지를 보내거나, 원본 메시지 또는 카드를 업데이트하거나, 대화상자를 닫을지 여부를 지정하는 RenderActions 객체를 반환합니다. 단계는 대화상자 닫기를 참고하세요.

문제 해결

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

Chat UI에 오류 메시지가 표시되지 않을 수 있지만 Chat 앱의 오류 로깅이 사용 설정된 경우 오류를 수정하는 데 도움이 되는 설명 오류 메시지와 로그 데이터를 사용할 수 있습니다. 오류를 보고, 디버그하고, 수정하는 데 도움이 필요한 경우 Google Chat 오류 문제 해결하기를 참고하세요.