Skip to content

커스텀 컴포넌트 카탈로그

표준 A2UI 컴포넌트와 함께 여러분만의 컴포넌트를 포함하는 커스텀 카탈로그를 정의하여 A2UI를 확장하세요.

왜 커스텀 카탈로그를 사용하나요?

A2UI 표준 카탈로그는 일반적인 UI 요소(버튼, 텍스트 필드 등)를 제공하지만, 여러분의 애플리케이션에는 특수한 컴포넌트가 필요할 수 있습니다:

  • 도메인 특화 위젯: 주식 차트, 의료용 차트, CAD 뷰어 등
  • 서드파티 통합: Google 지도, 결제 양식, 채팅 위젯 등
  • 브랜드 특화 컴포넌트: 커스텀 날짜 선택기, 상품 카드, 대시보드 등

커스텀 카탈로그는 다음과 같은 컴포넌트들의 집합입니다: - 표준 A2UI 컴포넌트 (Text, Button, TextField 등) - 여러분의 커스텀 컴포넌트 (GoogleMap, StockTicker 등) - 서드파티 컴포넌트

개별 컴포넌트가 아닌 전체 카탈로그를 클라이언트 애플리케이션에 등록합니다. 이를 통해 에이전트와 클라이언트는 보안과 타입 안전성을 유지하면서 확장된 컴포넌트 셋을 공유할 수 있습니다.

커스텀 카탈로그 동작 방식

  1. 클라이언트가 카탈로그 정의: 표준 컴포넌트와 커스텀 컴포넌트를 모두 나열하는 카탈로그 정의를 생성합니다.
  2. 클라이언트가 카탈로그 등록: 카탈로그(및 컴포넌트 구현체)를 클라이언트 앱에 등록합니다.
  3. 클라이언트가 지원 선언: 클라이언트가 에이전트에게 어떤 카탈로그를 지원하는지 알립니다.
  4. 에이전트가 카탈로그 선택: 에이전트가 특정 UI 서피스에 사용할 카탈로그를 선택합니다.
  5. 에이전트가 UI 생성: 에이전트가 해당 카탈로그의 이름을 사용하여 surfaceUpdate 메시지를 생성합니다.

커스텀 카탈로그 정의하기

TODO: 각 플랫폼별 커스텀 카탈로그 정의에 대한 상세 가이드 추가 예정

웹 (Lit / Angular): - 표준 및 커스텀 컴포넌트를 모두 포함하는 카탈로그 정의 방법 - A2UI 클라이언트에 카탈로그 등록 방법 - 커스텀 컴포넌트 클래스 구현 방법

Flutter: - GenUI를 사용하여 커스텀 카탈로그 정의 방법 - 커스텀 컴포넌트 렌더러 등록 방법

실행 가능한 예시: - Lit 샘플 - Angular 샘플 - Flutter GenUI 문서

에이전트 측: 커스텀 카탈로그 컴포넌트 사용하기

클라이언트에 카탈로그가 등록되면 에이전트는 surfaceUpdate 메시지에서 해당 컴포넌트들을 사용할 수 있습니다.

에이전트는 beginRendering 메시지의 catalogId를 통해 사용할 카탈로그를 지정합니다.

TODO: 다음 예제 추가 예정: - 에이전트의 카탈로그 선택 방법 - 에이전트의 카탈로그 내 커스텀 컴포넌트 참조 방법 - 카탈로그 버전 관리 방식

데이터 바인딩 및 액션

커스텀 컴포넌트는 표준 컴포넌트와 동일한 데이터 바인딩 및 액션 메커니즘을 지원합니다:

  • 데이터 바인딩: 커스텀 컴포넌트는 JSON Pointer 구문을 사용하여 속성을 데이터 모델 경로에 바인딩할 수 있습니다.
  • 액션: 커스텀 컴포넌트는 에이전트가 수신하고 처리할 수 있는 액션을 발생시킬 수 있습니다.

보안 고려 사항

커스텀 카탈로그와 컴포넌트를 생성할 때 주의할 점:

  1. 컴포넌트 허용 목록(Allowlist): 카탈로그에는 신뢰할 수 있는 컴포넌트만 등록하세요.
  2. 속성 검증: 에이전트 메시지로부터 전달된 컴포넌트 속성을 항상 검증하세요.
  3. 사용자 입력 정제(Sanitize): 컴포넌트가 사용자 입력을 받는 경우 처리 전 정제 과정을 거치세요.
  4. API 접근 제한: 민감한 API나 자격 증명을 커스텀 컴포넌트에 노출하지 마세요.

TODO: 상세 보안 베스트 프랙티스 및 코드 예제 추가 예정

다음 단계