페이지 이동경로
  • Docs>
  • Getting Started>
  • iOS

Getting Started

iOS

This document describes what you should do to integrate the Kakao SDK for iOS (hereinafter referred to as 'iOS SDK') into your web before leveraging the Kakao APIs.

IMPORTANT

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.

Features

The iOS SDK has the following features:

  • Uses Swift.
  • Implements intuitive interface similar with the usability of REST API.
  • Adopts networking and JSON libraries such as Retrofit, and Alamofire to maximize performance.
  • Provides ReactvieX Extension that makes your code reactive and helps you to program more effectively when you use RxSwift.
  • Adopts a default browser (CustomTabs) instead of WebView to enhance security.

Requirements

Here are what you need to use the iOS SDK:

  • Xcode 11.0 or higher
  • iOS 11.0 or higher
  • iOS Deployment Target 11.0 or higher
  • Swift 5.0 or higher
External library dependency

The iOS SDK uses the following libraries that are automatically installed when installing the iOS SDK:

Install SDK

You can install the Kakao SDK either by:

Using CocoaPods

  1. Install or update CocoaPods to the latest version. CocoaPods 1.8 or higher is required.
  2. Add the entire modules of the Kakao SDK or the desired modules in the Podfile in your project as below. If you add all modules, you must complete the Cocoapods settings for picker.
  3. In Terminal, go to your project's root folder and run pod install.
  4. Open .xcworkspace file to work on your project.
Swift
RxSwift
# Add all modules
pod 'KakaoSDK'

# or

# Add the desired modules
pod 'KakaoSDKCommon'  # Common module that contains essential elements
pod 'KakaoSDKAuth'  # Authentication
pod 'KakaoSDKUser'  # Kakao Login, User
pod 'KakaoSDKTalk'  # Kakao Talk Social, Kakao Talk messaging
pod 'KakaoSDKFriend' # Friend picker, 'Cocoapods settings for picker' is required.
pod 'KakaoSDKStory'  # Kakao Story
pod 'KakaoSDKShare'  # Kakao Talk sharing
pod 'KakaoSDKTemplate'  # Message default template
pod 'KakaoSDKNavi'  # Kakao Navi
# Add all modules
pod 'RxKakaoSDK'

# or

# Add the desired modules
pod 'RxKakaoSDKCommon'  # Common module that contains essential elements
pod 'RxKakaoSDKAuth'  # Authentication
pod 'RxKakaoSDKUser'  # Kakao Login, User
pod 'RxKakaoSDKTalk'  # Kakao Talk Social, Kakao Talk messaging
pod 'RxKakaoSDKFriend' # Friend picker, 'Cocoapods settings for picker' is required.
pod 'RxKakaoSDKStory'  # Kakao Story
pod 'RxKakaoSDKShare'  # Kakao Talk sharing
Module dependency

Some modules in the Kakao SDK are dependent on another module. If you add the Common or Auth module, its subordinate modules are automatically added together.

Kakao SDK module dependency tree
Cocoapods settings for picker

If you want to implement the Friend picker or add all modules including the Friend picker, you must add the KakaoSDKFriend or RxKakaoSDKFriend modules. These modules include the built binary framework unlike other modules, you must add the following code snippet at the bottom of your Podfile. Afterthat, run pod install to apply the changes.

post_install do |installer|
  installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
  end
end

Using Swift Package Manager

In iOS SDK 2.8.5 or higher, you can simply install the iOS SDK by using Swift Package Manager (SPM). The SPM is a tool used to manage the distribution of source code and built in Xcode 11 or higher. For more details, refer to Adding Package Dependencies to Your App.

IMPORTANT

You cannot install the KakaoSDKFriend and RxKakaoSDKFriend modules intended for the Friend picker by using the Swift Package Manager. To implement the Friend picker in your service, install iOS SDK by using CocoaPods. If you cannot install the module related to the Friend picker with CocoaPods, ask us in DevTalk.

How to install iOS SDK by using Swift Package Manager

In your Xcode,

  1. Select [File] > [Add Packages] > [Add Swift Packages].
    If the menu is not displayed, go to your project in [PROJECT] > [Package Dependencies] and click [+] under 'Packages'.
  2. Input the GitHub repository URL of the iOS SDK you want to add in the Search box:
    - iOS SDK: https://github.com/kakao/kakao-ios-sdk.git
    - ReactiveX iOS SDK: https://github.com/kakao/kakao-ios-sdk-rx
  3. After selecting the 'kakao-ios-sdk' or 'kakao-ios-sdk-rx' package, set the version, branch, or commit hash in 'Dependency Rule'. If you specify the version, the minimum version should be 2.8.5 or higher. Then, click [Add package].
  4. Choose the packages that you want to use, and then click [Add package].
