카카오스토리

카카오스토리 API는 카카오스토리 서비스에서 제공하는 API를 말합니다. 카카오계정으로 로그인을 하는 앱에서 사용할 수 있고, 카카오스토리 사용자에 대해서만 사용할 수 있습니다.

현재 제공되는 카카오스토리 API는 다음과 같습니다.

  • 사용자 확인
    로그인된 사용자가 카카오스토리를 사용하고 있는지 확인을 합니다.
  • 프로필 요청
    카카오스토리를 사용하는 사용자에 한해 카카오스토리의 프로필 정보를 얻어 옵니다.
  • 포스팅
    로그인된 자신의 카카오스토리에 글, 사진(여러장), 링크(스크랩) 등을 포스팅합니다.
  • 내스토리 요청
    하나 또는 여러개의 내스토리 정보를 얻어 옵니다.
  • 내스토리 삭제
    내스토리를 삭제합니다.

카카오스토리 API를 사용할 때 필요한 버튼은 여기를 참조하세요.

시작하기 전에

  1. 로그인 API를 사용할 수 있는 앱 설정이 되어있는 지 Kakao 계정 로그인이 필요한 앱설정을 참고하여 확인합니다.
  2. 앱 사인(sign)과정에 사용한 키를 설정 > 일반 > 플랫폼 > Android > 키 해시 에 등록한 상태인지 확인합니다.

    키 해시를 생성하는 방법은 앱 생성의 키 해시등록 과정을 참고 합니다.

3. 카카오스토리 포스팅 API를 사용하기 위해 앱으로 연결할 커스텀 스킴을 추가로 등록합니다.

[kakao_strings.xml]

<resources>
    <string name="kakao_app_key">AAAAAAAAAAAAAAAAAAAAAA</string>
    <string name="kakao_scheme">kakaoAAAAAAAAAAAAAAAAAAAAAA</string>
    <string name="kakaostory_host">kakaostory</string>
</resources>
  • 스킴(kakao_scheme): "kakao" 문자열에 앱키의 문자열 값을 붙인 형식입니다. 예) 앱키가 AAAAAAAAAAAAAAAAAAAAAA라면 kakaoAAAAAAAAAAAAAAAAAAAAAA가 커스텀 스킴이 됩니다.
  • 호스트(kakaostory_host) : "kakaostory"로 고정된 값을 사용합니다.

[AndroidManifest.xml]

<uses-permission android:name="android.permission.INTERNET" />

<application
    ...
    <activity
        android:name=".KakaoStoryMainActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="@string/kakao_scheme"
                android:host="@string/kakaostory_host" />
        </intent-filter>
    </activity>
    ...
 </application>

StoryResponseCallback

카카오스토리 API의 공통 Callback. ApiResponseCallback을 상속받아 구현되었다.

Name Return Param Description
onNotKakaoStoryUser void NONE 카카오계정에 연결한 카카오스토리 사용자가 아니여서 요청이 실패한 경우 호출된다.

ProfileResponse

StoryResponseCallback을 통해 성공시 onSuccess의 Param으로 ProfileResponse 정보를 넘겨준다.

Name Type Description
nickName String 카카오톡 별명
profileImageUrl String 480px * 480px ~ 1024px * 1024px 크기의 카카오스토리 프로필 이미지 URL
thumbnailUrl String 160px * 213px 크기(160*213 크기의 범위내에서 이미지 비율에 맞게 변경)의 카카오스토리 썸네일 프로필 이미지 URL
bgImageURL String 480px 480px ~ 1024px 1024px 크기의 카카오스토리 배경 이미지 URL
permalink String 내 공식 스토리 홈 주소
birthday String MMdd
birthdayType BirthdayType SOLAR 또는 LUNAR

StoryType

스토리 포스팅의 종류를 정의한 Enum class

Name Value Description
NOTE "NOTE" Note 타입의 스토리로 text가 꼭 포함되어야 한다.
PHOTO "PHOTO" Photo 타입의 스토리로, 이미지를 먼저 업로드 한후에 이미지 url을 꼭 포함되어야 한다.
LINK "LINK" Link 타입의 스토리로, url로 부터 먼저 정보를 가지고 온 후, 그 결과가 포함되어야 한다.

BirthdayType

카카오스토리의 생일 타입을 정의한 Enum class

Name Value Description
SOLAR "+" 양력
LUNAR "-" 음력

StoryPermission

공개 범위 값을 정의한 Enum class

Name Value Description
PUBLIC "PUBLIC" 전체공개
FRIEND "FRIEND" 친구공개
ONLY_ME "ONLY_ME" 나만보기

MyStoryImageInfo

내스토리의 이미지를 크기별로 얻을 수 있는 class

Field Value Type Description
xlarge String xlarge size image
large String large size image
medium String medium size image
small String small size image
original String 원본이미지

