브리지 레퍼런스 (프로토콜 v1.1)

SDK를 사용하면 브리지를 직접 다룰 필요가 없습니다. 이 문서는 프로토콜 명세로, 디버깅이나 비 SDK 구현의 참고용입니다.

전송 (미니앱 → 클랙 앱)

window.ReactNativeWebView.postMessage(JSON.stringify({
  method: string,   // 메서드명
  id?: string,      // 요청-응답 상관관계 ID (요청형 메서드) — v1.1
  params?: string,  // JSON.stringify된 메서드별 페이로드
}))

응답 (클랙 앱 → 미니앱)

앱이 window.__clack_bridge_callback(responseMethod, data, requestId?)를 호출합니다. requestId는 요청 id의 에코이며, 없으면(구버전 앱) 가장 오래된 대기 요청에 매칭합니다(FIFO 폴백). data는 항상 문자열이고 필요 시 JSON 문자열입니다.

토큰 주입

최초 로드: 페이지 JS 실행 전에 window.__clack_token에 전용 토큰(mat_)이 주입됩니다.
갱신: REQUEST_TOKEN 응답과 함께 window.__clack_token도 새 값으로 재설정됩니다.

환경 스냅샷 주입 (SDK 0.2.0+)

최초 로드 시 window.__clack_token에 더해 window.__clack_env가 페이지 JS 실행 전에 주입됩니다:

interface ClackEnvPayload {
  os: 'ios' | 'android' | 'unknown';
  osVersion: string | null;
  appVersion: string | null;
  language: string;
  theme: 'light' | 'dark';
  safeArea: { top: number; bottom: number; left: number; right: number };
  bridgeMethods: string[]; // 예: ['close','REQUEST_TOKEN','share','openExternal']
}

bridgeMethods는 SDK isApiAvailable(method) 판단의 근거입니다. 구버전 앱은 window.__clack_env를 주입하지 않으므로, SDK는 미주입 시 보수적으로 폴백합니다(os 'unknown', isApiAvailable 항상 false, theme는 prefers-color-scheme, safeArea는 전부 0).

런타임 푸시 이벤트 (SDK 0.2.0+)

SDK가 window.__clack_emit(type, payloadJson) 전역 함수를 설치하고, 앱은 값이 바뀔 때마다 이를 호출합니다. 방향은 RN→앱, fire-and-forget(응답 없음)입니다.

themeChange — data={"theme":"light"|"dark"}, SDK onThemeChange 구독의 근거
safeAreaChange — data={"safeArea":{top,bottom,left,right}}, SDK onSafeAreaChange 구독의 근거

메서드

메서드	방향	params	응답
close	앱→RN	—	없음 (fire-and-forget)
REQUEST_TOKEN	앱→RN→앱	—	TOKEN_RESPONSE, data=새 토큰 문자열
share	앱→RN→앱	{ title?, message?, url? }	SHARE_RESPONSE, data={"ok":boolean,"cancelled"?:true,"reason"?:...}
openExternal	앱→RN	{ url } (http/https만)	없음 (fire-and-forget)

share는 scope mini-app:share 필요 — 미보유 시 ok:false, reason:"scope_denied"
유저가 공유를 취소한 경우는 ok:true, cancelled:true — 실패가 아닙니다.
미신고 메서드 호출은 무시됩니다(앱 로그만).

하위호환 규칙

메서드 추가 = 마이너 버전, 메서드 제거·시그니처 변경 = 메이저 버전
v1.0 (SDK 0.0.x): id 없음 — 응답은 FIFO 매칭
v1.1 (SDK 0.1.0+): id 상관관계 추가 — 앱은 요청 id를 응답 3번째 인자로 에코