카카오스토리

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

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

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

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

시작하기 전에

Kakao iOS SDK를 설치하고 초기화해야 합니다. 자세한 내용은 시작하기를 참고해 주세요.

카카오스토리 관련 API를 호출할때 리턴될 수 있는 에러는 아래와 같습니다.

  • KOServerErrorBadParameter: 올바르지 않은 파라미터가 전송된 경우 발생합니다.
  • KOServerErrorInsufficientScope: 해당 API에 대한 퍼미션이 없는 앱이 요청한 경우 발생합니다.
  • KOServerErrorUnknown: 서버 내부에서 에러가 발생한 경우입니다.
  • KOServerErrorNotSignedUpUser: 해당 앱에 가입되지 않은 사용자가 호출한 경우에 발생합니다.
  • KOServerErrorNotStoryUser: 카카오스토리 미가입 사용자가 요청한 경우 발생합니다.
  • KOServerErrorStoryImageUploadSizeExceed: 카카오스토리로 포스팅하면서 업로드시 이미지 용량이 초과하였을 경우 발생합니다. 이미지는 10MB로 제한되어 있습니다.
  • KOServerErrorStoryUploadTimeout: 카카오스토리로 이미지 업로드시 지정된 시간을 초과하였을 경우 발생합니다.
  • KOServerErrorStoryInvalidScrapUrl: 카카오스토리로 스크랩시 스크랩하고자 하는 URL이 올바르지 않을 경우 발생합니다.
  • KOServerErrorStoryInvalidPostId: 카카오스토리로 내스토리 정보(들) 요청시 잘못된 내스토리 아이디(포스트 아이디)로 요청하였을 경우 발생합니다.
  • KOServerErrorStoryMaxUploadNumberExceed: 카카오스토리로 이미지 업로드시 지정된 파일 갯수를 초과하였을 경우 발생합니다. 다수 이미지 업로드시 한 요청당 파일 5개(단, gif는 1개)까지만 허용됩니다.
  • KOServerErrorApiLimitExceed: 허용된 요청 횟수가 초과한 경우로 자세한 내용은 쿼터 정책을 참고해 주세요.
  • KOServerErrorUnderMaintenance: 카카오 플랫폼 서비스의 점검으로 인해 올바른 요청을 할 수 없는 경우에 발생합니다.

에러코드의 다른 상세 정보는 KOErrorCode에서 확인 가능합니다.

사용자 확인

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

[KOSessionTask storyIsStoryUserTaskWithCompletionHandler:^(BOOL isStoryUser,
                                                           NSError *error) {
    if (!error) {
        // isStoryUser의 boolean으로 판단합니다. true일 경우 story 사용자입니다.
        if (isStoryUser) {
            NSLog(@"You are a KakaoStory's user");
        } else {
            NSLog(@"You are not a KakaoStory's user");
        }
    } else {
        // error
        NSLog("%@", error);
    }
}];

프로필 요청

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

현재 카카오스토리 프로필 API에서 제공되는 정보는 아래와 같습니다.

  • 사용자의 닉네임 정보 (nickName)
  • 사용자의 생일 (birthday)
  • 사용자의 생일 타입 (birthdayType)
  • 사용자의 프로필 이미지 URL (profileImageURL)
  • 사용자의 프로필 이미지의 썸네일 URL (thumbnailURL). 160px * 213px 크기의 범위내에서 이미지 비율에 맞게 변경
  • 사용자의 배경 이미지 URL (bgImageURL)
  • 내 스토리를 방문할 수 있는 웹 page의 URL (permalink)

[KOSessionTask storyProfileTaskWithCompletionHandler:^(KOStoryProfile* profile,
                                                       NSError* error) {
    if (profile) {
        NSLog(@"%@",profile.nickName);
    } else {
        // failed
        NSLog(@"get story profile failed.");
    }
}];

포스팅

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

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

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

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

요소 설명
공개 범위 (permission) 포스팅 할 스토리를 전체 공개할지 친구 공개할지 나만 공개할지의 여부. KOStoryPostPermission
공유 여부 (sharable) 친구 공개시에 친구가 해당포스팅을 공유할 수 있는지 여부. (전체 공개인 경우는 공유여부 선택불가. 무조건 공유가능) 기본값은 false. BOOL 타입.
앱이동 버튼의 URL 파람들 스토리 상세보기 하단에 포스팅 출처 앱 이름 클릭시 이동하는 URL에 붙일 파라미터.
특정 파라미터를 같이 전달하면 포스팅별로 다른 URL 사용 가능.
해당 실행 URL이 존재하지 않으면 마켓 URL로 이동.
androidExecParam, iosExecParam을 통해 각각 안드로이드, iOS에서 URL로 이동될 때 뒤에 붙는 Key/Value의 파라미터를 지정할 수 있습니다.
핸들러 (completionHandler) 포스팅 후의 후처리를 위한 핸들러. 성공/실패에 따라 포스트 id를 포함한 포스트 정보 또는 에러를 받을 수 있음.
  • 실행 URL
    • 기본 값은 kakao[appkey]://kakaostory 입니다.
  • 마켓 URL
    • 기본 iOS 마켓 URL : https://itunes.apple.com/app/id[앱스토어ID]
      • iOS의 마켓 URL은 설정 > 일반 > 플랫폼 > iOS > iPhone 마켓 URL (iPad 앱이 따로 존재하는 경우는 iPad 마켓 URL)에 설정합니다.
    • 기본 Android 마켓 URL : market://details?id=[android package name]
      • Android앱의 마켓 URL은 설정 > 일반 > 플랫폼 > Android > 마켓 URL 에 설정합니다.
    • 마켓 URL을 설정하지 않으면, 앱 미설치 기기에서 링크 클릭시 반응이 없습니다.
      • 예를 들어 아이폰 앱만 존재하여 설정 > 일반 > 플랫폼 > Android 에 설정을 하지 않은 경우, Android 카카오스토리에서 앱이동 버튼을 클릭하여도 반응이 없습니다.

