게임플레이 파트너 가이드

테마 전환

단축 URL 생성 ​

공유 피커에서 URL 복사 기능을 사용하려면 공유 SDK 호출 전에 단축 URL을 발급받아야 합니다.
응답의 short_url을 공유 SDK 호출 시 templateArgs.BUTTON_URL과 pickerSettings.args.copy_url에 주입합니다.

관련 가이드: 공유 설정

Endpoint ​

http
GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url

헤더 ​

Header설명
Authorization필수KakaoAK {APP_KEY}: 파트너사 디벨로퍼스 앱의 REST API 키
Content-Type필수application/json

인증 ​

  • Authorization 헤더의 APP_KEY 검증
  • IP ACL 기반(사전 등록된 IP만 허용) 이중 인증

파트너사 정보 전달 양식에서 제출한 IP를 사용합니다.

파라미터 ​

위치이름타입설명
pathgameCodestring필수파트너사 기준 게임 ID
query파트너사 정의 키string공유 링크에 실어 게임으로 다시 전달할 딥링크 파라미터. key=value 형태로 0~N개 전달합니다. 제약은 딥링크 파라미터를 참고하세요.

전달한 딥링크 파라미터는 발급된 단축 URL에 포함되어, 사용자가 공유 링크로 게임에 진입할 때 게임으로 다시 전달됩니다.
파라미터를 전달하지 않으면 기존과 동일하게 동작합니다(하위 호환).

딥링크 파라미터 ​

게임 진입 시 함께 넘기고 싶은 값을 쿼리 파라미터로 전달하면, 카카오가 검증한 뒤 공유 링크에 추가합니다.
아래 제약을 벗어나면 -2 에러가 반환됩니다.

제약 항목값
예약 키(사용 불가)referer, t_src, t_ch, t_obj (대소문자 무시)
키 허용 문자A~Z, a~z, 0~9, _, -
최대 파라미터 개수20개
키 최대 길이64자
값 최대 길이512자
파라미터 전체 길이2,048자
값 인코딩UTF-8 URL 인코딩되어 추가됩니다
동일 키 중복첫 번째 값만 사용합니다

예약 키(referer·t_src·t_ch·t_obj)는 카카오 공유 트래킹용으로 예약되어 있어 파트너사 파라미터로 사용할 수 없습니다.

요청 예시

http
GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url?stage=3&invite=abc123

위 요청으로 발급한 단축 URL로 사용자가 진입하면 stage=3·invite=abc123이 게임으로 전달됩니다.

응답 ​

json
{
  "short_url": "https://gameplay.kakao.com/s/xxxxxxx"
}

에러 코드 ​

code설명
-2gameCode가 전달되지 않았거나, 딥링크 파라미터가 제약을 벗어난 경우(예약 키 사용, 허용 문자 위반, 개수·길이 초과 등)
-852gameCode로 조회되는 게임이 없는 경우
-900허용되지 않은 IP에서 접근한 경우

Rate Limit ​

모든 API에 공통으로 요청 IP 기준 Rate Limit이 적용됩니다.

항목값
제한 기준요청 IP 단위
허용량최대 1,000 RPS
Burst순간 최대 2,000 requests

제한 초과 시 503 Service Temporarily Unavailable이 반환됩니다.

참고 문서 ​