양방향 카드 빌드

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

위젯에 작업 추가

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

대부분의 경우 다음과 같은 일반적인 절차에 따라 선택 또는 업데이트 시 특정 작업을 실행하도록 위젯을 구성할 수 있습니다.

  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 enum을 사용하여 열기 및 닫기 동작을 지정할 수도 있습니다.

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

  • 콜백 함수를 간단하게 유지합니다. 부가기능의 응답성을 유지하기 위해 카드 서비스는 콜백 함수를 최대 30초의 실행 시간으로 제한합니다. 실행 시간이 이보다 오래 걸리면 부가기능 UI가 Action에 응답하여 카드 디스플레이를 제대로 업데이트하지 못할 수 있습니다 .

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