kakao developers

iOS

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

Tag used in this document

Before you begin

Register iOS Platform

To use the iOS SDK, you must register the iOS platform in advance. Go to [My Application] > [Platform] and register the iOS platform by specifying the Bundle ID. If not, an error may occur.

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.

import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKStory

import KakaoSDKAuth
import RxKakaoSDKAuth

import KakaoSDKUser
import RxKakaoSDKUser

import KakaoSDKStory
import RxKakaoSDKStory

Validate Kakao Story user Login required

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

Sample

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)

Return data

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 Login required Consent required

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

Sample

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)

Return data

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

Post story Login required Consent required

To use this API,

• You must enable the 'Publish posts in KakaoStory' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the scope. Otherwise, an error occurs.

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

Posting text story

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

Sample

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

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

Sample

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

// 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

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

LinkInfo

Sample

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

// 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)

Return data

The methods to post a story return the StoryPostResult object.

StoryPostResult

Retrieve my story Login requiredConsent required

To use this API,

• You must enable the 'Read access to KakaoStory posts' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the 'Read access to KakaoStory posts' scope. Otherwise, an error occurs.

Retrieving multiple stories

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

Sample

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

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

Sample

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)

Return data

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

StoryMedia

StoryComments

StoryLike

StoryActor

Delete story Login required

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

Sample

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

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

• Download iOS SDK
• API Reference for iOS →
• API Reference for ReactiveX iOS →

Legacy

To see how to integrate Kakao Story using the Legacy Kakao SDK for iOS, see Kakao Story guide for Legacy iOS SDK.

It is highly recommended to migrate to the new version of iOS SDK as soon as possible because the Legacy version may not be supported anymore.