---
url: /docs/share/settings.md
description: 카카오 JS SDK 기반 카카오톡 공유·URL 복사 연동 방법
---

# 공유 설정

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

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

## 적용 범위

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

## 사전 셋팅 항목 

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

### 카카오 제공 값

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

### 파트너사 설정 항목 

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

## 사전 이해 사항

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

SDK 설치와 초기화 방법은 [카카오 JS SDK](/api-sdk/sdk/kakao-js)를 참고하세요.

## 공유 흐름

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

## 공유 타입

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

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

## 카카오톡 공유 템플릿 ID 

카카오톡 공유는 하나의 템플릿 ID로 메시지 타입별 소재를 구분해 사용합니다.
템플릿 ID는 카카오가 사전 생성해 파트너사에 전달하는 값이며, 디벨로퍼스 문서에서는 [사용자 정의 템플릿](https://developers.kakao.com/docs/ko/message-template/custom#how-to-use)이라는 이름으로 안내됩니다.

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

메시지 타입:

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

## 구현 상세 안내

### SDK 초기화 

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

```ts
window.Kakao.init('JAVASCRIPT_KEY');
```

설치 스크립트와 버전 요구사항은 [카카오 JS SDK](/api-sdk/sdk/kakao-js)에 정리되어 있습니다.

### 단축 URL 생성 API 호출 

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

```ts
interface ShortUrlResponse {
  short_url: string;
}

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

API 상세는 [단축 URL 생성](/api-sdk/share/short-url)을 참고하세요.

### 공유 호출 

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

```ts
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](/api-sdk/sdk/kakao-js): SDK 설치와 초기화
* [단축 URL 생성](/api-sdk/share/short-url): 공유용 단축 URL 발급
* [공유 웹훅 연동](/api-sdk/share/reward-result): 공유 성공 후 파트너사 서버로 결과 통지
* [심사 체크리스트](/docs/checklist/review-checklist): 공유 관련 자체 점검 사항
* [카카오톡 공유 JavaScript 가이드](https://developers.kakao.com/docs/ko/kakaotalk-share/js-link)
* [사용자 정의 템플릿 사용자 인자 가이드](https://developers.kakao.com/docs/ko/message-template/custom#user-argument-text)