본문으로 건너뛰기

2026-07-30

userHash를 필수 옵션으로 전환 — AppKit 생성 시 dApp이 userHash를 반드시 전달하도록 변경했습니다. 생략 시 SDK가 설치 단위 임의 ID로 대신 채우던 동작을 제거하고, 사용자 식별값을 dApp이 결정하도록 타입과 실행 시점 검증을 바꿨습니다.

주요 변경​

  • AppKitOptions.userHash를 필수(userHash: string)로 변경했습니다. 이에 따라 new AppKit(options)의 options 자체도 필수가 되었습니다.
  • userHash가 없거나 공백이면 AppKit 생성자가 INVALID_CONFIG AppError를 던짐
  • SDK 내부의 getOrCreateUserHash() 자동 대체 동작을 제거해, 생략 시 설치 단위 ID가 자동으로 붙지 않게 했습니다.
  • @scope-connect/appkit-react의 ScopeAppKitConfig.userHash도 필수로 변경했습니다.

변경​

  • getOrCreateUserHash()는 공개 함수로 유지했습니다. 자체 식별자가 없는 dApp이 필수 userHash 값을 만들 때 사용하는 권장 함수로 역할을 재정의했습니다.
  • 데모 dApp(connect/payment)은 쿼리와 환경 변수에 지정값이 없으면 getOrCreateUserHash()로 값을 만들어 항상 명시적으로 전달하도록 변경했습니다.

적용 방법​

  • 기존에 userHash를 이미 넘기던 dApp: 변경 없음
  • 생략하던 dApp: new AppKit({ userHash: getOrCreateUserHash()!, ... })처럼 명시적으로 전달 (이전 자동 생성 값과 같은 저장 키 scc.uh.v1를 사용하므로 콘솔 집계 이력은 끊기지 않음)
  • SSR 앱: getOrCreateUserHash()는 SSR/제한 환경에서 undefined일 수 있으므로, 클라이언트에서 값을 결정한 뒤 AppKit을 생성

참고​

  • userHash의 의미는 바뀌지 않았습니다. 개인정보에서 유도하지 않는 임의의 식별값이며, 콘솔은 고유·활성·신규 사용자 지표 집계에만 사용합니다.
  • 콘솔 지표, DB 스키마, 수집 API 동작은 변경 없음