공유 설정

공유 설정은 파트너사 디벨로퍼스 앱에 설정된 카카오톡 공유 기능을 사용합니다.
공유 기능은 디벨로퍼스 앱 설정을 완료한 뒤 사용할 수 있으며, 본 문서는 게임플레이 환경에서 카카오 JS SDK로 카카오톡 공유·URL 복사 기능을 연동하는 방법을 정리합니다.

메시지는 카카오가 사전 정의한 공유 템플릿 ID와 사용자 인자를 기준으로 발송됩니다.
공유 성공 후 보상 결과 통지 연동은 공유 웹훅 연동을 참고하세요.

적용 범위

카카오 JS SDK를 이용한 공유 SDK 호출 (디벨로퍼스 가이드 참고)
사용자 정의 템플릿 기반 메시지 발송
카카오톡 공유와 URL 복사 두 타입 연동

사전 셋팅 항목 필수

공유 기능을 연동하기 전에 카카오 제공 값과 파트너사 앱 설정을 먼저 확인합니다.

카카오 제공 값

환경별 메시지 템플릿 ID
템플릿에 전달할 사용자 인자(templateArgs)
공유 피커 groupId
공유 웹훅 연동 기준값

파트너사 설정 항목 필수

파트너사 앱의 JavaScript 키 확인과 게임 실행 도메인 등록: [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]
[앱] > [제품 링크 관리] > [웹 도메인] 에 게임플레이 도메인(https://gameplay.kakao.com) 등록
카카오 JS SDK 로드 및 초기화 준비
공유 SDK 호출 시 카카오가 전달한 templateId·groupId 적용
단축 URL 생성 응답을 BUTTON_URL과 copy_url에 주입하도록 매핑
공유 웹훅용 serverCallbackArgs 구성
필요한 경우 파트너사 앱의 카카오톡 공유 웹훅 설정: [앱] > [웹훅] > [카카오톡 공유 웹훅]

사전 이해 사항

구분	설명
SDK 버전	최소 `2.8.0` 이상
사용 앱 키	디벨로퍼스의 파트너사 앱의 JavaScript 키 (어드민 키 미사용)
도메인 제한	[앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인] 에 등록한 도메인에서만 정상 동작
메시지 템플릿	카카오가 사전 생성한 사용자 정의 템플릿 사용
사용자 인자	템플릿의 `${KEY}` 값을 `templateArgs`에 동일 키로 전달

SDK 설치와 초기화 방법은 카카오 JS SDK를 참고하세요.

공유 흐름

사용자가 게임 안에서 공유 버튼을 누릅니다.
파트너사는 카카오의 단축 URL 생성을 호출해 공유용 단축 URL을 발급받습니다.
응답받은 URL을 templateArgs.BUTTON_URL과 pickerSettings.args.copy_url에 주입합니다.
Kakao.Share.sendCustom()을 호출합니다.
게임 공유·보상 공유·자랑하기 모두 pickerSettings를 포함합니다.
사용자가 카카오톡에서 공유를 완료합니다.
디벨로퍼스에 공유 웹훅을 설정하였을 경우 공유 웹훅 연동을 통해 결과가 통지됩니다.

공유 타입

타입	공유 범위	말풍선 형태	비고
카카오톡 공유	카카오톡 내 메시지	사전 정의된 템플릿	카카오가 제공하는 템플릿 ID 사용
URL 복사	외부 브라우저·블로그 등 카카오톡 외부	OG 태그 스크랩	`pickerSettings.args.copy_url`에 단축 URL 전달

예시 - 공유 타입별 공유 피커

카카오톡 공유 템플릿 ID 필수

카카오톡 공유는 하나의 템플릿 ID로 메시지 타입별 소재를 구분해 사용합니다.
템플릿 ID는 카카오가 사전 생성해 파트너사에 전달하는 값이며, 디벨로퍼스 문서에서는 사용자 정의 템플릿이라는 이름으로 안내됩니다.

환경	템플릿 ID	피커 groupId
CBT	126532	10
PROD	126533	12

메시지 타입:

타입	적용 여부	설명
`GAME_SHARE`	필수	보상 없이 단순 게임을 공유
`REWARD_SHARE`	선택	공유를 통해 보상(아이템·점수 등)을 제공
`RANKING_SHARE`	선택	랭킹·스테이지 클리어 자랑하기

구현 상세 안내

SDK 초기화 필수

파트너사 앱의 JavaScript 키로 SDK를 초기화합니다.

window.Kakao.init('JAVASCRIPT_KEY');

설치 스크립트와 버전 요구사항은 카카오 JS SDK에 정리되어 있습니다.

단축 URL 생성 API 호출 필수

공유 SDK 호출 전에 단축 URL을 먼저 발급받습니다.
응답의 short_url을 이후 templateArgs.BUTTON_URL과 pickerSettings.args.copy_url에 주입합니다.

interface ShortUrlResponse {
  short_url: string;
}

const response: ShortUrlResponse = await callShortUrlApi({gameCode});

API 상세는 단축 URL 생성을 참고하세요.

공유 호출 필수

게임 공유·보상 공유·자랑하기 모두 아래 방식으로 Kakao.Share.sendCustom()을 호출합니다.
pickerSettings는 반드시 포함합니다.

type MessageType = 'GAME_SHARE' | 'RANKING_SHARE' | 'REWARD_SHARE';

interface SendCustomPayload {
  installTalk: boolean;
  templateId: number;
  templateArgs: {
    THU: string;
    TITLE: string;
    DESCRIPTION: string;
    BUTTON_TEXT: string;
    BUTTON_URL: string;
  };
  pickerSettings: {
    args: {copy_url: string};
    groupId: number;
    limit: number;
    type: 'default';
    logs: {
      section: 'gameplay';
      customProps: {
        gameplay_message_type: MessageType;
        gameplay_origin: string;
        gameplay_game_type: string;
        gameplay_template_id: number;
      };
    };
  };
  serverCallbackArgs: {
    APP_USER_ID: number;
    APP_ID: number;
    GAME_TYPE: string;
    MESSAGE_TYPE: MessageType;
    HAS_REWARD: boolean;
    SHARE_ID?: string;
  };
}

window.Kakao.Share.sendCustom({
  installTalk: true,
  templateId: 126533, // CBT=126532, PROD=126533
  templateArgs: {
    THU: THUMBNAIL_URL,
    TITLE: 'MESSAGE_TITLE',
    DESCRIPTION: 'MESSAGE_DESCRIPTION',
    BUTTON_TEXT: '지금 플레이',
    BUTTON_URL: response.short_url,
  },
  pickerSettings: {
    args: {
      copy_url: response.short_url,
    },
    groupId: PICKER_GROUP_ID, // CBT=10, PROD=12
    limit: 1,
    type: 'default',
    logs: {
      section: 'gameplay',
      customProps: {
        gameplay_message_type: 'GAME_SHARE',
        gameplay_origin: `${PARTNER_NAME}_GAME`,
        gameplay_game_type: `${PARTNER_NAME}_${GAME_TITLE}`,
        gameplay_template_id: TEMPLATE_ID, // CBT=126532, PROD=126533
      },
    },
  },
  serverCallbackArgs: {
    APP_USER_ID: 1111111,
    APP_ID: 1234567,
    GAME_TYPE: 'sample-game',
    MESSAGE_TYPE: 'GAME_SHARE',
    HAS_REWARD: true,
    SHARE_ID: 'a3f2c5b7-9d11-4e8a-9f01-2b6c7e8a9d10',
  },
} satisfies SendCustomPayload);

필드 상세

templateArgs 필수

템플릿에 ${KEY} 형태로 정의된 값을 동일한 key로 전달합니다.
같은 템플릿을 사용하더라도 공유 대상 게임에 따라 실제 메시지 내용과 이미지가 달라지도록 구성합니다.

인자	설명	스펙
`THU`	공유 대상 게임의 대표 이미지 또는 썸네일 URL	—
`TITLE`	메시지 제목	최대 1줄, 최대 15자 (공백 포함)
`DESCRIPTION`	메시지 본문	최대 2줄, 100자 내외
`BUTTON_TEXT`	버튼 텍스트	최대 10자 (공백 포함)
`BUTTON_URL`	버튼 랜딩 링크. 단축 URL 응답값(`short_url`) 사용	—

serverCallbackArgs 필수

공유 웹훅으로 전달되어 로그 수집에 사용됩니다.

필드	타입	적용 여부	설명
`APP_USER_ID`	`long`	✓	파트너사 앱 사용자 식별자 (공유 주체)
`APP_ID`	`long`	✓	파트너사 식별자 (다중 게임 운영 시 라우팅)
`GAME_TYPE`	`string`	✓	게임플레이 파트너센터오픈 예정에 등록한 게임 코드와 동일한 게임 식별자
`MESSAGE_TYPE`	`enum`	✓	`GAME_SHARE` (게임 공유) 또는 `RANKING_SHARE` (자랑하기)
`HAS_REWARD`	`boolean`	✓	`true`: 보상 있음, `false`: 단순 공유
`SHARE_ID`	`string` (UUID)		파트너사가 공유 시점에 발급하는 트랜잭션 식별자. 콜백 응답 매칭 키

pickerSettings 필수

필드	설명	값
`args.copy_url`	URL 복사 링크	단축 URL 응답값(`short_url`)
`groupId`	공유 피커 그룹 ID	CBT `10`, PROD `12`
`limit`	공유 대상 선택 가능 수	`1`
`type`	공유 대상 선택 화면 유형	`default`
`logs.section`	공유 로그 구분값	`gameplay`
`logs.customProps.gameplay_message_type`	소재 구분	`GAME_SHARE` / `RANKING_SHARE` / `REWARD_SHARE`
`logs.customProps.gameplay_origin`	파트너사 게임 출처 구분값	`{파트너사명}_GAME`, 사전 협의 필요
`logs.customProps.gameplay_game_type`	파트너사명과 게임 이름 결합 식별값	`{파트너사명}_${GAME_TITLE}`
`logs.customProps.gameplay_template_id`	사용 템플릿 ID	CBT `126532`, PROD `126533`

참고 문서

카카오 JS SDK: SDK 설치와 초기화
단축 URL 생성: 공유용 단축 URL 발급
공유 웹훅 연동: 공유 성공 후 파트너사 서버로 결과 통지
심사 체크리스트: 공유 관련 자체 점검 사항
카카오톡 공유 JavaScript 가이드
사용자 정의 템플릿 사용자 인자 가이드

심사 가이드

애드핏 설정

공유 설정

적용 범위

사전 셋팅 항목 필수

카카오 제공 값

파트너사 설정 항목 필수

사전 이해 사항

공유 흐름

공유 타입

카카오톡 공유 템플릿 ID 필수

구현 상세 안내

SDK 초기화 필수

단축 URL 생성 API 호출 필수

공유 호출 필수

필드 상세

templateArgs 필수

serverCallbackArgs 필수

pickerSettings 필수

참고 문서

공유 설정 ​

적용 범위 ​

사전 셋팅 항목 필수 ​

카카오 제공 값 ​

파트너사 설정 항목 필수 ​

사전 이해 사항 ​

공유 흐름 ​

공유 타입 ​

카카오톡 공유 템플릿 ID 필수 ​

구현 상세 안내 ​

SDK 초기화 필수 ​

단축 URL 생성 API 호출 필수 ​

공유 호출 필수 ​

필드 상세 ​

templateArgs 필수 ​

serverCallbackArgs 필수 ​

pickerSettings 필수 ​

참고 문서 ​

공유 설정

적용 범위

사전 셋팅 항목 필수

카카오 제공 값

파트너사 설정 항목 필수

사전 이해 사항

공유 흐름

공유 타입

카카오톡 공유 템플릿 ID 필수

구현 상세 안내

SDK 초기화 필수

단축 URL 생성 API 호출 필수

공유 호출 필수

필드 상세

templateArgs 필수

serverCallbackArgs 필수

pickerSettings 필수

참고 문서