Package name Description
KakaoSDK / RxKakaoSDK Select this library if you want to add all dependencies.
KakaoSDKAuth / RxKakaoSDKAuth Add this library for authentication or calling the Checking token presence API.
KakaoSDKCommon / RxKakaoSDKCommon Add this library for the common module that contains essential elements.
KakaoSDKCommonCore / RxKakaoSDKCommonCore Add this library for the common module except for the network function.
KakaoSDKUser / RxKakaoSDKUser Add this library for Kakao Login.
KakaoSDKStory / RxKakaoSDKStory Add this library for Kakao Story API.
KakaoSDKTemplate
(Not supported for ReactiveX iOS SDK)
Add this library for configuring a default template when calling the Kakao Talk sharing or Kakao Talk messaging APIs.
KakaoSDKShare / RxKakaoSDKShare Add this library for Kakao Talk sharing API.
KakaoSDKTalk / RxKakaoSDKTalk Add this library for Kakao Talk messaging API and Kakao Talk Social API.
KakaoSDKNavi
(Not supported for ReactiveX iOS SDK)
Add this library for Kakao Navi API.

To check if libraries are successfully added, select your project in [TARGETS], and then check if the libraries you selected are listed under 'Frameworks, Libraries, and Embedded Content'.

Libraries added by using Swift Package Manager in Xcode

Configure build settings

Step 1. Register Allowlist

Since iOS 9.0, iOS only allows apps registered in Allowlist to enhance security. Thus, you must register 'Allowlist' to allow your app to run Kakao apps, such as Kakao Talk, Kakao Story, Kakao Navi, and so on.

To register Allowlist:

How to register Allowlist in Xcode
  1. Add the LSApplicationQueriesSchemes key with an array type in the plist file.
  2. Add the Items to the LSApplicationQueriesSchemes key, and set them to "kakaokompassauth" and "kakaolink".
Step 2. Set URL Scheme

You need to set 'URL Schemes' to use the Custom URL Scheme. The Custom URL Scheme is used to run an app through a Kakao Talk message or Kakao Story post, or to go back to your app after logging in through Kakao Talk or Kakao Account.

How to set custom URL scheme in Xcode
  1. Go to [Info] > [URL Type] > [URL Schemes].
  2. Input your Native app key in kakao${YOUR_NATIVE_APP_KEY} format. For example, if your Native app key is 123456789, set 'URL Schemes' to "kakao123456789".

This setting above is used to create the Custom URL Scheme in the following format.

  • Kakao Login: kakao${NATIVE_APP_KEY}://oauth
  • Kakao Talk Sharing: kakao${NATIVE_APP_KEY}://kakaolink
  • Kakao Story: kakao${NATIVE_APP_KEY}://kakaostory

Or you can add the keys manaully in the Info.plst file as follows:

<key>KAKAO_APP_KEY</key>
<string>0123456789abcdefghijklmn</string>


<key>LSApplicationQueriesSchemes</key>
<array>
    <string>kakao${YOUR_NATIVE_APP_KEY}</string>
    <string>kakaokompassauth</string>
    <string>storykompassauth</string>
    <string>kakaolink</string>
    <string>storylink</string>
</array>
Change key for allowlist

For Xcode 14 or above, the key for allowlist may be automatically converted from the current key LSApplicationQueriesSchemes to the new key Queried URL Schemes. The Info.plist file internally uses the existing key. If you modify the Info.plist file directly, use the current key.

Initialize SDK

After installing the SDK, you need to initialize the SDK for the initial setup.

To initialize the iOS SDK,

  1. Add the following import statement in AppDelegate.swift.
  2. Initialize the KakaoSDK instance by adding the initSDK method with your Native app key in the application method of AppDelegate instance.
    If you use SwiftUI App Life Cycle, add initSDK() inside the ${PROJECT_NAME}App class created with the SwiftUI App project, instead of AppDelegate.swift.
Swift
RxSwift
SwiftUI App
import KakaoSDKCommon

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

  ...
  KakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
  ...

}
import RxKakaoSDKCommon

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

  ...
  RxKakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
  ...

}
import SwiftUI
import KakaoSDKCommon
import KakaoSDKAuth
...