글(Note) 포스팅

KOSessionTask+StoryAPIstoryPostNoteTaskWithContent:permission:sharable:androidExecParam:iosExecParam:completionHandler: API를 통해 호출합니다.

요소 설명
텍스트(content) 포스팅에 들어갈 내용.
길이제한은 2048자(char).
필수값이므로 설정하지 않을시 KOServerErrorBadParameter 발생.

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

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

// post a note
[KOSessionTask storyPostNoteTaskWithContent:@"post note test"
                                 permission:KOStoryPostPermissionFriend
                                   sharable:YES
                           androidExecParam:@{@"andParam1":@"value1",
                                              @"andParam2":@"value2"}
                               iosExecParam:@{@"iosParam1":@"value1",
                                              @"iosParam2":@"value2"}
                          completionHandler:^(KOStoryPostInfo *post,
                                              NSError *error) {
    if (!error) {
        // 성공
        NSLog(@"postId=%@", post.ID);
    } else {
        // 실패
        NSLog(@"failed to post a note.");
    }
}];

다음은 결과 예시 입니다.

story_post_note.png

사진(Photo) 포스팅

1. 사진 포스팅을 하기 위해서 먼저 KOSessionTask+StoryAPIstoryMultiImagesUploadTaskWithImages:completionHandler: API를 호출합니다. 업로드를 성공하면, 결과인 image URL들로 사진 포스팅을 진행합니다.

2. 위 1에서 얻은 image URL들을 이용하여 KOSessionTask+StoryAPIstoryPostPhotoTaskWithImageUrls:content:permission:sharable:androidExecParam:iosExecParam:completionHandler: API를 호출합니다.

요소 설명
이미지 URL들(imageUrls) 이미지 업로드 결과로 포스팅에 들어갈 이미지들.
필수값이므로 이미지가 없으면 KOServerErrorBadParameter 발생.
텍스트(content) 포스팅에 들어갈 이미지에 대한 내용.
길이제한은 2048자(char).
선택값

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

다음은 이미지 업로드 및 사진 포스팅을 모두 요청하는 예제입니다.

// ex. prepare an array of your images
UIImage *chosenImage1 = myImage1; // your image
UIImage *chosenImage2 = myImage2; // another image
NSMutableArray *chosenImages = [[NSMutableArray alloc] init]; // ex. array(NSArray *) of your images
[chosenImages addObject:chosenImage1];
[chosenImages addObject:chosenImage2];

// upload
[KOSessionTask storyMultiImagesUploadTaskWithImages:chosenImages
                                  completionHandler:^(NSArray *imageUrls,
                                                      NSError* error) {
    if (!error){
        // 업로드 성공

        // post photo
        [KOSessionTask storyPostPhotoTaskWithImageUrls:imageUrls
                                               content:@"post photo test"
                                            permission:KOStoryPostPermissionFriend
                                              sharable:YES
                                      androidExecParam:@{@"andParam1":@"value1",
                                                         @"andParam2":@"value2"}
                                          iosExecParam:@{@"iosParam1":@"value1",
                                                         @"iosParam2":@"value2"}
                                     completionHandler:^(KOStoryPostInfo *post,
                                                         NSError *error) {
            if (!error) {
                // 성공
                NSLog(@"postId=%@", post.ID);
            } else {
                // 실패
                NSLog(@"failed to post photo.");
            }
        }];
    } else {
        // 업로드 실패
        NSLog(@"failed to upload images.");
    }
}];

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

다음은 결과 예시 입니다.

story_post_photo.png

1. 링크 포스팅을 하기 위해서 먼저 KOSessionTask+StoryAPIstoryGetLinkInfoTaskWithUrl:completionHandler: API를 호출합니다. 정보를 성공적으로 얻어오면, 결과인 KOStoryLinkInfo로 링크 포스팅을 진행합니다.

2. 위 1에서 얻은 KOStoryLinkInfo를 이용하여 KOSessionTask+API)의 storyPostLinkTaskWithLinkInfo:content:permission:sharable:androidExecParam:iosExecParam:completionHandler: API를 호출합니다.