Emoticon

카카오스토리의 느낌 타입을 정의한 Enum class

Name Value Description
LIKE "LIKE" 좋아요
COOL "COOL" 멋져요
HAPPY "HAPPY" 기뻐요
SAD "SAD" 슬퍼요
CHEER_UP "CHEER_UP" 힘내요

StoryActor

작성자의 정보를 얻을 수 있는 class

Field Value Type Description
displayName String 작성자의 이름
profileThumbnailUrl String 작성자의 프로필 썸네일 이미지

StoryComment

내스토리의 댓글 정보를 얻을 수 있는 class

Field Value Type Description
text String xlarge size image
writer StoryActor 작성자에 대한 정보

StoryLike

내스토리의 느낌 정보를 얻을 수 있는 class

Field Value Type Description
emoticon Emoticon xlarge size image
actor StoryActor 작성자에 대한 정보

MyStoryInfo

나의 스토리정보

Field Value Type Description
id String 해당 Activity id
url String 해당 Activity image url
mediaType String "PHOTO", "NOTE", "LINK" 중 하나
createdAt String Activity 생성시간
commentCount int 댓글의 갯수
likeCount int 느낌의 갯수
content String Activity 내용
permission String Activity 접근권한
imageInfoList MyStoryImageInfo List 내스토리의 이미지를 리스트
commentList StoryComment List 내 스토리 댓글 리스트
StoryLike StoryLike List 내 스토리 느낌 리스트

시작하기

API 요청은 KakaoStoryService를 이용하여 요청합니다. 파라미터로 API 요청 결과에 따른 콜백 StoryResponseCallback을 넘깁니다. 아래 예제를 참고하여 StoryResponseCallback 구현합니다.

Name Param Description
onSuccess T 해당 API 요청이 성공한 경우로요청 결과 T를 받습니다.
onSessionClosed ErrorResult 세션이 닫혀 실패한 경우로 에러 결과를 받습니다.
onNotKakaoStoryUser NONE 카카오스토리 사용자가 아니여서 요청이 실패한 경우 호출되는 콜백입니다.
onFailure ErrorResult 요청이 실패한 경우로 에러 결과를 받습니다.
public class KakaoStoryMainActivity extends Activity {

    private void redirectLoginActivity() {
        final Intent intent = new Intent(this, KakaoStoryLoginActivity.class);
        startActivity(intent);
        finish();
    }

    private void redirectSignupActivity() {
        final Intent intent = new Intent(this, KakaoStorySignupActivity.class);
        startActivity(intent);
        finish();
    }

    private abstract class KakaoStoryResponseCallback<T> extends StoryResponseCallback<T> {

        @Override
        public void onNotKakaoStoryUser() {
           Logger.d("not KakaoStory user");
        }

        @Override
        public void onFailure(ErrorResult errorResult) {
            Logger.e("KakaoStoryResponseCallback : failure : " + errorResult);
        }

        @Override
        public void onSessionClosed(ErrorResult errorResult) {
            redirectLoginActivity();
        }

        @Override
        public void onNotSignedUp() {
            redirectSignupActivity();
        }
    }
}

사용자 확인

로그인을 한 사용자가 카카오스토리를 가입했는지, 사용하고 있는지를 확인할 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 다음은 해당 API를 간단히 호출하는 예제 입니다.

private void requestIsStoryUser() {
    KakaoStoryService.requestIsStoryUser(new KakaoStoryResponseCallback<Boolean>() {
        @Override
        public void onSuccess(Boolean result) {
            Logger.d("check story user : " + result);
        }
    });
}

프로필 요청

프로필 요청은 사용자중에 카카오스토리를 사용하는 사용자에 한해 카카오스토리의 프로필 정보를 얻어 올 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다.

KakaoStoryService#requestProfile API를 호출합니다. 이미지 url을 https로 받고 싶은 경우에는 KakaoStoryService#requestProfile(boolean) API를 호출합니다. 다음은 카카오스토리 프로필을 요청하는 예제입니다.

public void readProfile() {
    KakaoStoryService.requestProfile(new KakaoStoryResponseCallback<ProfileResponse>() {
        @Override
        public void onSuccess(ProfileResponse profile) {
            Logger.d("succeeded to get story profile");
        }
    });
}

성공 결과는 ProfileResponse로 제공됩니다..

포스팅

포스팅은 사용자중에 카카오스토리를 사용하는 사용자에 한해, 자신의 카카오스토리에 포스팅할 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다.

포스팅할 수 있는 타입은 아래 세가지 입니다.

  • story_note.png 글(Note): 글을 작성하여 포스팅합니다.
  • story_photo.png 사진(Photo) : 사진을 올리고, 사진에 맞는 이야기를 작성한 후 포스팅합니다.
  • story_link.png 링크(Link): 스크랩할 URL로부터 해당 페이지의 정보(링크)를 얻은 후, 그 정보를 바탕으로 포스팅합니다.