@main
struct SwiftUI_testApp: App {

    ...
    init() {
        // Initialize Kakao SDK.
        KakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
    }
    ...

}
IMPORTANT

In iOS SDK 2.8.3, the class names, used for initialization, have been changed: - KakaoSDKCommon → KakaoSDK - RxKakaoSDKCommon → RxKakaoSDK

Migrate v1 to v2

You can migrate the Legacy iOS SDK (version 1.x.x) to the latest version of iOS SDK (version 2.x.x) using this migration guide.

Initialization

The Legacy iOS SDK requires you to configure a project and import the SDK, and then call APIs. On the other hand, the latest iOS SDK requires explicit initialization, so you must have your app launched and initialized first and then call an API.

Notice when using token-based APIs

The token-based APIs refer to the APIs that require Kakao Login with which you can get an access token.

With the Legacy iOS SDK, you need to use KOSessionTask to call an API that passes an access token issued through Kakao Login. When using the Legacy iOS SDK, the session changes according to a user's login status, and some APIs can be called only when a session is open.

APIs in the latest iOS SDK are separated by modules so that you can use the desired modules only. However, for the API that passes an access token through Kakao Login, you must install the Kakao Login module along with the desired module and implement the login function.

Considering the structural difference, you must check if the module you want to use is dependent on Kakao Login. For the token-based APIs that require Kakao Login, the development guide for each API describes the required modules and whether to implement Kakao Login.

API comparison by version

Common
  • Latest SDK: Call the initSDK() method that initializes the SDK through KakaoSDK.
Name Legacy SDK SDK
Initializing Kakao SDK - initSDK()
IMPORTANT

In iOS SDK 2.8.3, the class names, used for initialization, have been changed: - KakaoSDKCommon → KakaoSDK - RxKakaoSDKCommon → RxKakaoSDK

Kakao Login
Name Legacy SDK SDK
Checking if Kakao Talk is installed - isKakaoTalkLoginAvailable()
Kakao Login openWithCompletionHandler -
Login with Kakao Talk - loginWithKakaoTalk()
Login with Kakao Account - loginWithKakaoAccount()
Checking token presence isOpen hasToken()
Logout logoutAndCloseWithCompletionHandler logout()
Unlink unlinkTaskWithCompletionHandler unlink()
Retrieving token information accessTokenInfoTaskWithCompletionHandler accessTokenInfo()
Retrieving user information userMeTaskWithCompletion me()
Retrieving shipping address shippingAddressTask shippingAddresses()
Storing user information profileUpdateTaskWithProperties:properties: updateProfile(properties:)
Requesting additional consent updateScopes:needsAgreementScopes: loginWithKakaoTalk(scopes:)
loginWithKakaoAccount(scopes:)
Retrieving user agreed terms serviceTermsTask serviceTerms()
Getting consent to desired term open loginWithKakaoTalk(serviceTerms:)
loginWithKakaoAccount(serviceTerms:)
Kakao Talk Social
  • Legacy SDK: Call the Kakao Talk Social APIs through KOSessionTask.
  • Latest SDK: Call the Kakao Talk Social APIs through TalkApi in the KakaoSDKTalk module.
Name Legacy SDK SDK
Retrieving Kakao Talk profile talkProfileTaskWithCompletionHandler profile()
Retrieving list of friends appFriendsWithContext:context: friends()
Message: Kakao Talk Sharing
  • Legacy SDK:
    • Call the Kakao Talk sharing APIs through KLKTalkLinkCenter for Sending message API.
    • Call the Image API through KLKImageStorage.
    • If Kakao Talk is not installed on a user's device, a message is internally sent through a WebView.
  • Latest SDK:
    • Call the Kakao Talk sharing APIs through ShareApi in the KakaoSDKShare module.
    • If Kakao Talk is not installed on a user's device, implement a process to share URI through a WebView or a default browser.
IMPORTANT

In iOS SDK 2.11.0, the names of the module, classes, and methods related to Kakao Talk sharing have been changed due to the change of its service name. To see more detailed changes, see Version history.

