페이지 이동경로
  • Docs>
  • Kakao Story>
  • iOS

Kakao Story

iOS

This document describes how to integrate Kakao Story APIs into your service with the Kakao SDK for iOS ("iOS SDK").

Before you begin

Add modules

To use Kakao Story, you need to add the KakaoSDKStory or RxKakaoSDKStory in the Podfile by referring to Install SDK. To use Kakao Story APIs that require Kakao Login, you must also add the Kakao Login module, KakaoSDKUser and KakaoSDKAuth.

After that, add the import statements as follows.

Swift
RxSwift
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKStory
import KakaoSDKAuth
import RxKakaoSDKAuth

import KakaoSDKUser
import RxKakaoSDKUser

import KakaoSDKStory
import RxKakaoSDKStory

Validate Kakao Story user

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required -

To check if the user who is currently logged in is using Kakao Story, call the isStoryUser() method in the StoryApi class.

Sample

Swift
RxSwift
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)

If true is returned, the user is using Kakao Story. If the user is not using Kakao Story, false is returned so that you can take action to prevent an error that occurs when calling Kakao Story APIs for the user.

Users can set their desired profile nicknames and images for Kakao Story, Kakao Talk, and Kakao Account respectively. Thus, profile information retrieved through this API is different from the ones obtained through the Retrieving user information or Retrieving Kakao Talk profile API.

Retrieve Kakao Story profile

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Profile Info(nickname/profile image)
Nickname
Profile image
KakaoStory Profile URL

To retrieve the Kakao Story profile information of the user who is currently logged in, call the profile() method in the StoryApi class.

Sample

Swift
RxSwift
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)

profile() returns Kakao Story profile information through the StoryProfile object.

The profile information retrieved through this API may be different from the profiles obtained through the Retrieving user information API or Retrieving Kakao Talk profile API because users can set their profile nicknames and images respectively for Kakao Story, Kakao Talk, and Kakao Account.

StoryProfile
Name Type Description Required
nickName String Kakao Story nickname.

Required user consent: Profile Info(nickname/profile image) or Nickname
X
profileImageUrl String Kakao Story profile image URL.

Required user consent: Profile Info(nickname/profile image) or Profile image
X
thumbnailUrl URL Kakao Story thumbnail profile image URL.

Required user consent: Profile Info(nickname/profile image) or Profile image
X
bgImageUrl URL Kakao Story background image URL.

Required user consent: Profile Info(nickname/profile image) or Profile image
X
permalink URL Kakao Story profile URL.

Required user consent: KakaoStory profile URL

NOTE: From June 1, 2021, only when a user consents to 'KakaoStory profile URL(story_permalink)', the Retrieving Kakao Story profile API returns 'permalink' in the response. For more details, see Notice.
X
birthday String Birthday registered in Kakao Story in MMdd format.

Required user consent: Birthday
X
birthdayType BirthdayType - Solar: Solar birthday.
- Lunar: Lunar birthday.

Required user consent: Birthday
X

Post story

To post a new story on Kakao Story of the user who is currently logged in, call one of the following methods depending on the story type — text, photo, or link. You also must pass arguments for the corresponding story type.

Story types

Type Description Method
Text Story with text only. postNote()
Photo Story with text and photos. postPhoto()
Link Story with text and the information obtained by scrapping a web page. postLink()

Posting text story

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Publish posts in KakaoStory

To post a text story without any photo or web page URL, call the postNote() method. You must also pass the content parameter that contains the text you want to input.

Parameter

Name Type Description Required
content String Text to be input in the story. O
permission Permission Audience for the story.
- Public: Open to all.
- Friend: Open to only friends.
- OnlyMe: Open to only me (Private).
(Default: Public)
X
enableShare Bool Whether to share the story when permission is set to Friend (Friends only).
(Default: false)
X
androidExecParam [String, String]? Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story. X
iosExecParam [String, String]? Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story. X
androidMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to an open market from Kakao Story. X
iosMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story. X

Sample

Swift
RxSwift
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)

Posting photo story

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Publish posts in KakaoStory

To post a story with photos,

  1. To use the image files saved on a local device, you need to upload them to the Kakao server first. Call the upload() method by passing images as a list of strings. upload() returns the list of the uploaded image URLs.
  2. Call the postPhoto() method by passing images that is obtained through upload().

Parameter

Name Type Description Required
imagePaths [String] List of image URLs to be attached to a story. O
content String Text to be input in the story.
Up to 2048 characters are allowed.
X
permission Permission Audience for the story.
- Public: Open to all.
- Friend: Open to only friends.
- OnlyMe: Open to only me (Private).
(Default: Public)
X
enableShare Bool Whether to share the story when permission is set to Friend (Friends only).
(Default: false)
X
androidExecParam [String, String]? Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story. X
iosExecParam [String, String]? Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story. X
androidMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to an open market from Kakao Story. X
iosMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story. X

Sample

The following code snippet shows the algorithm for uploading images and posting a photo story with the uploaded images.

