postMessage 프로토콜

<mooni-frame> 대신 Mooni iframe을 직접 임베드하는 경우에만 이 페이지가 필요합니다. Web Component는 아래 모든 동작을 자동으로 처리합니다.

모든 메시지는 type 디스크리미네이터를 가진 JSON 객체입니다. 양방향 모두 valibot으로 검증되며 알 수 없는 메시지는 무시됩니다.

Parent → iframe

`mooni:config:update`

iframe 로드 시점과 설정 가능 속성이 변경될 때마다 전송됩니다.

{
  type: "mooni:config:update",
  apiKey: string,
  theme?: "light" | "dark",
  language?: "ko" | "en",
  tenantId?: string,
  userId?: string,
  brandId?: string,
}

sessionId는 의도적으로 이 스키마에 포함되지 않습니다 — iframe 내부에서 localStorage 기반으로 생성되므로 호스트 통합이 최소화됩니다.

`mooni:visibility:changed`

호스트가 표시 상태를 토글했음을 iframe에 알립니다. iframe은 입력창 포커스나 활동 일시정지에 사용합니다.

{
  type: "mooni:visibility:changed",
  visible: boolean,
}

`mooni:viewport:resize`

호스트 뷰포트 변경을 iframe에 알립니다 (반응형 레이아웃 결정용).

{
  type: "mooni:viewport:resize",
  width: number,
  height: number,
}

iframe → Parent

`mooni:ready`

iframe 부팅 후 첫 메시지. 호스트는 iframe이 동작하기 전에 mooni:config:update로 응답해야 합니다.

{ type: "mooni:ready" }

`mooni:close`

사용자가 iframe 내부 닫기 버튼을 눌렀습니다. 호스트는 위젯을 숨겨야 합니다.

{ type: "mooni:close" }

`mooni:resize`

iframe 콘텐츠 높이가 변경되었습니다. 호스트는 iframe height를 맞춰 갱신해야 합니다.

{
  type: "mooni:resize",
  height: number,
}

핸드셰이크 시퀀스

참조 구현

부모 측 정식 구현 (iframe 생성, messenger 셋업, 정리 로직)은 ax-cs-chat/packages/mooni-kit의 mooni-frame.ts를 참고하세요.

postMessage 프로토콜

목차