양방향 카드 빌드

대부분의 부가기능은 데이터를 표시하는 것 외에도 사용자가 정보를 입력해야 합니다. 카드 기반 부가기능을 빌드할 때 버튼, 툴바 메뉴 항목, 체크박스와 같은 대화형 위젯을 사용하여 부가기능에 필요한 데이터를 사용자에게 요청하거나 다른 상호작용 컨트롤을 제공할 수 있습니다.

위젯에 작업 추가

대부분의 경우 위젯을 특정 작업에 연결하고 콜백 함수에서 필요한 동작을 구현하여 위젯을 대화형으로 만듭니다. 자세한 내용은 부가기능 작업을 참고하세요.

대부분의 경우 다음 일반 절차에 따라 위젯이 선택되거나 업데이트될 때 특정 작업을 실행하도록 구성할 수 있습니다.

  1. 실행해야 하는 콜백 함수와 필요한 매개변수를 지정하여 Action 객체를 만듭니다.
  2. 적절한 위젯 핸들러 함수를 호출하여 위젯을 Action에 연결합니다.
  3. 필요한 동작을 실행하도록 콜백 함수를 구현합니다.

예

다음 예에서는 클릭 후 사용자 알림을 표시하는 버튼을 설정합니다. 클릭하면 알림 텍스트를 지정하는 인수를 사용하여 notifyUser() 콜백 함수가 트리거됩니다. 빌드된 ActionResponse을 반환하면 알림이 표시됩니다.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

효과적인 상호작용 설계

대화형 카드를 디자인할 때는 다음 사항에 유의하세요.

  • 대화형 위젯에는 일반적으로 동작을 정의하는 핸들러 메서드가 하나 이상 필요합니다.

  • URL이 있고 탭에서 열기만 하려면 setOpenLink() 위젯 핸들러 함수를 사용합니다. 이렇게 하면 Action 객체와 콜백 함수를 정의할 필요가 없습니다. 먼저 URL을 빌드해야 하거나 URL을 열기 전에 다른 추가 단계를 거쳐야 하는 경우 Action를 정의하고 대신 setOnClickOpenLinkAction()를 사용하세요.

  • setOpenLink() 또는 setOnClickOpenLinkAction() 위젯 핸들러 함수를 사용할 때는 열 URL을 정의하는 OpenLink 객체를 제공해야 합니다. 이 객체를 사용하여 OpenAs 및 OnClose 열거형을 사용하여 열기 및 닫기 동작을 지정할 수도 있습니다.

  • 둘 이상의 위젯이 동일한 Action 객체를 사용할 수 있습니다. 하지만 콜백 함수에 다른 매개변수를 제공하려면 다른 Action 객체를 정의해야 합니다.

  • 콜백 함수는 간단하게 유지하세요. 부가기능의 응답성을 유지하기 위해 카드 서비스는 콜백 함수의 실행 시간을 최대 30초로 제한합니다. 실행 시간이 이보다 길어지면 Action에 대한 응답으로 애드온 UI의 카드 표시가 제대로 업데이트되지 않을 수 있습니다 .

  • 사용자가 부가기능 UI와 상호작용한 결과로 서드 파티 백엔드의 데이터 상태가 변경되는 경우 기존 클라이언트 측 캐시가 삭제되도록 부가기능이 true에 '상태 변경됨' 비트를 설정하는 것이 좋습니다. 자세한 내용은 ActionResponseBuilder.setStateChanged() 메서드 설명을 참고하세요.