--- url: /api-sdk/sdk/gameplay-js/getting-started.md description: 게임플레이 JS SDK 의 사전 준비와 설치, 초기화 방법 --- # 게임플레이 JS SDK 시작하기 SDK 가 무엇을 해결하는지는 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)를 참고하세요. ## 사전 준비 게임플레이 JS SDK 를 설치해도 아래 등록 절차는 그대로 파트너사가 직접 진행해야 합니다. SDK 는 연동 코드를 통합할 뿐, 조직 간 등록 프로세스까지 대신하지는 않습니다. * 카카오디벨로퍼스에 앱을 생성하고 JavaScript 키를 발급받습니다. * 게임플레이 파트너센터에 게임 정보와 게임 URL을 등록합니다. * 게임웹뷰 실행에 사용할 샌드박스·운영·테스트 도메인(화이트리스트)은 카카오 담당자에게 등록을 요청합니다. * 카카오 광고(애드핏)에 등록하고 광고단위를 발급받습니다. 위 절차를 먼저 마쳐야 아래 설치·초기화 단계에서 발급받은 키와 도메인을 바로 사용할 수 있습니다. ## 설치 `` 에 SDK 스크립트를 추가합니다. CDN 에서 제공하는 ` ``` `{버전}` 과 `integrity` 는 [다운로드](/api-sdk/sdk/gameplay-js/download)에서 확인하세요. **`integrity` 는 그 버전의 값과 일치해야 합니다.** 버전만 올리고 `integrity` 를 그대로 두면 브라우저가 무결성 검증에 실패해 SDK 가 로드되지 않습니다. ## TypeScript 같은 경로의 `gameplay-sdk.d.ts` 를 내려받아 프로젝트에 두고 `tsconfig.json` 의 `include` 에 추가하면, `import` 없이 `Gameplay` 객체에 타입이 적용됩니다. ```json { "include": ["src/**/*", "./gameplay-sdk.d.ts"] } ``` 이 파일 하나에 SDK 가 노출하는 모든 타입과 `Gameplay` 전역 선언이 함께 들어 있습니다. 별도 `@types/...` 패키지는 없습니다. 자세한 사용법은 [다운로드: TypeScript](/api-sdk/sdk/gameplay-js/download#typescript)를 참고하세요. ## 초기화 ```ts await Gameplay.init({ gameName: '게임 이름', gameCode: 'sample-game', appId: 1234567, clientKey: 'YOUR_JAVASCRIPT_KEY', }); ``` | 옵션 | 타입 | 설명 | | --- | --- | --- | | `gameName` | `string` | 필수게임 이름. 닫기 버튼을 눌렀을 때 SDK 가 띄우는 [이탈 확인 팝업](/api-sdk/sdk/gameplay-js/ui#나가기-버튼)의 제목입니다 | | `gameCode` | `string` | 필수파트너사가 정해 게임플레이 파트너센터에 등록한 게임 코드. [단축 URL 생성](/api-sdk/share/short-url)의 `gameCode` · 광고 CPID 와 같은 값입니다 | | `appId` | `number` | 필수카카오디벨로퍼스 [앱 ID](https://developers.kakao.com/docs/ko/app-setting/app#app-id) | | `clientKey` | `string` | 카카오디벨로퍼스가 발급하는 JavaScript 키. 카카오 로그인·공유를 쓰는 게임만 지정합니다 | `tiara` · `ad` · `webview` · `ui` 를 포함한 전체 옵션은 [전체 메서드](/api-sdk/sdk/gameplay-js/reference#init-options)에 있습니다. ::: danger clientKey 를 쓰면 try/catch 로 감쌉니다 `clientKey` 를 지정했거나 `window.Kakao` 가 이미 로드되어 있으면 `init()` 이 카카오 JS SDK 를 로드합니다. 이 로드가 실패하거나 응답이 없으면 `init()` 이 `KAKAO_NOT_AVAILABLE` 로 reject 됩니다. 감싸지 않으면 광고 차단기·CSP 차단·네트워크 지연 상황에서 unhandled rejection 이 됩니다. ::: ## 게임 로그 게임 로그(Tiara)는 **SDK 가 대신 보냅니다.** Tiara Web SDK 를 직접 연동하지 않아도 되고, 게임이 구현할 항목도 없습니다. `init()` 에 넘긴 `gameCode` · `appId` 와 카카오 사용자 식별값이 그대로 쓰입니다. ::: warning 이미 Tiara 를 직접 연동했다면 `tiara: false` 로 꺼 주세요. 켠 채로 두면 같은 로그가 두 번 쌓입니다. ::: 무엇이 언제 나가는지는 [전체 메서드](/api-sdk/sdk/gameplay-js/reference#게임-로그)를 참고하세요. ## 전체 예시 init 으로 웹뷰 상태를 선언하고, UI·광고·공유를 거쳐 종료까지 이어지는 흐름입니다. ```ts async function bootstrapGame(): Promise { try { await Gameplay.init({ gameName: '게임 이름', gameCode: 'sample-game', appId: 1234567, clientKey: 'YOUR_JAVASCRIPT_KEY', webview: { orientation: 'landscape', scrollEnabled: false, }, }); } catch (error) { console.error('게임플레이 SDK 초기화 실패', error); return; } Gameplay.UI.Toast.show('게임을 준비하고 있습니다.', {duration: 1500}); const ad = await Gameplay.createInterstitialAd({ adUnit: 'DAN-...', ctag: {cp: 'game-code', channel: 'ch-id'}, }); ad.onClose(() => startGame()); ad.load(); ad.open(); } async function onGameClear(): Promise { await Gameplay.talkShare({ templateId: 12345, serverCallbackArgs: { APP_USER_ID: 1001, APP_ID: 42, GAME_TYPE: 'my-game', MESSAGE_TYPE: 'GAME_SHARE', HAS_REWARD: false, }, }); } async function onGameExit(): Promise { await Gameplay.close(); } void bootstrapGame(); ``` ## 기능 확인 카카오톡 버전마다 지원하는 브리지 메서드가 다르므로, 버전을 비교해 기능을 분기하지 않습니다. 패치·백포트 빌드가 섞이면 버전 비교가 실제 지원 여부와 어긋날 수 있기 때문입니다. 대신 `isAvailable()` 로 메서드가 실제로 존재하는지 직접 확인합니다. ```ts declare function semverGte(version: string | undefined, target: string): boolean; declare const info: {talkVersion?: string}; // 권장하지 않음 — 버전으로 추정하면 패치·백포트 빌드에서 어긋납니다 if (semverGte(info.talkVersion, '26.7.0')) { await Gameplay.setScrollEnabled(false); } // 권장 — 메서드 존재를 직접 확인합니다 if (Gameplay.isAvailable('setScrollEnabled')) { await Gameplay.setScrollEnabled(false); } ``` `getDeviceInfo()` 가 반환하는 `talkVersion` 은 기능 분기가 아니라 톡 업데이트 안내 UX, 분석 지표, 버그 리포트 용도로 씁니다. ## 참고 문서 * [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/): SDK 개요와 게임웹뷰 SDK 와의 관계 * [다운로드](/api-sdk/sdk/gameplay-js/download): CDN 주소와 버전별 `integrity` 값 * [전체 메서드](/api-sdk/sdk/gameplay-js/reference): 메서드와 에러 코드 전체 명세 * [UI 컴포넌트](/api-sdk/sdk/gameplay-js/ui): managed UI 5개 컴포넌트의 옵션과 표시 정책 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)