이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 |
request() |
현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 받습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.
url
값을 /v1/api/talk/profile
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/talk/profile 로 고정 |
O |
Kakao.API.request({
url: '/v1/api/talk/profile',
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요: 사용 권한 |
플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함) |
사용자가 카카오톡 친구를 선택할 수 있는 피커를 호출합니다. 선택 유형에 따라 호출해야 할 함수가 다르므로, 서비스의 필요에 맞는 함수를 선택해 사용합니다.
선택 유형 | 함수 |
---|---|
싱글 피커 | selectFriend() |
멀티 피커 | selectFriends() |
JavaScript SDK를 사용해 피커를 호출할 경우, 서비스 UI/UX에 맞춰 피커 화면으로 자연스럽게 이동할 수 있도록 두 가지 사용 방식을 제공합니다.
Promise
로 전달returnUrl
로 리다이렉트(HTTP 302 Redirect)하여 쿼리 스트링(Query string)으로 전달returnUrl
의 사이트 도메인 등록 필수피커의 구성 요소, 언어는 파라미터를 사용해 선택적으로 지정할 수 있습니다. 아래 표를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
친구 피커의 타이틀 영역에 표시될 텍스트 (기본값: "친구 선택") |
X |
enableSearch | Boolean |
친구 검색 기능 사용 여부 (기본값: true ) |
X |
showMyProfile | Boolean |
내 프로필 표시 여부true 일 경우 자신의 프로필 선택 가능(기본값: true ) |
X |
showFavorite | Boolean |
즐겨찾기 친구 표시 여부 (기본값: true ) |
X |
showPickedFriend | Boolean |
멀티 피커 전용 선택한 친구 표시 여부 (기본값: true ) |
X |
maxPickableCount | Number |
멀티 피커 전용 선택 가능한 친구 수의 최대 값 minPickableCount 보다 크거나 같은 수(기본값: 30 , 최대: 100 ) |
X |
minPickableCount | Number |
멀티 피커 전용 선택 가능한 친구 수의 최소 값 maxPickableCount 보다 작거나 같은 수(기본값: 1 , 최대: 100 ) |
X |
returnUrl | String |
리다이렉트 방식 사용 시 필수 선택한 친구 정보를 받을 서비스 URL 비고: [내 애플리케이션] > [플랫폼] > [Web]에 등록된 사이트 도메인만 허용 |
X |
enableBackButton | Boolean |
리다이렉트 방식 전용 뒤로가기 버튼 사용 여부 지정 true : 사용false : 미사용(기본값: true ) |
X |
// 팝업 방식
Kakao.Picker.selectFriends({
title: '친구 선택',
maxPickableCount: 10,
minPickableCount: 1,
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
// 리다이렉트 방식
// 성공: ${returnUrl}?selected=${SelectedUsers}
// 실패: ${returnUrl}?error=${Error}
Kakao.Picker.selectFriends({
returnUrl: 'https://developers.kakao.com', // 필수
title: '친구 선택',
maxPickableCount: 10,
minPickableCount: 1,
});
사용자가 피커 화면에서 친구 선택을 완료하면 SelectedUsers
객체가 반환됩니다. 해당 객체는 선택된 각 친구의 정보를 SelectedUser
객체의 배열로 포함합니다. 요청에 실패했거나 문제가 발생한 경우 문제 해결에서 원인을 확인합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
selectedTotalCount | Number |
친구 피커에서 사용자가 선택한 친구 수 선택한 친구 정보 목록의 친구 수와 다를 수 있음 참고: 피커를 통해 제공받은 친구 정보의 수가 선택한 친구 수보다 적은 경우 |
O |
users | SelectedUser[] |
선택한 친구 정보 목록 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
uuid | String |
친구마다 고유한 값을 가지는 참고용 코드(Code) 카카오톡 메시지 전송 시 사용 참고: 카카오톡을 탈퇴하거나 새로 가입할 경우 값이 변경될 수 있음 |
O |
id | String |
친구의 회원번호 | X |
profile_nickname | String |
카카오톡 프로필 닉네임 | X |
profile_thumbnail_image | String |
카카오톡 프로필 썸네일 이미지 | X |
favorite | Boolean |
카카오톡 친구 즐겨찾기 설정 여부 | X |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
필요: 사용 권한 |
플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함) |
request() |
현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 받아 옵니다.
정렬 순서, 한 페이지에 가져올 친구 수 등 파라미터를 선택적으로 사용하여 요청할 수 있습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.
응답 중 각 친구의 uuid
값은 메시지 보내기 API 요청 시 사용하는 수신자 정보로, 메시지 보내기 전 친구 목록을 먼저 받아와야 해당 값을 구할 수 있습니다.
카카오톡 친구 수가 요청 시 limit
보다 많다면 결과가 페이지로 나뉩니다. 응답에 포함된 after_url
을 사용해 친구 목록 받기를 요청하면 파라미터를 다시 지정하지 않고도 다음 페이지의 친구 목록을 받아올 수 있습니다.
url
값을 /v1/api/talk/friends
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/talk/friends 로 고정 |
O |
data | Object |
API에 전달할 파라미터 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
offset | Number | 친구 목록 시작 지점(기본값: 0) | X |
limit | Number | 한 페이지에 가져올 친구 최대 수(기본값: 10, 최대: 100) | X |
order | String | 친구 목록 정렬 순서, 오름차순("asc") 또는 내림차순("desc")(기본값 "asc") | X |
friend_order | String | 친구 목록 정렬 시, 즐겨찾기 친구의 우선 정렬 또는 닉네임 순서 정렬로 기준 설정 즐겨찾기 친구( favorite ) 또는 카카오톡 닉네임(nickname )(기본값: favorite ) |
X |
Kakao.API.request({
url: '/v1/api/talk/friends',
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
카카오톡 소셜의 Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 개발 가이드는 다음 링크에서 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.