게임플레이 파트너 가이드

테마 전환

게임플레이 JS SDK 시작하기 1.0.0-beta.3 ​

게임플레이 JS SDK 는 베타 버전입니다. 베타 테스트 기간 동안 스펙이 변경될 수 있습니다.

베타 기간 중 변경 사항은 릴리즈 노트의 SDK 탭에서 확인하세요.
연동 중 문제가 생기거나 궁금한 점이 있으면 데브톡으로 문의해 주세요.

SDK 가 무엇을 해결하는지는 게임플레이 JS SDK를 참고하세요.

사전 준비 ​

게임플레이 JS SDK 를 설치해도 아래 등록 절차는 그대로 파트너사가 직접 진행해야 합니다.
SDK 는 연동 코드를 통합할 뿐, 조직 간 등록 프로세스까지 대신하지는 않습니다.

  • 카카오디벨로퍼스에 앱을 생성하고 JavaScript 키를 발급받습니다.
  • 게임플레이 파트너센터오픈 예정에 게임 정보와 게임 URL을 등록합니다.
  • 게임웹뷰 실행에 사용할 샌드박스·운영·테스트 도메인(화이트리스트)은 카카오 담당자에게 등록을 요청합니다.
  • 카카오 광고(애드핏)에 등록하고 광고단위를 발급받습니다.

위 절차를 먼저 마쳐야 아래 설치·초기화 단계에서 발급받은 키와 도메인을 바로 사용할 수 있습니다.

설치 필수 ​

<head> 에 SDK 스크립트를 추가합니다.
CDN 에서 제공하는 <script> 한 줄이면 Gameplay 객체를 바로 사용할 수 있고, 별도 번들러 설정이나 패키지 설치는 필요하지 않습니다.

html
<script
  src="https://t1.kakaocdn.net/gameplay/gameplay-sdk/{버전}/gameplay-sdk.min.js"
  integrity="{해당 버전의 integrity 값}"
  crossorigin="anonymous"></script>

{버전} 과 integrity 는 다운로드에서 확인하세요.
integrity 는 그 버전의 값과 일치해야 합니다.
버전만 올리고 integrity 를 그대로 두면 브라우저가 무결성 검증에 실패해 SDK 가 로드되지 않습니다.

TypeScript ​

같은 경로의 gameplay-sdk.d.ts 를 내려받아 프로젝트에 두고 tsconfig.json 의 include 에 추가하면, import 없이 Gameplay 객체에 타입이 적용됩니다.

json
{
  "include": ["src/**/*", "./gameplay-sdk.d.ts"]
}

이 파일 하나에 SDK 가 노출하는 모든 타입과 Gameplay 전역 선언이 함께 들어 있습니다.
별도 @types/... 패키지는 없습니다.
자세한 사용법은 다운로드: TypeScript를 참고하세요.

초기화 ​

ts
await Gameplay.init({
  gameName: '게임 이름',
  gameCode: 'sample-game',
  appId: 1234567,
  clientKey: 'YOUR_JAVASCRIPT_KEY',
});
옵션타입설명
gameNamestring필수게임 이름.
닫기 버튼을 눌렀을 때 SDK 가 띄우는 이탈 확인 팝업의 제목입니다
gameCodestring필수파트너사가 정해 게임플레이 파트너센터오픈 예정에 등록한 게임 코드.
단축 URL 생성의 gameCode · 광고 CPID 와 같은 값입니다
appIdnumber필수카카오디벨로퍼스 앱 ID
clientKeystring카카오디벨로퍼스가 발급하는 JavaScript 키.
카카오 로그인·공유를 쓰는 게임만 지정합니다

tiara · ad · webview · ui 를 포함한 전체 옵션은 전체 메서드에 있습니다.

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 와 카카오 사용자 식별값이 그대로 쓰입니다.

이미 Tiara 를 직접 연동했다면

tiara: false 로 꺼 주세요.
켠 채로 두면 같은 로그가 두 번 쌓입니다.

무엇이 언제 나가는지는 전체 메서드를 참고하세요.

전체 예시 ​

init 으로 웹뷰 상태를 선언하고, UI·광고·공유를 거쳐 종료까지 이어지는 흐름입니다.

ts
async function bootstrapGame(): Promise<void> {
  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<void> {
  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<void> {
  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, 분석 지표, 버그 리포트 용도로 씁니다.

참고 문서 ​