Swift
RxSwift
// Uploading image
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
        }

        // If uploading image is successful, request to write Photo story.
        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()

// Uploading image
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)
        }
        // If uploading image is successful, request to write Photo story.
        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)

Posting link story

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Publish posts in KakaoStory

To post a story with the information obtained by scrapping a web page,

  1. To obtain the web page information to be shared in a story, call the linkInfo() method by passing url with a string type. linkInfo() returns the LinkInfo object that contains the web page information scraped based on the Open Graph Protocol.
  2. Call the postLink() method by passing LinkInfo that is obtained through linkInfo().

Parameter

Name Type Description Required
linkInfo LinkInfo The web page information. O
content String Text to be input in the story.
Up to 2048 characters are allowed.
X
permission Permission Audience for the story.
- Public: Open to all.
- Friend: Open to only friends.
- OnlyMe: Open to only me (Private).
(Default: Public)
X
enableShare Bool Whether to share the story when permission is set to Friend (Friends only).
(Default: false)
X
androidExecParam [String, String]? Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story. X
iosExecParam [String, String]? Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story. X
androidMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to an open market from Kakao Story. X
iosMarketParam [String, String]? Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story. X
LinkInfo
Name Type Description Required
url String URL of of the scraped web page.
In the case of a shortened link, the resolved URL.
X
requestedUrl String Original URL of the scraped web page.
In the case of a shortened link, the original URL before resolving it.
X
host String Site domain of the scraped web page. X
title String Title of the scraped web page. X
images [URL] List of representative images on the scraped web page.
Up to three images are allowed.
X
description String Description of the scraped web page. X
section String Section information of the scraped web page. X
type String Content type of the scraped web page such as video, music, book, article, profile, and website. X

Sample

The following code snippet shows the algorithm for scraping web page and posting a link story with the scraped web page information.

Swift
RxSwift
// Scraping web page 
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 {
            // Posting link story
            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()

// Scraping web page 
StoryApi.shared.rx.linkInfo(url: URL(string: "https://www.youtube.com/watch?v=naytyuVj75I")!)
    .retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
    .flatMap({ linkInfo in
        // Posting link story
        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)

The methods to post a story return the StoryPostResult object.

StoryPostResult
Name Type Description
id String ID of the uploaded story.

Retrieve my story

Retrieving multiple stories

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Read access to KakaoStory posts

To retrieve story information on Kakao Story of the user currently logged in, call the stories() method in the StoryApi class.

Sample

Swift
RxSwift
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)

Retrieving a specific story

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Read access to KakaoStory posts

To retrieve the detailed information of a specific story, call the story() method by passing id included in the Story object. Then, you can get detailed information including comments and reactions.

Parameter

Name Type Description Required
id String Story ID to be retrieved. O

Sample

Swift
RxSwift
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)

story() returns the Story object, and stories() returns a list of Story objects that contains each story information. stories() does not return comments and likes that are only returned through story().

Story
Name Type Description Required
id String Story ID. O
url String Story URL. O
content String Story content. O
createdAt Date The time when the story is posted in RFC3339 internet date/time format. O
mediaType MediaType Story type.
One of Photo (photo), Note (text), NotSupported (not supported).
X
media [StoryMedia] URLs by image size.
Only returned if mediaType is Photo.
X
commentCount Int Number of comments. O
likeCount Int Number of moods that the user's friends left. O
permission Permission Audience for the story.
One of Public(Open to all), Friend(Friends only), OnlyMe(Private)
X
comments [StoryComment] List of comments consisting of text (content) and writer (the user who left the comment).
NOTE: Not returned if stories() is called.
X
likes [StoryLike] List of moods consisting of emotion (mood emoji) and actor (the user who left the mood).
NOTE: Not returned if stories() is called.
X
StoryMedia
Name Type Description Required
large URL URL of the image with a size of 720x960 pixels. X
medium URL URL of the image with a size of 240x320 pixels. X
original URL URL of the original image. X
small URL URL of the image with a size of 160x213 pixels. X
xlarge URL URL of the image with a size of 1280x1706 pixels. X
StoryComment
Name Type Description Required
text String Comment content. O
writer StoryActor User who left a comment. O
StoryLike
Name Type Description Required
emotion Emotion Mood left in a story.
One of Like, Cool, Happy, Sad, CheerUp.
O
actor StoryActor User who left the mood. O
StoryActor
Name Type Description Required
displayName String User's Kakao Story nickname. O
profileThumbnailUrl URL User's Kakao Story profile thumbnail URL. X

Delete story

Basic information
Permission Prerequisite Kakao Login User consent
- Register platforms
Activate Kakao Login
Manage consent items
Required Required:
Read access to KakaoStory posts

To delete a story on a user's Kakao Story, call the delete() method in the StoryApi class. You must pass id to specify the story ID you want to delete.

Parameter

Name Type Description Required
id String Story ID to be deleted.
If you do not know the story ID, call the Retrieving my story API.
O

Sample

The following code snippet shows the algorithm for retrieving all stories of the user and deleting the first story.

Swift
RxSwift
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.")        
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

See more