SDK 레퍼런스 (@clack-platform/mini-app-sdk)
클랙 앱 WebView 브리지·전용 토큰·이벤트 트래킹을 다루는 공식 SDK입니다. 미니앱에 필수 탑재이며, 정적 검사가 탑재 여부를 확인합니다.
npm i @clack-platform/mini-app-sdk
import { ClackMiniApp } from '@clack-platform/mini-app-sdk';
const clack = ClackMiniApp.init({ appId: 'my-app' });
const user = await clack.getUser(); // { userKey, nickname, avatar } | null
clack.track('stage_clear', { stage: 3 });
await clack.share({ message: '내 결과 보기', url: 'https://my-app.clack.page/r/abc' });메서드
| 시그니처 | 설명 |
|---|---|
| ClackMiniApp.init(config) | 초기화(싱글톤). appId 형식 검증, 주입 토큰 추출. 두 번째 호출은 기존 인스턴스 반환. |
| ClackMiniApp.getInstance() | 초기화된 인스턴스 반환 (미초기화 시 throw). |
| getToken(): string | null | 현재 전용 토큰(mat_). 유저 액세스 토큰은 절대 제공되지 않습니다. |
| refreshToken(): Promise<string | null> | 토큰 재발급 요청 (TTL 1시간). |
| getUser(): Promise<MiniAppUser | null> | scope mini-app:user:read 최소 프로필. 세션 동안 캐시. |
| track(type, payload?): void | scope mini-app:events 이벤트 전송 — 내부 배치 + 이탈 시 keepalive 자동 flush. |
| share(payload): Promise<void> | scope mini-app:share 클랙 공유 시트. { title?, message?, url? } — message 또는 url 필수. 유저 취소는 resolve, scope 거부·타임아웃은 reject. |
| openExternal(url): void | 외부 http(s) URL을 시스템 브라우저로. WebView 안에서는 오리진 밖 이동이 차단되므로 외부 링크는 반드시 이 메서드 사용. |
| close(): void | 미니앱 종료, 클랙 앱 복귀. |
| isInApp(): boolean | 클랙 앱 WebView 내부 여부 (mock 모드는 항상 false). |
| onTokenChange(cb): unsubscribe | 토큰 변경 구독 — 갱신으로 값이 바뀔 때 호출. |
| onResume(cb): unsubscribe | WebView 포커스 복귀(백그라운드 → 포그라운드) 구독. |
| getEnv(): MiniAppEnv | 실행 환경 스냅샷 — { os, osVersion, appVersion, sdkVersion, language, theme, safeArea }. |
| isApiAvailable(method): boolean | 브리지 메서드 지원 여부 사전 감지(예: 'share'). 구버전 앱은 baseline(close/REQUEST_TOKEN)만 true. |
| onThemeChange(cb): unsubscribe | 클랙 앱 테마(light/dark) 변경 구독. |
| onSafeAreaChange(cb): unsubscribe | safe area 인셋 변경 구독(회전 등). |
| onPause(cb): unsubscribe | 백그라운드 진입·포커스 이탈 구독 (onResume의 짝). |
init 설정
| 키 | 기본값 | 설명 |
|---|---|---|
| appId | (필수) | 포털 등록 app_id — 소문자 영숫자·하이픈 2~40자. |
| debug | false | [ClackSDK] 콘솔 로깅 활성화. |
| mock | false | 로컬 브라우저 개발 모드 — 토큰 null·브리지 no-op·track 미전송. |
| mockUser | null | mock 모드에서 getUser()가 반환할 유저. |
| apiBaseUrl | 자동 | 서빙 호스트로 자동 결정 — {app_id}-dev.clack.page는 dev API, 그 외 prod API. |
React 어댑터
import { ClackProvider, useClack } from '@clack-platform/mini-app-sdk/react';
<ClackProvider config={{ appId: 'my-app' }}>...</ClackProvider>
// 하위 컴포넌트에서
const clack = useClack();유저 식별 (userKey)
getUser().userKey는 앱별 스코프드 익명키입니다. 같은 유저라도 앱마다 값이 다르며 클랙 내부 user_id는 제공되지 않습니다. 자체 서버의 유저 매핑 키로 사용하세요. 자체 서버 인증은 getToken()의 mat_ 토큰을 서버로 보내 클랙 API(GET /v4/mini-apps/me)로 검증하는 패턴을 권장합니다.
환경 정보 (MiniAppEnv)
interface MiniAppEnv {
os: 'ios' | 'android' | 'unknown';
osVersion: string | null;
appVersion: string | null;
sdkVersion: string;
language: string;
theme: 'light' | 'dark';
safeArea: { top: number; bottom: number; left: number; right: number };
}비 WebView/mock 환경 폴백: os: 'unknown', osVersion/appVersion: null, theme는 prefers-color-scheme 감지값, safeArea는 전부 0. isApiAvailable도 비 WebView/mock에서는 항상 false를 반환합니다.
theme·safeArea는 변경 푸시가 있어 항상 최신값이지만, language는 페이지 로드 시점 값입니다 — 클랙 앱 언어가 실행 중 바뀌면 미니앱 리로드 전까지 이전 값이 유지됩니다.
로컬 브라우저 개발은 mock 모드(
init({ appId, mock: true, mockUser }))를 사용하세요 — WebView 밖에서는 브리지가 동작하지 않습니다.