이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오스토리 기능 구현 방법을 안내합니다.
JavaScript SDK는 Android, iOS SDK와 달리 카카오스토리 공유 기능을 웹뷰 형태로 제공합니다. 사용자는 카카오 로그인 후 웹 페이지에 삽입된 공유 버튼을 클릭해 스토리를 쓰거나 웹 페이지 정보를 공유할 수 있습니다.
이 문서에 포함된 기능 일부는 [도구] > [JS 데모]를 통해 사용해 볼 수 있습니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | - | request() |
현재 로그인한 사용자가 카카오스토리를 사용하고 있는지 확인합니다. 카카오스토리 미사용으로 인한 에러를 방지할 수 있습니다.
url
값을 /v1/api/story/isstoryuser
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/isstoryuser 로 고정 |
O |
Kakao.API.request({
url: '/v1/api/story/isstoryuser',
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 카카오스토리 프로필 URL |
request() |
현재 로그인한 사용자의 카카오스토리 프로필을 불러옵니다.
사용자는 카카오계정, 카카오톡, 카카오스토리에 각각 프로필을 설정할 수 있으므로, 카카오스토리 프로필 가져오기 API로 불러온 프로필은 사용자 정보나 카카오톡 프로필 가져오기 API로 조회한 정보와 별개입니다.
url
값을 /v1/api/story/profile
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/profile 로 고정 |
O |
Kakao.API.request({
url: '/v1/api/story/profile',
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
현재 로그인한 사용자의 카카오스토리에 새로운 스토리를 작성합니다.
스토리 쓰기는 다음 세 가지 종류의 API를 제공합니다.
타입 | 설명 | URL |
---|---|---|
글(Note) | 텍스트로 구성된 스토리 | /v1/api/story/post/note |
사진(Photo) | 텍스트와 사진으로 구성된 스토리 | /v1/api/story/post/photo |
링크(Link) | 텍스트와 스크랩할 웹 페이지에서 얻은 정보로 구성된 스토리 | /v1/api/story/post/link |
작성하려는 스토리의 종류에 따라 전달해야 할 파라미터가 다릅니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
request() |
사진이나 웹 페이지 URL 등 다른 요소 없이 글로만 구성된 스토리를 게시할 때 사용합니다.
url
값을 /v1/api/story/post/note
로 지정해 Kakao.API.request()
함수를 호출합니다. 글 스토리 쓰기 시, 스토리 내용 텍스트를 담은 data
하위의 content
파라미터를 필수 전달해야 합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/post/note 로 고정 |
O |
data | Object |
API에 전달할 파라미터 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | O |
permission | String |
스토리 공개 범위F : 친구에게만 공개A : 전체 공개M : 나만 보기(기본값: A ) |
X |
enable_share | Boolean |
친구 공개 스토리인 경우 공유 설정 (기본값: false ) |
X |
android_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터 | X |
ios_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터 | X |
android_market_param | String |
스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터 | X |
ios_market_param | String |
스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터 | X |
Kakao.API.request({
url: '/v1/api/story/post/note',
data: {
content: '스토리에 들어갈 글을 작성해주세요.',
},
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
request() |
사진과 글로 구성된 스토리를 게시할 때 사용합니다.
사진 스토리 쓰기 요청 시 이미지 업로드하기를 통해 구한 URL만 사용할 수 있습니다. 임의의 데이터 전달 시 요청에 실패합니다.
이미지 업로드하기 API를 통해 스토리 쓰기에 사용할 이미지를 카카오 플랫폼에 업로드하여 이미지의 경로와 크기 정보를 구할 수 있습니다. 업로드할 이미지의 크기는 10MB 이하, 갯수는 10개 이하여야 합니다. 단, GIF 파일은 1개만 올릴 수 있습니다.
이미지를 업로드하려면 url
값을 /v1/api/story/upload/multi
로 지정해 Kakao.API.request()
함수를 호출합니다. 이미지 업로드에 성공하면 사진 스토리 쓰기 API를 호출하는 함수를 호출합니다.
사진 스토리 쓰기 API는 url
값을 /v1/api/story/post/photo
로 지정해 Kakao.API.request()
함수로 호출합니다. 글 스토리 쓰기 시, 스토리 내용 텍스트를 담은 content
는 선택 파라미터이나, 스토리에 첨부할 이미지 정보를 담은 image_url_list
파라미터는 필수로 전달해야 합니다.
Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
이미지 업로드하기: /v1/api/story/upload/multi 로 고정 사진 스토리쓰기: /v1/api/story/post/photo 로 고정 |
O |
data | Object |
API에 전달할 파라미터 자세한 내용은 data: 이미지 업로드하기, data: 사진 스토리 쓰기 확인 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
files | FileList | File[] |
<input> 태그를 통해 입력된 업로드할 File 객체 목록 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
image_url_list | String[] |
이미지 업로드하기 API를 통해 얻은 이미지들의 경로와 이미지의 가로와 세로 길이 | O |
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | X |
permission | String |
스토리 공개 범위F : 친구에게만 공개A : 전체 공개M : 나만 보기(기본값: A ) |
X |
enable_share | Boolean |
친구 공개 스토리인 경우 공유 설정 (기본값: false ) |
X |
android_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터 | X |
ios_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터 | X |
android_market_param | String |
스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터 | X |
ios_market_param | String |
스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터 | X |
var files = document.getElementById('input-file').files;
Kakao.API.request({
url: '/v1/api/story/upload/multi',
files: files,
})
.then(function(uploadedUrls) {
return Kakao.API.request({
url: '/v1/api/story/post/photo',
data: {
image_url_list: uploadedUrls,
},
});
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
request() |
웹 페이지를 공유하는 스토리를 게시합니다.
링크 스토리 쓰기 요청 시 웹 페이지 스크랩하기 API를 통해 구한 웹 페이지 스크랩 정보만 사용할 수 있습니다. 임의의 데이터 전달 시 요청에 실패합니다.
링크 스토리 쓰기 API 호출 전, 웹 페이지 스크랩하기 API를 호출하여 스토리에 사용할 웹 페이지 정보를 미리 스크랩해야 합니다. url
값을 /v1/api/story/linkinfo
로 지정해 Kakao.API.request()
함수를 호출합니다. 웹 페이지는 오픈 그래프 프로토콜(Open Graph Protocol)을 기반으로 스크랩합니다.
웹 페이지 스크랩 성공 시, 링크 스토리 쓰기 API를 호출할 수 있습니다. url
값을 /v1/api/story/post/link
로 지정해 Kakao.API.request()
함수를 호출합니다. 스토리 내용 텍스트를 담은 content
는 선택 파라미터이나, 스토리에 첨부할 링크 정보를 담은 link_info
파라미터는 필수로 전달해야 합니다.
Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
웹 페이지 스크랩하기: /v1/api/story/linkinfo 로 고정 링크 스토리 쓰기: /v1/api/story/post/link 로 고정 |
O |
data | Object |
API에 전달할 파라미터 자세한 내용은 data: 웹 페이지 스크랩하기, data: 링크 스토리 쓰기 확인 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
스크랩할 웹 페이지 URL | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
link_info | Object |
웹 페이지 스크랩하기 API를 통해 얻은 스크랩할 웹 페이지 정보 | O |
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | X |
permission | String |
스토리 공개 범위F : 친구에게만 공개A : 전체 공개M : 나만 보기(기본값: A ) |
X |
enable_share | Boolean |
친구 공개 스토리인 경우 공유 설정 (기본값: false ) |
X |
android_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터 | X |
ios_exec_param | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터 | X |
android_market_param | String |
스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터 | X |
ios_market_param | String |
스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터 | X |
이름 | 타입 | 설명 |
---|---|---|
url | String |
스크랩한 웹 페이지 URL 단축 URL의 경우 실제 URL |
requested_url | String |
요청 시 전달된 URL |
host | String |
URL Host |
title | String |
웹 페이지 타이틀 |
image | String[] |
웹 페이지의 대표 이미지 URL, 최대 3개 |
description | String |
웹 페이지 설명 |
type | String |
웹 페이지가 포함한 콘텐츠 타입 정보 website, video, music 등 |
section | String |
웹 페이지 섹션 정보 |
Kakao.API.request({
url: '/v1/api/story/linkinfo',
data: {
url: 'https://developers.kakao.com',
},
})
.then(function(scrappedLink) {
return Kakao.API.request({
url: '/v1/api/story/post/link',
data: {
link_info: scrappedLink,
},
});
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
현재 로그인한 사용자의 카카오스토리에서 스토리 목록을 불러옵니다.
다음 두 가지 방법으로 스토리를 가져올 수 있습니다.
스토리 가져오기 요청 시 하나의 스토리를 요청하는지, 여러 개의 스토리를 요청하는지에 따라 전달해야 할 파라미터가 다릅니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
request() |
여러 개의 스토리를 요청합니다.
last_id
파라미터를 지정하면 특정 스토리부터 그 이전 정보를 가져올 수 있습니다. 요청 성공 시, 응답에는 댓글(comments)과 느낌(likes) 수가 포함됩니다.
url
값을 /v1/api/story/mystories
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/mystories 로 고정 |
O |
data | Object |
API에 전달할 파라미터 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
last_id | String |
정보를 원하는 마지막 스토리 아이디 해당 스토리를 제외하고, 그 이전에 작성된 스토리 정보가 제공됨 기본 값은 가장 최근 작성된 스토리 아이디 파라미터 미포함 시 가장 최근 스토리 정보부터 제공 |
X |
Kakao.API.request({
url: '/v1/api/story/mystories',
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
request() |
하나의 스토리를 지정해 요청합니다.
스토리 ID
를 필수 전달해야 합니다. 특정 스토리 ID를 지정하여 요청하면 해당 스토리의 댓글을 포함한 상세 정보를 받을 수 있습니다.
url
값을 /v1/api/story/mystory
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/mystory 로 고정 |
O |
data | Object |
API에 전달할 파라미터 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
정보를 원하는 스토리 아이디 | O |
Kakao.API.request({
url: '/v1/api/story/mystory',
data: {
id: '${STORY_ID}',
},
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
request() |
현재 로그인한 사용자의 카카오스토리에서 지정한 ID에 해당하는 스토리를 삭제합니다.
삭제할 스토리 게시물의 ID를 알고 있어야 요청 가능하므로, 내 스토리 가져오기 또는 스토리 쓰기 요청을 통해 해당 스토리의 ID를 확인하거나, 참고할 수 있는 스토리 ID 값이 있어야 합니다.
url
값을 /v1/api/story/delete/mystory
로 지정해 Kakao.API.request()
함수를 호출합니다. Kakao.API.request()
는 Promise
를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
/v1/api/story/delete/mystory 로 고정 |
O |
data | Object |
API에 전달할 파라미터 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
삭제할 스토리 ID | O |
Kakao.API.request({
url: '/v1/api/story/delete/mystory',
data: {
id: '${STORY_ID}',
},
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | createShareButton() |
웹 페이지에 카카오스토리 공유 버튼을 추가하는 기능입니다. Kakao.Story.createShareButton()
을 호출하면 버튼을 생성합니다 해당 버튼을 클릭하면 공유하기 웹뷰(Web view)를 띄우는 기능이 추가됩니다. container
파라미터로 카카오스토리 공유 버튼이 나타날 위치를 지정합니다.
[도구] > [소셜 플러그인] 메뉴에서 내 웹 페이지에 맞춘 크기의 카카오스토리 공유하기 버튼과 소스코드를 손쉽게 만들어 쓸 수 있습니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
container | String |
카카오스토리 공유하기 버튼을 추가할 위치의 Element ID | O |
url | String |
카카오스토리에 공유할 웹 페이지 URL | O |
text | String |
공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용 | O |
Kakao.Story.createShareButton({
container: '#kakaostory-share-button',
url: 'https://developers.kakao.com',
text: '카카오 개발자 사이트로 놀러오세요! #개발자 #카카오 :)',
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | share() |
카카오스토리에 새로운 스토리를 쓰는 웹뷰를 띄우는 기능입니다. 공유 버튼 클릭 시 Kakao.Story.share()
를 호출합니다. 사용자가 공유 버튼을 클릭하면 카카오 로그인 웹뷰가 나타나고, 로그인 후 공유하기 웹뷰가 나타납니다. 만약 이미 로그인한 상태라면 바로 공유하기 웹뷰를 띄웁니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
카카오스토리에 공유할 웹 페이지 URL | O |
text | String |
공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용 | O |
Kakao.Story.share({
url: 'https://developers.kakao.com',
text: '카카오 개발자 사이트로 놀러오세요! #개발자 #카카오 :)',
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | open() |
Kakao.Story.open()
을 호출하면 카카오스토리 앱을 통해 지정한 웹 페이지를 공유할 수 있습니다. 웹 페이지 정보는 오픈 그래프 프로토콜(Open Graph Protocol) 기반으로 스크랩합니다.
이 API는 특정 정보를 카카오스토리 앱에 전달해 보다 쉽게 공유할 수 있도록 도와주는 기능입니다. 사용자가 웹 페이지를 공유 완료했는지는 알려주지 않습니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
url | String |
공유할 웹 페이지 URL | O |
text | String |
공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용 | O |
urlInfo | UrlInfoObject |
웹 페이지를 스크랩한 정보 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
웹 페이지 타이틀 | O |
desc | String |
웹 페이지 설명 | X |
name | String |
웹 페이지 이름 | X |
images | String[] |
웹 페이지 대표 이미지 URL | X |
Kakao.Story.open({
url: 'http://blog.kakaocorp.co.kr/390',
text: '카카오검색에서 카카오스토리를! #카카오스토리 #카카오검색 :)',
});
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | createFollowButton() |
사용자가 특정 카카오스토리 채널의 소식을 받을 수 있도록 하는 기능입니다. 소식 받기 버튼을 배치할 위치에서 Kakao.Story.createFollowButton()
를 호출합니다. container
위치에 구독 버튼이 생성되며, 버튼 클릭 시 카카오 JavaScript SDK가 로그인한 사용자 정보로 id
에 해당하는 카카오스토리 채널에 구독 요청을 보냅니다.
이 기능은 로그인한 사용자 정보로 구독 요청을 보내는 방식으로 동작합니다. 따라서 사용자가 로그인되어 있지 않다면 카카오 로그인 웹뷰를 통해 먼저 로그인하는 과정을 거칩니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
container | String |
버튼을 추가할 위치의 Element ID | O |
id | String |
소식 받기할 카카오스토리 채널 ID | O |
showFollowerCount | String |
해당 채널 구독자 수 'container' Element의 data-show-follower-count Attribute로 대신할 수 있음 |
X |
type | String |
구독자 수 노출 형태 'container' Element의 data-type Attribute로 대신할 수 있음 |
X |
Kakao.Story.createFollowButton({
container: '#kakaostory-follow-button',
id: 'kakao',
});
카카오스토리의 Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 개발 가이드는 다음 링크에서 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.