모든 타입의 포스팅에 필요한 요소는 여기서 설명하고 각 타입별로 필요한 요소는 각 세션에서 설명합니다.

Value Type Description Default
permission StoryPermission 포스팅 할 스토리를 전체공개할지 친구공개할지 나만보기를 할지 여부. StoryPermission.PUBLIC
enableShare boolean 친구 공개시에 친구가 해당포스팅을 공유할 수 있는지 여부. (전체 공개인 경우는 공유여부 선택불가. 무조건 공유가능) false
androidExecParam String, Map<String, String> 카카오 스토리에서 '해당 앱으로 이동' 버튼을 눌렀을 때 안드로이드 앱 실행 URL에 같이 붙여줄 파라미터. Kakao Developers_에서 안드로이드 앱 설정을 했을 경우에만 유효 NONE
iosExecParam String, Map<String, String> 카카오 스토리에서 '해당 앱으로 이동' 버튼을 눌렀을 때 iOS 앱 실행 URL에 같이 붙여줄 파라미터. Kakao Developers_에서 iOS 앱 설정을 했을 경우에만 유효 NONE
androidMarketParam String, Map<String, String> 카카오 스토리에서 마켓으로 이동될때 실행 URL에 같이 붙여줄 파라미터. Kakao Developers_에서 안드로이드 앱 설정을 했을 경우에만 유효 NONE
iosMarketParam String, Map<String, String> 카카오 스토리에서 앱스토어로 이동될때 실행 URL에 같이 붙여줄 파라미터. Kakao Developers_에서 iOS 앱 설정을 했을 경우에만 유효 NONE
  • 실행 URL
    • 기본 값은 kakao[appkey]://kakaostory 로 커스텀 스킴 설정은 시작하기 전에를 참고하세요.
  • 마켓 URL
    • 기본 Android 마켓 URL : market://details?id=[android package name]
      • Android앱의 마켓 URL은 설정 > 일반 > 플랫폼 > Android > 마켓 URL 에 설정합니다.
    • 기본 iOS 마켓 URL : https://itunes.apple.com/app/id(앱스토어ID))
      • iOS의 마켓 URL은 설정 > 일반 > 플랫폼 > iOS > iPhone 마켓 URL (iPad 앱이 따로 존재하는 경우는 iPad 마켓 URL)에 설정합니다.
    • 마켓 URL을 설정하지 않으면, 앱 미설치 기기에서 링크 클릭시 반응이 없습니다.
      • 예를 들어 Android 앱만 존재하여 설정 > 일반 > 플랫폼 > iOS 에 설정을 하지 않은 경우, 아이폰 카카오스토리에서 앱이동 버튼을 클릭하여도 반응이 없습니다.

글(Note) 포스팅

KakaoStoryService#requestPostNote API를 호출합니다.

Value Type Description Default
content String 포스트에 들어갈 내용.
2048자(char) 미만 길이제한.
필수값이므로 설정하지 않을시 KakaoParameterException 발생.
없음.

성공 결과는 MyStoryInfo로 포스팅의 id를 포함합니다.

다음은 글 포스팅을 요청하는 예제입니다.

private void requestPostNote() throws KakaoParameterException {
    KakaoStoryService.requestPostNote(new KakaoStoryResponseCallback<MyStoryInfo>() {
        @Override
        public void onSuccess(MyStoryInfo result) {
            Logger.d(result.toString());
        }
    }, content, StoryPermission.PUBLIC, true, execParam, execParam, marketParam, marketParam);
}

다음은 결과 예시 입니다.

story_post_note.png

사진(Photo) 포스팅

KakaoStoryService#requestPostPhoto API를 호출합니다.

이미지 파일의 크기는 파일당 10MB 이하, 갯수는 10개 이하로 제한됩니다. 단, gif 파일은 1개 이하로 제한됩니다.

Value Type Description Default
fileList File List 이미지 업로드 결과로 포스팅에 들어갈 이미지들.
필수값이므로 이미지가 없으면 KakaoParameterException 발생.
NONE
content String 포스팅에 들어갈 이미지에 대한 내용.
2048자(char) 미만 길이제한.
NONE

성공 결과는 MyStoryInfo로 포스팅의 id를 포함합니다.

다음은 사진 포스팅을 요청하는 예제입니다.

