AppKit 설정

공개 Client ID로 AppKit을 생성하고 브라우저 지갑 연결을 시작합니다. 기본 데스크톱 주입형 연결은 지갑과 직접 통신합니다. 프로젝트 설정 조회와 백엔드 기반 모바일 연결 등은 Connect 백엔드를 사용하며, Connect 백엔드와 릴레이 엔드포인트는 SDK 빌드 시점에 고정됩니다.

준비 사항

• Node.js를 사용하는 프론트엔드 프로젝트
• 공식 배포 채널에서 안내받은 @scope-connect/appkit 버전
• SCOPE Console 프로젝트에서 발급받은 Client ID
• 텔레메트리를 사용할 때는 수집 목적과 사용자 동의, 보존 정책

Client ID는 브라우저에 포함할 수 있는 공개 식별자입니다. Client Secret은 이 가이드의 어떤 프론트엔드 설정에도 사용하지 않습니다.

1. 패키지 설치

<VERSION>을 배포 안내에서 제공한 버전으로 바꿔 설치합니다.

npm install "@scope-connect/appkit@<VERSION>"

2. 기본 연결 설정

필수 옵션은 clientId 하나입니다. 프로젝트 콘솔에서 발급받은 공개 앱 키이며, 없거나 공백이면 생성자가 INVALID_CONFIG를 던집니다. 브라우저 확장 지갑만 연결한다면 그 외 옵션은 넘기지 않아도 됩니다. init()은 동기 메서드이며 네트워크 요청 없이 초기화 상태를 설정합니다.

src/lib/appkit.ts

import { AppKit } from "@scope-connect/appkit";

export const appKit = new AppKit({
  clientId: import.meta.env.VITE_SCOPE_CLIENT_ID,
});

appKit.init();

이후 사용자 클릭 이벤트에서 appKit.connect() 또는 appKit.selectWallet()을 호출할 수 있습니다. 초기화가 끝나면 appKit.initialized는 true입니다.

지갑 연결 전에 AppKit을 초기화하세요

init() 전에 연결 메서드를 호출하면 INVALID_CONFIG가 발생합니다. 앱 부트스트랩에서 한 번 초기화하고, 버튼 이벤트에서는 이미 초기화된 인스턴스를 사용합니다.

3. 백엔드·릴레이 사용 범위와 텔레메트리 설정

프로젝트 설정 조회, 잔액 조회, 릴레이 토큰 발급, 모바일 유니버설 링크·Phantom 세션은 생성자에 전달한 clientId를 사용합니다. React 바인딩은 주입형 EVM 연결 기록도 Connect 백엔드에 남깁니다. Connect 백엔드와 릴레이의 URL은 SDK에 포함되어 있으므로 런타임 옵션을 추가하지 않습니다. 텔레메트리를 사용할 때만 telemetry를 설정하고, 사용자 단위 집계가 필요하면 userHash를 함께 전달합니다.

항목	기능	설정 방법
clientId	모든 기능 — 생성자 필수 옵션이라 없으면 인스턴스를 만들 수 없습니다	콘솔에서 발급한 공개값을 전달
Connect 백엔드	프로젝트 설정·잔액 조회, 릴레이 토큰 발급, 백엔드 기반 모바일 연결, 선택적 연결 기록·텔레메트리	런타임 URL 옵션 없음 — SDK 빌드 시점에 DEFAULT_CONNECT_BASE_URL로 고정
릴레이	pair()를 통한 QR·딥링크 페어링과 세션 메시지 전송	런타임 URL 옵션 없음 — SDK 빌드 시점에 DEFAULT_RELAY_URL로 고정
telemetry	Connect 이벤트 전송 여부와 세부 옵션	보안·개인정보 정책 검토 후 활성화
userHash	텔레메트리 이벤트에 부착할 사용자 식별값(개인정보에서 유도하지 않는 임의의 값)	선택 — 생략·공백이면 사용자 식별값을 전송하지 않습니다(오류 아님). 사용자 단위 조회·집계가 필요하고 자체 식별자가 없으면 getOrCreateUserHash() 사용

텔레메트리와 사용자 단위 집계를 함께 사용할 때만 다음 옵션을 추가합니다.

import { AppKit, getOrCreateUserHash } from "@scope-connect/appkit";

const observedAppKit = new AppKit({
  clientId: import.meta.env.VITE_SCOPE_CLIENT_ID,
  telemetry: true,
  userHash: getOrCreateUserHash(),
});

observedAppKit.init();

텔레메트리를 켜기 전에 수집 정책을 정하세요

텔레메트리는 기본 비활성이며 telemetry: true 또는 옵션 객체로 켤 때만 전송합니다. 켜면 현재 이벤트에 연결 계정 주소와 서명 요청 데이터가 포함될 수 있습니다.

수집 목적, 보존 기간, 동의와 접근 통제를 검토하기 전에는 기본 예시처럼 telemetry를 생략합니다. 운영에서 활성화할 때는 앱의 개인정보·보안 정책에 이 데이터 흐름을 반영합니다.

생성자 필드와 정확한 기본값은 AppKit Types를 확인합니다.

4. 설정 결과 확인

개발 환경에서 다음 값을 확인합니다.

console.log(appKit.initialized); // true
console.log(
  appKit.getSupportedNetworks().map((network) => network.chainId),
);

연결 버튼을 누르기 전 initialized가 true이고, getSupportedNetworks()가 돌려주는 체인 목록이 앱의 네트워크 선택 정책과 일치하면 기본 설정이 끝난 것입니다. 이 목록은 AppKit API의 loadConfig()를 호출하기 전에는 SDK 내장 목록 전체이고, 호출한 뒤에는 프로젝트 콘솔에서 활성화한 네트워크로 좁혀집니다. INVALID_CONFIG의 원인과 대응은 AppKit 오류 처리에서 확인합니다.

Client ID와 Client Secret 구분

Client ID는 브라우저 요청의 X-App-Key 헤더에 사용되는 공개값입니다. 반면 Client Secret은 서버 전용 비밀 저장소에 보관하며, 프론트엔드 코드, VITE_ 환경변수, URL 또는 로그에 넣지 않습니다. 자세한 취급 기준은 아키텍처의 값의 노출 범위를 따릅니다.

다음 단계

• 지갑 연결 — 네트워크별 지갑 목록과 연결 버튼 구성
• AppKit Types — PairOptions 필드와 PairResult 반환 형식