@clack-platform/mini-app-sdk

앱인클랙 미니앱 SDK — 클랙 앱 WebView 안에서 동작하는 미니앱이 전용 토큰·유저 프로필·이벤트 트래킹·공유 같은 클랙 기능을 사용하기 위한 공식 SDK입니다.

• 개발자 문서: https://developers.clack.kr/docs
• 미니앱은 클랙이 정적 호스팅하는 SPA입니다. 유저 액세스 토큰은 절대 전달되지 않으며, scope 제한 전용 토큰(mat_)만 제공됩니다.

설치

npm i @clack-platform/mini-app-sdk
# 화이트리스트 기간에는 next 태그로 배포됩니다
npm i @clack-platform/mini-app-sdk@next

빠른 시작

import { ClackMiniApp } from '@clack-platform/mini-app-sdk';

const clack = ClackMiniApp.init({ appId: 'my-app' });

// 전용 토큰 (자체 서버 인증에 사용 가능 — scope 범위 내)
const token = clack.getToken();

// 최소 프로필 (scope: mini-app:user:read)
const user = await clack.getUser(); // { userKey, nickname, avatar } | null

// 이벤트 트래킹 (scope: mini-app:events) — 내부 배치·이탈 시 자동 flush
clack.track('stage_clear', { stage: 3 });

// 클랙 공유 시트 (scope: mini-app:share)
await clack.share({ message: '내 결과 보기', url: 'https://my-app.clack.page/r/abc' });

// 외부 링크는 시스템 브라우저로 (WebView 안에서는 오리진 밖 이동이 차단됨)
clack.openExternal('https://example.com');

환경 정보·기능 감지

const { os, appVersion, theme, safeArea } = clack.getEnv();
document.body.style.paddingTop = `${safeArea.top}px`;

// 구버전 클랙 앱에는 없는 기능은 먼저 감지하고 폴백을 준비한다
if (clack.isApiAvailable('share')) {
  await clack.share({ url: 'https://my-app.clack.page' });
}

// 클랙 앱 테마·안전 영역 변경 구독 (unsubscribe 반환)
const off = clack.onThemeChange((next) => document.documentElement.dataset.theme = next);
clack.onSafeAreaChange(({ bottom }) => { /* 하단 여백 갱신 */ });

React

import { ClackProvider, useClack } from '@clack-platform/mini-app-sdk/react';

function App() {
  return (
    <ClackProvider config={{ appId: 'my-app' }}>
      <Page />
    </ClackProvider>
  );
}

function Page() {
  const clack = useClack();
  // ...
}

로컬 개발 (mock 모드)

WebView 밖 일반 브라우저에서는 브리지가 동작하지 않습니다. mock 모드로 개발하세요.

const clack = ClackMiniApp.init({
  appId: 'my-app',
  mock: true,
  mockUser: { userKey: 'local-dev', nickname: '테스터', avatar: null },
});

• 토큰은 null, 브리지는 no-op, track()은 전송 없이 디버그 로깅만 합니다.
• getUser()는 mockUser를 반환합니다.

API

| 메서드 | 설명 | |---|---| | 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?) | 이벤트 전송 — scope mini-app:events, 배치+keepalive | | .share(payload): Promise<void> | 클랙 공유 시트 — scope mini-app:share. 취소는 resolve, scope 거부·타임아웃은 reject | | .openExternal(url) | http(s) URL을 시스템 브라우저로. 브라우저에서는 새 탭 폴백 | | .close() | 미니앱 종료, 클랙 앱 복귀 | | .isInApp(): boolean | 클랙 앱 WebView 내부 여부 (mock 모드는 항상 false) | | .getEnv(): MiniAppEnv | 실행 환경 스냅샷 — os / osVersion / appVersion / sdkVersion / language / theme / safeArea(dp). 호출 시점 복사본 | | .isApiAvailable(method): boolean | 브릿지 메서드 지원 여부 (구버전 앱 대비 기능 감지). 브라우저·mock은 항상 false | | .onTokenChange(cb): unsubscribe | 토큰 변경 구독 | | .onResume(cb): unsubscribe | WebView 포커스 복귀 구독 | | .onPause(cb): unsubscribe | WebView 이탈(백그라운드 전환) 구독 | | .onThemeChange(cb): unsubscribe | 테마 변경 구독. 브라우저·mock은 prefers-color-scheme 폴백 | | .onSafeAreaChange(cb): unsubscribe | 안전 영역 변경 구독 (화면 회전 등). 브라우저·mock은 no-op |

init 설정

| 키 | 기본값 | 설명 | |---|---|---| | appId | (필수) | 포털 등록 app_id — 소문자 영숫자·하이픈 2~40자 | | debug | false | [ClackSDK] 콘솔 로깅 | | mock | false | 로컬 브라우저 개발 모드 | | mockUser | null | mock 모드에서 getUser() 반환값 | | apiBaseUrl | 자동 | 서빙 호스트로 자동 결정 — {app_id}-dev.clack.page는 dev API, 그 외 prod API |

유저 식별

getUser().userKey는 앱별 스코프드 익명키입니다. 같은 유저라도 앱마다 값이 다르며, 클랙 내부 user_id는 제공되지 않습니다. 자체 서버의 유저 매핑 키로 사용하세요.

scope

| scope | 내용 | 부여 | |---|---|---| | mini-app:events | 이벤트 트래킹 | 기본 | | mini-app:user:read | 닉네임·아바타 최소 프로필 | 기본 | | mini-app:user:profile | 상세 프로필 | 심사 승인 | | mini-app:share | 클랙 공유 시트 | 심사 승인 |

scope 변경은 재심사 대상입니다. 자세한 내용은 개발자 문서를 참고하세요.

License

MIT