private void requestPostPhoto(final String[] imageURLs,
                            final String storyContent) throws KakaoParameterException {
    List<File> fileList = new ArrayList<File>();
    final File uploadFile = new File(writeStoryImage(R.drawable.kakaostory_animated_gif));
    fileList.add(uploadFile);

    StoryPermission permission = StoryPermission.PUBLIC;
    KakaoStoryService.requestPostPhoto(new KakaoStoryResponseCallback<MyStoryInfo>() {
        @Override
        public void onSuccess(MyStoryInfo result) {
            Logger.d(result.toString());
        }

        private void deleteUploadFiles() {
            if (uploadFile != null) {
                uploadFile.delete();
            }
        }
    }, fileList, content, permission, true, execParam, execParam, marketParam, marketParam);
}

다음은 결과 예시 입니다.

story_post_photo.png

KakaoStoryService#requestPostLink API를 호출합니다.

Value Type Description Default
linkUrl String 링크 스크랩 Url.
linkUrl이 스크랩가능하지 않는 url이면 KakaoParameterException 발생.
없음.
content String 포스팅에 들어갈 스크랩에 대한 내용.
2048자(char) 미만 길이제한.
없음.

성공 결과는 MyStoryInfo로 포스팅의 id를 포함합니다.

다음은 링크 포스팅을 요청하는 예제입니다.

private void requestPostLink() throws KakaoParameterException {
    StoryPermission permission = StoryPermission.PUBLIC;
        KakaoStoryService.requestPostLink(new KakaoStoryResponseCallback<MyStoryInfo>() {
            @Override
            public void onSuccess(MyStoryInfo result) {
                Logger.d(result.toString());
            }
        }, scrapUrl, content, permission, true, execParam, execParam, marketParam, marketParam);
}

다음은 결과 예시 입니다.

story_post_link.png

내스토리 정보 요청

사용자중에 카카오스토리를 사용하는 사용자에 한해, 자신이 올린 스토리의 정보를 가지고 올 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 현재는 글 타입과 사진 타입의 내스토리에 대한 정보만 유효합니다. 나머지 타입은 글내용만 포함합니다.

성공 결과는 MyStoryInfo로 제공됩니다.

하나의 내스토리 정보 요청

얻고자 하는 내스토리 id(포스트 id)를 지정하고, KakaoStoryService#requestGetMyStory API를 호출합니다.

Value Type Description Default
storyId String 정보를 원하는 포스트 아이디.
필수값이므로 설정하지 않으면 KakaoParameterException 발생.
없음
private void getMyStory(final String myStoryId) throws KakaoParameterException {
    KakaoStoryService.requestGetMyStory(new KakaoStoryResponseCallback<MyStoryInfo>() {
        @Override
        public void onSuccess(MyStoryInfo result) {
            Logger.d(result.toString());
        }
    }, myStoryId);
}

복수개의 내스토리 정보 요청

가장 최근에 작성된 내스토리 복수개를 요청하거나 지정한 스토리보다 이전에 작성된 내스토리 복수개를 요청할 수 있습니다. 대략 18개 정도의 정보를 한꺼번에 받을 수 있습니다. 지정한 아이디의 내스토리는 결과에 포함되지 않습니다.

마지막 내스토리 id(포스트 id)를 지정하거나, 최근 내스토리를 얻기 위해서는 id를 지정하지 않고, KakaoStoryService#requestGetMyStories API를 호출합니다.

Value Type Description Default
lastMyStoryId String 정보를 원하는 마지막 포스트 아이디.
설정한 포스트 아이디 바로 전 내스토리로부터 복수개의 내스토리 정보 반환.
설정한 이 포스트 아이디에 해당하는 내스토리 정보는 포함되지 않음.
가장 최근 작성된 포스트 아이디
private void getMyStories(final String lastMyStoryId) {
    KakaoStoryService.requestGetMyStories(new KakaoStoryResponseCallback<List<MyStoryInfo>>() {
        @Override
        public void onSuccess(List<MyStoryInfo> result) {
            Logger.d("succeeded to get my posts from KakaoStory.");
        }
    }, lastMyStoryId);
}

내스토리 삭제

사용자중에 카카오스토리를 사용하는 사용자에 한해, 자신이 올린 스토리를 삭제할 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 삭제하고자 하는 내스토리 id(포스트 id)를 지정하고, KakaoStoryService#requestDeleteMyStory API를 호출합니다.

Value Type Description Default
id String 삭제를 원하는 포스트 아이디.
필수값이므로 설정하지 않으면 KakaoParameterException 발생.
없음
private void requestDeleteMyStory(final String myStoryId) throws KakaoParameterException {
    KakaoStoryService.requestDeleteMyStory(new KakaoStoryResponseCallback<Boolean>() {
        @Override
        public void onSuccess(Boolean result) {
            Logger.d("Delete Story is Succeed");
        }
    }, myStoryId);
}

문제해결

카카오스토리 적용중 잘 실행되지 않는다면 카카오스토리 문제해결를 참고해 보세요.


Last Modified : 2017-07-28