Name Legacy SDK SDK
Checking if Kakao Talk is installed - isKakaoTalkSharingAvailable()
Sending with default template sendDefaultWithTemplate:template: shareDefault(templatable:)
Sending with custom template sendCustomWithTemplateId:templateId:templateArgs: shareCustom(templateId:templateArgs:)
Sending a scrap message sendScrapWithURL: url:templateId: shareScrap(requestUrl:templateId:)
Uploading an image uploadWithImage:sourceImage: imageUpload(image:)
Scraping an image scrapWithImageURL:imageURL: imageScrap(imageUrl:)
Deleting an image deleteWithImageURL:imageURL: -
Message: Kakao Talk Messaging
  • Legacy SDK: Call the Kakao Talk APIs through KOSessionTask.
  • Latest SDK: Call the Kakao Talk APIs through TalkApi in the KakaoSDKTalk module.
Name Legacy SDK SDK
Sending me with default template talkMemoSendTaskWithTemplate:template: sendDefaultMemo(templatable:)
Sending me with custom template talkMemoSendTaskWithTemplateId:templateId: sendCustomMemo(templateId:)
Sending me a scrap message talkMemoSendTaskWithURL:url:templateId: sendScrapMemo(requestUrl:templateId:)
Sending friends with default template sendMessageToFriendsWithTemplate:template: sendDefaultMessage(templatable:receiverUuids:)
Sending friends with custom template sendMessageToFriendsTaskWithTemplateId:templateId: sendCustomMessage(templateId:receiverUuids:)
Sending friends a scrap message sendMessageToFriendsTaskWithURL:url:templateId: sendScrapMessage(requestUrl:templateId:receiverUuids:)
Kakao Story
  • Legacy SDK: Call the Kakao Story APIs through KOSessionTask.
  • Latest SDK: Call the Kakao Story APIs through StoryApi in the KakaoSDKStory module.
Name Legacy SDK SDK
Validating Kakao Story user storyIsStoryUserTaskWithCompletionHandler isStoryUser()
Retrieving Kakao Talk profile storyProfileTaskWithCompletionHandler profile()
Posting text story storyPostNoteTaskWithContent:content: postNote(content:)
Posting photo story storyPostPhotoTaskWithImageUrls:content:images: postPhoto(content:images:)
Posting link story storyPostLinkTaskWithLinkInfo:link: postLink(content:linkInfo:)
Retrieving specified story storyGetMyStoryTaskWithMyStoryId:myStoryId: story(id:)
Retrieving multiple stories storyGetMyStoriesTaskWithLastMyStoryId:lastMyStoryId: stories()
Deleting story storyDeleteMyStoryTaskWithMyStoryId:myStoryId: delete(id:)
Uploading image storyMultiImagesUploadTaskWithImages:chosenImages: upload(images:)
Scraping web page storyGetLinkInfoTaskWithUrl:url: linkInfo(url:)
Kakao Talk Channel
  • Legacy SDK:
    • Call the Adding Kakao Talk Channel and Kakao Talk Channel chat APIs through KPFPlusFriend.
    • Call the Checking Kakao Talk Channel relationship API through KOSessionTask.
  • Latest SDK:
    • Call the Kakao Talk Channel APIs through TalkApi in the KakaoSDKTalk module.
    • Call the Checking Kakao Talk Channel relationship API after implementing Kakao Login.
Name Legacy SDK SDK
Adding Kakao Talk Channel addFriend:plusFriendId: makeUrlForAddChannel(channelPublicId:)
Starting Kakao Talk Channel chat chat:plusFriendId: makeUrlForChannelChat(channelPublicId:)
Checking Kakao Talk Channel relationship talkPlusFriendsTask channels()
Kakao Navi
  • Legacy SDK:
    • Call the Navi APIs through KNVNaviLauncher.
    • Use a class builder to set parameters.
  • Latest SDK:
    • Call the Navi APIs through KakaoSDKNavi in the NaviApi module.
    • Define the constructor for each class to set parameters.
Name Legacy SDK SDK
Navigation navigateWithParams:params: navigateUrl(destination:)
Getting URL for navigation - Deprecated webNavigateUrl(destination:)
Sharing location shareDestinationWithParams:params: shareUrl(destination:)
Setting conditions for navigation locationWithName NaviOption()
Setting conditions for destination information paramsWithDestination NaviLocation()
Push Notification
  • Legacy SDK: Call the Push Notification API through KOSessionTask.
  • Latest SDK: Not support Push Notification API. You can send the push notifications only using REST API.
Name Legacy SDK SDK
Registering push token pushRegisterDeviceWithToken:deviceToken: -
Retrieving push token pushGetTokensTaskWithCompletionHandler -
Deleting push token pushDeregisterDeviceWithToken:deviceToken: -

See more

Legacy

To see how to use the Legacy Kakao SDK for iOS, see Getting Started 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.