요소 설명
링크 정보(스크랩 정보, linkInfo) 링크 스크랩 결과의 객체.
필수값이므로 존재하지 않으면 KOServerErrorBadParameter 발생.
텍스트(content) 포스팅에 들어갈 스크랩에 대한 내용.
길이제한은 2048자(char).
선택값

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

다음은 스크랩을 통해 링크 정보를 얻어온 후 링크를 포스팅하는 예제입니다.

// get a link info
[KOSessionTask storyGetLinkInfoTaskWithUrl:@"https://developers.kakao.com"
                         completionHandler:^(KOStoryLinkInfo *link, NSError *error) {
    if (!error) {
        // 링크 정보 요청 성공

        // post a link
        [KOSessionTask storyPostLinkTaskWithLinkInfo:link
                                             content:@"post link test"
                                          permission:KOStoryPostPermissionFriend
                                            sharable:YES
                                    androidExecParam:@{@"andParam1":@"value1",
                                                       @"andParam2":@"value2"}
                                        iosExecParam:@{@"iosParam1":@"value1",
                                                       @"iosParam2":@"value2"}
                                   completionHandler:^(KOStoryPostInfo *post,
                                                       NSError *error) {
            if (!error) {
                // 성공
                NSLog(@"postId=%@", post.ID);
            } else {
                // 실패
                NSLog(@"failed to post a link.");
            }
        }];
    } else {
        // 링크 정보 요청 실패
        NSLog(@"failed to get a link info.");
    }
}];

다음은 결과 예시 입니다.

story_post_link.png

내스토리 정보 요청

사용자중에 카카오스토리를 사용하는 사용자에 한해, 자신이 올린 스토리의 정보를 가지고 올 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다.

성공 결과는 KOStoryMyStoryInfo로 제공되며, 정보는 아래와 같습니다.

요소 설명
포스트 id(ID) 포스팅 결과로 받는 포스트별 고유 아이디.
글내용(content) 스토리 구성중 텍스트에 해당하는 글 내용.
미디어 타입(mediaType) 미디어 타입 enum.
KOStoryMediaType
미디어(media) PHOTO 스토리인 경우만 제공.
크기별로 이미지 URL로 구성된 KOStoryMyStoryImageInfo의 array
포스트 생성시각(createdAt) RFC3339 internet date/time format
내스토리 정보의 URL(url) 해당 내스토리 정보에 대한 URL
댓글 수(commentCount) 해당 내스토리에 포함된 댓글 수
느낌 수(likeCount) 해당 내스토리에 포함된 느낌 수
댓글 정보(comments) 댓글의 상세 정보.
KOStoryCommentInfo의 array
느낌 정보(likes) 느낌의 상세 정보.
KOStoryLikeInfo의 array
공개 범위(permission) 해당 내스토리의 공개 범위 enum. 예) 전체공개, 친구공개, 나만보기
KOStoryPermission

하나의 내스토리 정보 요청

얻고자 하는 내스토리 id(포스트 id)를 지정하고, KOSessionTask+StoryAPIstoryGetMyStoryTaskWithMyStoryId:completionHandler: API를 호출합니다.

요소 설명
내스토리 id 정보를 원하는 포스트 아이디.
필수값이므로 설정하지 않으면 KOServerErrorBadParameter 발생.
NSString *myStoryId = @"XXXXXXX"; // ex. post id

// get the mystory
[KOSessionTask storyGetMyStoryTaskWithMyStoryId:myStoryId
                              completionHandler:^(KOStoryMyStoryInfo *myStory,
                                                  NSError *error) {
    if (!error) {
        // 성공
        NSLog(@"myStoryId=%@", myStory.ID);
    } else {
        // 실패
        NSLog(@"failed to get the mystory.");
    }
}];

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

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

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

요소 설명
내스토리 id 정보를 원하는 마지막 포스트 아이디.
설정한 포스트 아이디 바로 전 내스토리로부터 복수개의 내스토리들이 반환된다.
설정한 이 포스트 아이디에 해당하는 내스토리 정보는 반환되지 않는다.
NSString *lastMyStoryId = @"XXXXXXX"; // ex. last post id or nil.

// get mystories
[KOSessionTask storyGetMyStoriesTaskWithLastMyStoryId:lastMyStoryId
                                    completionHandler:^(NSArray *myStories,
                                                        NSError *error) {
    if (!error) {
        // 성공
        for (KOStoryMyStoryInfo *myStory in myStories) {
            NSLog(@"myStoryId=%@", myStory.ID);
        }
        //NSLog(@"%@", myStories);
    } else {
        // 실패
        NSLog(@"failed to get mystories.");
    }
}];

내스토리 삭제

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

요소 설명
내스토리 id 삭제를 원하는 포스트 아이디.
NSString *myStoryId = @"XXXXXXX"; // ex. post id

// delete the mystory
[KOSessionTask storyDeleteMyStoryTaskWithMyStoryId:myStoryId
                                 completionHandler:^(NSError *error) {
    if (!error) {
        // 성공
        NSLog(@"the mystory has been deleted successfully.");
    } else {
        // 실패
        NSLog(@"failed to delete the mystory.");
    }
}];

Last Modified : 2017-07-28