이 문서는 Kakao SDK for iOS(이하 iOS SDK)를 사용한 카카오스토리 기능 구현 방법을 안내합니다.
이 기능을 사용하려면 카카오디벨로퍼스(Kakao Developers, 이하 개발자 웹사이트) 애플리케이션(이하 앱) 설정에 iOS 플랫폼 및 번들 ID 등 정보가 등록되어 있어야 합니다. 자세한 내용은 애플리케이션 등록을 참고합니다.
카카오스토리 API는 카카오스토리 모듈인 KakaoSDKStory
및 RxKakaoSDKStory
가 제공합니다. 설치를 참고하여 카카오 로그인, 사용자 인증, 카카오스토리 모듈을 모두 설치합니다.
모듈 설치 후 카카오 로그인과 카카오스토리 API를 사용하려면 다음과 같이 import
합니다.
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKStory
import KakaoSDKAuth
import RxKakaoSDKAuth
import KakaoSDKUser
import RxKakaoSDKUser
import KakaoSDKStory
import RxKakaoSDKStory
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | - | iOS SDKisStoryUser() ReactiveX iOS SDK isStoryUser() |
카카오스토리 미사용으로 인한 에러를 방지하기 위해, 현재 로그인한 사용자가 카카오스토리를 사용하고 있는지 확인합니다.
StoryApi
의 isStoryUser()
로 현재 로그인한 사용자의 카카오스토리 사용 여부를 확인할 수 있습니다. 사용자의 카카오스토리 이용 여부는 Boolean
값으로 사용(true
) 또는 미사용(false
)입니다.
StoryApi.shared.isStoryUser {(isStoryUser, error) in
if let error = error {
print(error)
}
else {
print("isStoryUser() success.")
//do something
_ = isStoryUser
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.isStoryUser()
.subscribe (onSuccess:{ (isStoryUser) in
print("isStoryUser() success.")
//do something
_ = isStoryUser
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 카카오스토리 프로필 URL |
iOS SDKprofile() ReactiveX iOS SDK profile() |
프로필 가져오기는 현재 로그인한 사용자의 카카오스토리 프로필을 불러옵니다. 사용자는 카카오계정, 카카오톡, 카카오스토리에 각각 프로필을 설정할 수 있으므로, 카카오스토리 프로필 가져오기 API로 불러온 프로필은 사용자 정보나 카카오톡 프로필 가져오기 API로 조회한 정보와 별개입니다.
사용자 카카오스토리 프로필을 불러오려면 StoryApi
의 profile()
API를 사용합니다.
StoryApi.shared.profile {(profile, error) in
if let error = error {
print(error)
}
else {
print("profile() success.")
//do something
_ = profile
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.profile()
.subscribe (onSuccess:{ (profile) in
print("profile() success.")
//do something
_ = profile
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
요청 성공 시 사용자의 카카오스토리 프로필을 StoryProfile
객체로 받습니다. 카카오스토리 프로필 정보의 구성 및 자료형은 REST API 가이드 및 레퍼런스에서 확인할 수 있습니다.
현재 로그인한 사용자의 카카오스토리에 새로운 스토리를 작성합니다.
스토리 종류별로 글, 사진과 글, 링크로 나뉜 세 가지 메서드를 제공합니다.
타입 | 설명 | 메서드 |
---|---|---|
글(Note) | 텍스트로 구성된 스토리 | postNote() |
사진(Photo) | 텍스트와 사진으로 구성된 스토리 | postPhoto() |
링크(Link) | 텍스트와 스크랩할 웹 페이지에서 얻은 정보로 구성된 스토리 | postLink() |
스토리마다 포함되어야 할 구성 요소가 다르지만, 다음 파라미터는 공통적으로 설정 가능합니다. 다음 파라미터를 통해 스토리에 포함할 내용 및 링크 정보를 설정할 수 있습니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
permission | Permission |
스토리 공개 범위 Public(전체 공개), Friend(친구 공개), OnlyMe(나만 보기) 기본 값은 Public(전체 공개) |
X |
enableShare | Bool |
친구 공개 스토리인 경우 공유 설정 기본값은 "false" |
X |
androidExecParam | [String, String]? |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터 | X |
iosExecParam | [String, String]? |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터 | X |
androidMarketParams | [String, String]? |
스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터 | X |
iosMarketParams | [String, String]? |
스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터 | X |
요청 성공 시 콜백 함수로 전달되는 StoryPostResult
객체를 통해 작성된 스토리 게시물의 ID를 확인할 수 있습니다.
이름 | 타입 | 설명 |
---|---|---|
id | String |
작성된 스토리 ID |
종류별 스토리 쓰기 구현 방법과 추가 파라미터 정보는 아래에서 확인할 수 있습니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
iOS SDKpostNote() ReactiveX iOS SDK postNote() |
postNote()
API는 사진이나 웹 페이지 URL 등 다른 요소 없이 글로만 구성된 스토리를 게시할 때 사용합니다. 글 스토리 쓰기 시, 스토리 내용 텍스트를 담은 content
파라미터를 필수 전달해야 합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | O |
다음은 글 스토리 쓰기 예제입니다. 다른 파라미터는 설정하지 않고 스토리 내용만을 content
파라미터로 전달합니다.
StoryApi.shared.postNote(content:"This cafe is really awesome!" ) { (postId, error) in
if let error = error {
print(error)
}
else {
print("postNote(content:) success.")
//do something
_ = postId
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.postNote(content: "This cafe is really awesome!")
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onSuccess:{ (postId) in
print("postNote(content:) success.")
//do something
_ = postId
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
iOS SDKpostPhoto() upload() ReactiveX iOS SDK postPhoto() upload() |
postPhoto()
API는 사진과 글로 구성된 스토리를 게시할 때 사용합니다. 글 스토리 쓰기 시, 스토리에 첨부할 이미지 정보를 담은 images
파라미터를 필수 전달해야 합니다. 스토리 내용 텍스트를 담은 content
는 선택 파라미터입니다.
images
파라미터에는 이미지 파일 URL 문자열(String)을 배열(Array) 형식으로 전달해야 합니다. 만약 기기에 저장된 이미지 파일을 사용하고 싶다면 upload()
API를 사용해 카카오 서버에 업로드합니다. 요청 시 업로드할 파일은 UIImage
객체의 배열 형식으로 전달합니다. 업로드된 이미지의 URL을 String
배열로 받아 postPhoto()
파라미터로 사용할 수 있습니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | X |
images | [String] |
스토리에 들어갈 이미지들의 URL | O |
다음은 이미지 업로드 후 사진 스토리 쓰기를 요청하는 예제입니다.
// 이미지 파일 업로드
StoryApi.shared.upload([UIImage(named:"sample1"), UIImage(named:"sample2")]) {(imagePaths, error) in
if let error = error {
print(error)
}
else {
guard let imagePaths = imagePaths else {
print(NSError(domain:"com.kakao.sdk.KakaoSample", code:0, userInfo:[ NSLocalizedDescriptionKey: "Upload is not complete."]))
return
}
// 이미지 파일 업로드 성공 시 사진 스토리 쓰기 요청
StoryApi.shared.postPhoto(imagePaths: imagePaths) { (postId, error) in
if let error = error {
print(error)
}
else {
print("postPhoto(imagePaths:) success.")
//do something
_ = postId
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
// 이미지 파일 업로드
StoryApi.shared.rx.upload([UIImage(named:"sample1"), UIImage(named:"sample2")])
.flatMap({ (imagePaths) -> Single<String> in
guard let imagePaths = imagePaths else {
throw (NSError(domain:"com.kakao.sdk.KakaoSample", code:0, userInfo:[ NSLocalizedDescriptionKey: "Upload is not complete."]) as Error)
}
// 이미지 파일 업로드 성공 시 사진 스토리 쓰기 요청
return StoryApi.shared.rx.postPhoto(imagePaths:imagePaths)
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
})
.subscribe (onSuccess:{ (postId) in
print("postPhoto(imagePaths:) success.")
//do something
_ = postId
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
공통LinkInfo iOS SDK postLink() linkInfo() ReactiveX iOS SDK postLink() linkInfo() |
postLink()
API는 웹 페이지를 공유하는 스토리를 게시할 때 사용합니다. 링크 스토리 쓰기 시, 공유할 웹 페이지 정보를 담은 linkInfo
파라미터를 필수 전달해야 합니다. 스토리 내용 텍스트를 담은 content
는 선택 파라미터입니다.
파라미터 값으로 전달할LinkInfo
객체는 linkInfo()
API를 사용하여 구합니다. linkInfo()
에 공유할 웹 페이지 URL을 전달하면, 카카오 SDK가 오픈 그래프 프로토콜(Open Graph Protocol)에 따라 웹 페이지 정보를 스크랩하여 LinkInfo
객체로 반환합니다.
따라서 링크 스토리 쓰기 요청 시에는 먼저 linkInfo()
를 호출하여 공유할 웹 페이지 정보를 담은 LinkInfo
객체를 구하고, 이 요청이 성공하면 이어서 postLink()
를 호출하도록 구현하는 것을 권장합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
스토리에 들어갈 글, 2048자(char) 미만으로 제한 | X |
linkInfo | LinkInfo |
웹 페이지 스크랩 정보 | O |
다음은 웹 페이지 스크랩 후 링크 스토리 쓰기를 요청하는 예제입니다.
// 웹 페이지 스크랩
StoryApi.shared.linkInfo(url: URL(string: "https://www.youtube.com/watch?v=naytyuVj75I")!) {(linkInfo, error) in
if let error = error {
print(error)
}
else {
if let linkInfo = linkInfo {
// 링크 스토리 쓰기
StoryApi.shared.postLink(linkInfo: linkInfo) { (postId, error) in
if let error = error {
print(error)
}
else {
print("postLink(linkInfo:) success.")
//do something
_ = postId
}
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
// 웹 페이지 스크랩
StoryApi.shared.rx.linkInfo(url: URL(string: "https://www.youtube.com/watch?v=naytyuVj75I")!)
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
.flatMap({ linkInfo in
// 링크 스토리 쓰기
StoryApi.shared.rx.postLink(linkInfo: linkInfo)
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
})
.subscribe (onSuccess:{ (postId) in
print("postLink(linkInfo:) success.")
//do something
_ = postId
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
현재 로그인한 사용자의 카카오스토리에서 스토리 목록을 불러옵니다.
다음 두 가지 방법으로 스토리를 가져올 수 있습니다.
스토리 가져오기 요청 시 하나의 스토리를 요청하는지, 여러 개의 스토리를 요청하는지에 따라 전달해야 할 파라미터가 다릅니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
공통Story iOS SDK stories() ReactiveX iOS SDK stories() |
내 스토리 가져오기는 현재 로그인한 사용자의 카카오스토리에서 스토리 게시물들을 불러오는 기능입니다. stories()
API로 요청하며, 요청 성공 시 각 스토리의 구성 요소를 담은 Story
객체의 리스트를 반환합니다.
각 Story
객체는 스토리 고유 번호인 ID를 포함합니다. stories()
응답은 각 스토리의 댓글이나 반응과 같은 상세 정보를 포함하지 않으므로, 각 스토리의 상세 정보를 확인하려면 해당 스토리 ID 값을 파라미터로 전달하여 stories()
를 호출해야 합니다.
StoryApi.shared.stories {(stories, error) in
if let error = error {
print(error)
}
else {
print("stories() success.")
//do something
_ = stories
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.stories()
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onSuccess:{ (stories) in
print("stories() success.")
//do something
_ = stories
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
공통Story iOS SDK stories() ReactiveX iOS SDK stories() |
하나의 스토리를 지정해 요청합니다.
해당 스토리 id
값을 파라미터로 전달하여 stories()
를 호출해야 합니다. 특정 스토리 ID를 지정하여 요청하면 해당 스토리의 댓글을 포함한 상세 정보를 받을 수 있습니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
상세 정보를 가져올 스토리 ID | O |
StoryApi.shared.stories { [weak self] (stories, error) in
if let error = error {
print(error)
}
else {
if let story = stories?.first {
StoryApi.shared.story(id: story.id) { (story, error) in
if let error = error {
print(error)
}
else {
print("story(id:) success.")
//do something
_ = story
}
}
}
else {
print(SdkError(reason:.Unknown, message: "not exist your story."))
}
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.stories()
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
.flatMap({ (stories) -> Single<Story> in
//first element get example
if let first = stories?.first {
return StoryApi.shared.rx.story(id:first.id)
}
else {
throw SdkError(reason:.Unknown, message: "not exist your story.")
}
})
.subscribe (onSuccess:{ (story) in
print("story(id:) success.")
//do something
_ = story
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
스토리 구성 요소는 REST API 가이드 및 레퍼런스에서 확인할 수 있습니다.
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
iOS SDKdelete() ReactiveX iOS SDK delete() |
내 스토리 삭제하기는 사용자의 카카오스토리에서 요청된 ID에 해당하는 스토리를 삭제합니다. 삭제할 스토리 게시물의 ID를 알고 있어야 요청 가능하므로, 내 스토리 가져오기 또는 스토리 쓰기 요청을 통해 해당 스토리의 ID를 확인하거나, 참고할 수 있는 스토리 ID 값이 있어야 합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
삭제할 스토리 ID | O |
다음은 현재 로그인한 사용자의 모든 스토리를 불러온 뒤, 그중 첫 번째 스토리를 삭제하는 예제입니다.
StoryApi.shared.stories {(stories, error) in
if let error = error {
print(error)
}
else {
if let story = stories?.first {
StoryApi.shared.delete(story.id) { (error) in
if let error = error {
print(error)
}
else {
print("delete(_ id:) success.")
}
}
}
else {
print(SdkError(reason:.Unknown, message: "not exist your story."))
}
}
}
// Class member property
let disposeBag = DisposeBag()
StoryApi.shared.rx.stories()
.retry(when:Auth.shared.rx.incrementalAuthorizationRequired())
.flatMapCompletable({ (stories) -> Completable in
//first element delete example
if let first = stories?.first {
return StoryApi.shared.rx.delete(first.id)
}
else {
throw SdkError(reason:.Unknown, message: "not exist your story.")
}
})
.subscribe (onCompleted:{
print("delete(_ id:) success.")
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)