양방향 카드 빌드

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

위젯에 작업 추가

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

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

  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() 위젯 핸들러 함수를 사용할 때는 OpenLink 객체를 제공하여 열 URL을 정의해야 합니다. 이 객체를 사용하면 OpenAsOnClose enum을 사용하여 열기 및 닫기 동작을 지정할 수 있습니다.

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

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

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