본문으로 건너뛰기

2026-08-11

userHash를 선택 옵션으로 전환 — 사용자 식별값 전송 여부를 전적으로 dApp·지갑이 결정한다. userHash를 넘기면 콘솔이 그 값으로 사용자 활동을 묶어 보여주고, 넘기지 않으면 사용자 식별값을 전송하지 않는다 — SDK는 어떤 대체 id도 만들지 않는다. 연결·서명 동작은 두 경우 모두 완전히 같다.

콘솔에서는 사용자 식별값이 없는 요청을 빈 값으로 보여주지 않고 미보고로 명시하며, 그 행에서는 사용자 단위 조회가 되지 않는다(빈 값으로 조회되는 경로를 없앴다).

주요 변경​

  • AppKitOptions.userHash를 선택(userHash?: string) 옵션으로 변경했습니다. 이전에는 필수였고 없거나 공백이면 생성자가 INVALID_CONFIG를 던졌지만, 이제는 "사용자 식별값 미보고"로 처리합니다.
  • @scope-connect/appkit-react의 ScopeAppKitConfig.userHash도 선택 옵션으로 변경했습니다.
  • WalletKit이 대체 userHash를 생성하지 않는다 — WalletKitConfig.userHash가 null이면 이전에는 프로세스 단위 UUIDv4를 만들어 붙였다. connect()마다 새 UUID가 생겨 콘솔이 매번 새 사용자로 집계하는 잘못된 지표의 원인이었으므로 제거했다. null은 이제 그대로 "미보고"다(방문 비컨을 생략하고 릴레이 이벤트에는 userHash를 기록하지 않음)

변경​

  • 공백 문자열은 생략과 동일하게 처리됩니다. 전송 데이터에서 userHash 키가 빠지고, 백엔드는 공백을 NULL로 정규화해 저장하므로 빈 값이 별도의 사용자로 집계되지 않습니다.
  • userHash가 없는 이벤트는 새 사용자(new wallet) 인덱스에 기록되지 않는다
  • 콘솔 표기 — Transactions·Signatures·Screening의 User 열이 값 없을 때 — 대신 미보고로 표시되고, 클릭·복사 동작이 없다(사용자 상세 조회 불가)
  • 콘솔 집계 — Users 명단에 행이 생기지 않고, Analytics의 유니크/활성/신규 사용자 지표와 사용자 단위 차트에서 제외된다. 요청 자체는 Transactions·Signatures·Screening 목록에 그대로 남는다

적용 방법​

  • userHash를 이미 넘기던 dApp: 변경 없음. 동작·집계가 모두 그대로다
  • 사용자 단위 지표가 필요 없는 dApp: 옵션을 지우면 된다. getOrCreateUserHash() 호출도 함께 지울 수 있다
  • SSR에서 빈 문자열("")을 넘겨 회피하던 코드: 이제 undefined를 그대로 넘기면 된다 — getOrCreateUserHash()의 undefined 반환값도 그대로 전달할 수 있다
  • WalletKit 지갑 앱: 콘솔 사용자 지표를 계속 쓰려면 WalletKitConfig.userHash에 개인정보를 포함하지 않는 임의의 식별값을 명시하고, 지갑 앱의 보호된 저장 영역에 안정적으로 보존해야 한다. 지정하지 않으면 사용자 지표가 집계되지 않는다

참고​

  • userHash는 여전히 개인정보에서 유도하지 않는 임의의 식별값이다. 이메일·전화번호·이름·생년월일이나 그 해시를 넣지 않는다
  • 값 형식 검증은 유지됩니다. 값이 있으면 64자 16진수 문자열 또는 UUID여야 하며, 형식이 틀리면 잘못된 값이 지표에 반영되지 않도록 422로 거절합니다.