이 문서는 Kakao SDK for iOS(이하 iOS SDK) 사용법을 설명합니다.
iOS SDK를 사용하기 위한 최소 요구 사양은 아래와 같습니다.
iOS SDK는 다음과 같은 외부 라이브러리를 사용합니다. iOS SDK 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.
Cocoapods 또는 Swift Package Manager(이하 SPM) 를 통해 iOS SDK를 설치할 수 있습니다.
Cocoapods를 이용하여 iOS SDK를 설치할 수 있습니다. Cocoapods 1.8 버전 이상이 필요합니다.
프로젝트의 Podfile에 Kakao SDK를 전체 또는 모듈(Module)별로 추가합니다.
# 전체 추가
pod 'KakaoSDK'
# or
# 필요한 모듈 추가
pod 'KakaoSDKCommon' # 필수 요소를 담은 공통 모듈
pod 'KakaoSDKAuth' # 사용자 인증
pod 'KakaoSDKUser' # 카카오 로그인, 사용자 관리
pod 'KakaoSDKTalk' # 친구, 메시지(카카오톡)
pod 'KakaoSDKStory' # 카카오스토리
pod 'KakaoSDKShare' # 메시지(카카오톡 공유)
pod 'KakaoSDKTemplate' # 메시지 템플릿
pod 'KakaoSDKNavi' # 카카오내비
pod 'KakaoSDKFriend' # 카카오톡 소셜 피커, 리소스 번들 파일 포함
# 전체 추가
pod 'RxKakaoSDK'
# or
# 필요한 모듈 추가
pod 'RxKakaoSDKCommon' # 필수 요소를 담은 공통 모듈
pod 'RxKakaoSDKAuth' # 카카오 로그인
pod 'RxKakaoSDKUser' # 사용자 관리
pod 'RxKakaoSDKTalk' # 친구, 메시지(카카오톡)
pod 'RxKakaoSDKStory' # 카카오스토리
pod 'RxKakaoSDKShare' # 메시지(카카오톡 공유)
pod 'RxKakaoSDKTemplate' # 메시지 템플릿
pod 'RxKakaoSDKNavi' # 카카오내비
pod 'RxKakaoSDKFriend' # 카카오톡 소셜 피커, 리소스 번들 파일 포함
iOS SDK가 제공하는 모듈 중, 피커 모듈의 경우 리소스 번들 파일을 포함합니다. Cocoapods를 통해 iOS SDK를 전체 설치하거나 피커 모듈을 포함해 설치할 경우, Podfile 하단에 아래 내용을 추가해야 합니다.
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
Xcode에서 SPM을 통해 iOS SDK를 설치하려면 다음 순서에 따라 설치를 진행합니다.
KakaoSDKFriend, RxKakaoSDKFriend 모듈은 SPM을 통해 설치할 수 없습니다. Cocoapods를 통한 설치가 불가능한 경우 데브톡으로 문의합니다.
➊[Project Target] > ➋[Package Dependencies] > ➌[Packages] 메뉴의 [+] 버튼을 눌러 패키지 추가 화면을 띄웁니다.
패키지 추가 화면 우측 상단의 ➍검색창에 설치할 iOS SDK의 레포지토리(Repository) URL를 입력해 검색합니다. iOS SDK와 ReactiveX iOS SDK의 레포지토리 URL은 각각 다음과 같습니다.
SDK | Repository Name | Repository URL |
---|---|---|
iOS SDK | kakao-ios-sdk |
https://github.com/kakao/kakao-ios-sdk |
ReactiveX iOS SDK | kakao-ios-sdk-rx |
https://github.com/kakao/kakao-ios-sdk-rx |
검색된 레포지토리 이름이 올바른지 확인한 후, ➎[Dependency Rule]을 브랜치(Branch)로 선택합니다. 브랜치 이름을 master
로 입력하고 ➏[Add Packages] 버튼을 누릅니다.
[Dependency Rule] 설정을 통해 iOS SDK의 특정 버전을 지정하여 설치할 수 있습니다. 단, SPM을 통한 설치는 2.8.5 이상 버전에서만 제공되므로, 그 이하 버전은 지정 설치가 불가능합니다.
설치할 수 있는 패키지 목록 화면이 나타납니다. ➐[Package Product] 목록에서 필요한 모듈에 체크하고 ➑[Add Packages] 버튼을 눌러 설치합니다.
아래는 모듈 정보입니다. 각 모듈은 의존하는 모듈을 자동으로 함께 설치하므로, 필요한 모듈만 체크하여 설치해도 SDK가 정상 동작합니다.
Module | Description |
---|---|
KakaoSDK | 모든 모듈 전체 설치 |
KakaoSDKCommon | Kakao SDK 공통 모듈 |
KakaoSDKCommonCore | 네트워크 기능이 제외된 공통 모듈 |
KakaoSDKAuth | 사용자 인증 및 토큰 관리 모듈 |
KakaoSDKUser | 카카오 로그인 모듈 |
KakaoSDKShare | 카카오톡 공유 모듈 |
KakaoSDKTalk | 카카오톡 소셜, 카카오톡 메시지 모듈 |
KakaoSDKTemplate | 카카오톡 공유, 카카오톡 메시지에 사용되는 메시지 템플릿 모듈 |
KakaoSDKNavi | 카카오내비 모듈 |
KakaoSDKStory | 카카오스토리 모듈 |
Module | Description |
---|---|
RxKakaoSDK | 모든 모듈 전체 설치 |
RxKakaoSDKCommon | Kakao SDK 공통 모듈 |
RxKakaoSDKCommonCore | 네트워크 기능이 제외된 공통 모듈 |
RxKakaoSDKAuth | 사용자 인증 및 토큰 관리 모듈 |
RxKakaoSDKUser | 카카오 로그인 모듈 |
RxKakaoSDKShare | 카카오톡 공유 모듈 |
RxKakaoSDKTalk | 카카오톡 소셜, 카카오톡 메시지 모듈 |
RxKakaoSDKStory | 카카오스토리 모듈 |
설치된 iOS SDK는 아래와 같이 [Packages] 메뉴에서 확인할 수 있습니다.
iOS SDK는 타겟별로 각각 설치해야 합니다. 테스트 앱에도 iOS SDK를 설치하려면 Step 3의 모듈 선택 시 [Add to Target]을 테스트 앱으로 설정합니다.
카카오톡 공유 모듈명이 2.11.0 버전부터 변경되었습니다. 아래 내용과 공지사항을 참고합니다. - 2.11.0 미만 버전: KakaoSDKLink, RxKakaoSDKLink - 2.11.0 이상 버전: KakaoSDKShare, RxKakaoSDKShare
Kakao SDK의 일부 모듈은 다른 모듈에 의존성이 있으며, 각 모듈은 설치 시 의존하는 모듈을 자동으로 함께 설치합니다. 모듈간 의존성 구조는 아래 이미지를 참고합니다.
[내 애플리케이션] > [플랫폼]에서 iOS 플랫폼 정보를 입력합니다. 이 설정은 iOS SDK를 통해 카카오 API를 사용하려면 필수입니다. 자세한 안내는 플랫폼 등록을 참고합니다.
iOS 9.0 이상에서 iOS SDK를 통해 카카오톡이나 카카오스토리, 카카오내비 등 애플리케이션(이하 앱)을 실행시키는 기능을 이용하려면 Info.plist 파일에 앱 실행 허용 목록(Allowlist)을 설정해야 합니다. 이 설정은 사용자 정보 보호를 위한 OS 정책에 따라 필요한 것으로, 자세한 내용은 Privacy and Your App을 참고합니다.
[Info] > [Custom iOS Target Properties]에 Array 타입 키(Key)인 LSApplicationQueriesSchemes
를 추가하고, 해당 키의 [Item]으로 커스텀 URL 스킴에 사용할 값인 "kakaokompassauth", "kakaolink"를 추가합니다.
위 설정은 Info.plist 파일을 직접 수정하여 적용할 수도 있습니다. 상세한 설정 값은 아래 예제를 참고합니다.
<key>LSApplicationQueriesSchemes</key>
<array>
<!-- 카카오톡으로 로그인 -->
<string>kakaokompassauth</string>
<!-- 카카오톡 공유 -->
<string>kakaolink</string>
</array>
Xcode 14 이상일 경우, 앱 실행 허용 목록 설정을 위한 키가 LSApplicationQueriesSchemes
에서 Queried URL Schemes
로 자동 변환될 수 있습니다. Info.plist 파일 내부에서는 기존 키를 사용하므로, 해당 파일을 직접 수정할 경우에는 기존 키를 사용합니다.
카카오계정을 통한 인증과 카카오톡 메시지를 통한 앱 실행을 위해 [URL Schemes] 설정을 합니다. [Info] > [URL Types] > [URL Schemes] 항목에 네이티브 앱 키(Native App Key)를 kakao${NATIVE_APP_KEY}
형식으로 등록합니다. 예를 들어 네이티브 앱 키가 "123456789"라면 [URL Schemes]에 "kakao123456789"를 입력합니다.
이 설정은 커스텀 URL 스킴 생성 시 사용됩니다. 커스텀 URL 스킴은 카카오톡으로 로그인 후 서비스 앱으로 돌아오거나, 카카오톡 공유 메시지 또는 카카오스토리 게시물을 통해 앱을 실행할 때 사용되며 각각 다음과 같은 형식입니다.
kakao${NATIVE_APP_KEY}://oauth
kakao${NATIVE_APP_KEY}://kakaolink
kakao${NATIVE_APP_KEY}://kakaostory
iOS 앱에서 iOS SDK를 사용하려면 iOS SDK 파일을 아래와 같이 임포트(import)해야 합니다. 또한 네이티브 앱 키를 사용해 iOS SDK를 초기화하는 과정이 필요합니다. AppDelegate.swift에 Kakao SDK를 초기화하는 코드를 추가합니다.
SwiftUI App Life Cycle 사용 시에는 프로젝트와 함께 생성되는 ${PROJECT_NAME}App 클래스가 AppDelegate.swift를 대신하므로, 해당 클래스 내부에 Kakao SDK 초기화 코드를 추가합니다.
아래 예제를 참고합니다.
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() {
// Kakao SDK 초기화
KakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
}
...
}
iOS SDK 2.8.3 버전부터 SDK 초기화에 사용하는 클래스의 이름이 변경되었습니다.
- KakaoSDKCommon → KakaoSDK
- RxKakaoSDKCommon → RxKakaoSDK
다음은 iOS SDK v1(2.0.0 미만 버전)에서 iOS SDK v2로 업그레이드하는 사용자를 위한 참고 정보입니다.
iOS SDK v1 사용 시, 프로젝트 설정 및 임포트(import) 후 API를 필요한 시점에 호출할 수 있습니다. 이와 달리 iOS SDK v2는 명시적인 초기화를 필요로 합니다. 앱 실행 후 초기화 이후에 각 API를 호출하도록 구현해야 합니다.
iOS SDK v1 사용 시, 카카오 로그인을 통해 발급 받은 액세스 토큰을 전달해야 하는 API를 KOSessionTask
를 통해 호출해야 합니다. iOS SDK v1의 세션은 사용자의 카카오 로그인 상태에 따라 변경되며, 세션이 열려 있는 상태에서만 호출할 수 있는 API들이 있습니다.
iOS SDK v2의 API는 모듈 단위로 분리되어 있고, 필요한 모듈을 선택하여 효율적으로 사용할 수 있습니다. 카카오 로그인을 통해 발급 받은 액세스 토큰을 전달해야 하는 API를 사용하려면 카카오 로그인 모듈을 함께 설치하고 기능을 구현해야 합니다.
이러한 구조적 차이로 인해 iOS SDK v2 사용 시에는 사용하려는 모듈의 카카오 로그인에 대한 의존도를 먼저 파악해야 합니다. 카카오 로그인 모듈 및 기능 구현이 필요한 API의 경우, 개발 가이드마다 설치해야 하는 모듈과 카카오 로그인 구현이 필요한지 안내합니다.
KakaoSDKCommon
을 통해 초기화 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
Kakao SDK 초기화 | - | initSDK() |
KOSession
을 통해 호출KOSessionTask
를 통해 호출KakaoSDKUser
모듈의 UserApi
를 통해 호출KakaoSDKAuth
모듈의 AuthApi
를 통해 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
카카오 로그인 | openWithCompletionHandler | - |
카카오톡으로 로그인 | - | loginWithKakaoTalk() |
카카오계정으로 로그인 | - | loginWithKakaoAccount() |
로그아웃 | logoutAndCloseWithCompletionHandler | logout() |
연결 끊기 | unlinkTaskWithCompletionHandler | unlink() |
사용자 정보 가져오기 | userMeTaskWithCompletion | me() |
사용자 정보 저장하기 | profileUpdateTaskWithProperties:properties: | updateProfile(properties:) |
추가 항목 동의 받기 | updateScopes:needsAgreementScopes: | loginWithKakaoTalk(scopes:) loginWithKakaoAccount(scopes:) |
카카오톡 실행 가능 여부 확인하기 | - | isKakaoTalkLoginAvailable() |
토큰 정보 보기 | accessTokenInfoTaskWithCompletionHandler | accessTokenInfo() |
토큰 존재 여부 확인하기 | isOpen | hasToken() |
KOSessionTask
를 통해 API 호출KakaoSDKTalk
모듈의 TalkApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
카카오톡 프로필 가져오기 | talkProfileTaskWithCompletionHandler | profile() |
카카오톡 친구 목록 가져오기 | appFriendsWithContext:context: | friends() |
KLKTalkLinkCenter
를 통해 호출KLKImageStorage
를 통해 호출KakaoSDKShare
모듈의 ShareApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
카카오톡 앱을 통한 공유 가능 여부 확인하기 | - | isKakaoTalkSharingAvailable() |
기본 메시지 보내기 | sendDefaultWithTemplate:template: | shareDefault(templatable:) |
사용자 정의 메시지 보내기 | sendCustomWithTemplateId:templateId:templateArgs: | shareCustom(templateId:templateArgs:) |
스크랩 메시지 보내기 | sendScrapWithURL: url:templateId: | shareScrap(requestUrl:templateId:) |
이미지 업로드하기 | uploadWithImage:sourceImage: | imageUpload(image:) |
이미지 스크랩하기 | scrapWithImageURL:imageURL: | imageScrap(imageUrl:) |
이미지 삭제하기 | deleteWithImageURL:imageURL: | - |
KOSessionTask
를 통해 API 호출KakaoSDKTalk
모듈의 TalkApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
나에게 기본 메시지 보내기 | talkMemoSendTaskWithTemplate:template: | sendDefaultMemo(templatable:) |
나에게 스크랩 메시지 보내기 | talkMemoSendTaskWithURL:url:templateId: | sendScrapMemo(requestUrl:templateId:) |
나에게 사용자 정의 메시지 보내기 | talkMemoSendTaskWithTemplateId:templateId: | sendCustomMemo(templateId:) |
친구에게 기본 메시지 보내기 | sendMessageToFriendsWithTemplate:template: | sendDefaultMessage(templatable:receiverUuids:) |
친구에게 스크랩 메시지 보내기 | sendMessageToFriendsTaskWithURL:url:templateId: | sendScrapMessage(requestUrl:templateId:receiverUuids:) |
친구에게 사용자 정의 메시지 보내기 | sendMessageToFriendsTaskWithTemplateId:templateId: | sendCustomMessage(templateId:receiverUuids:) |
KOSessionTask
를 통해 API 호출KakaoSDKStory
모듈의 StoryApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
사용자 확인하기 | storyIsStoryUserTaskWithCompletionHandler | isStoryUser() |
프로필 가져오기 | storyProfileTaskWithCompletionHandler | profile() |
스토리 쓰기 | storyPostNoteTaskWithContent:content: | postNote(content:) |
사진 스토리 쓰기 | storyPostPhotoTaskWithImageUrls:content:images: | postPhoto(content:images:) |
링크 스토리 쓰기 | storyPostLinkTaskWithLinkInfo:link: | postLink(content:linkInfo:) |
내 스토리 가져오기 > 하나의 스토리 가져오기 | storyGetMyStoryTaskWithMyStoryId:myStoryId: | story(id:) |
내 스토리 가져오기 > 여러 개의 스토리 가져오기 | storyGetMyStoriesTaskWithLastMyStoryId:lastMyStoryId: | stories() |
내 스토리 삭제하기 | storyDeleteMyStoryTaskWithMyStoryId:myStoryId: | delete(id:) |
이미지 업로드 | storyMultiImagesUploadTaskWithImages:chosenImages: | upload(images:) |
웹 페이지 스크랩하기 | storyGetLinkInfoTaskWithUrl:url: | linkInfo(url:) |
KPFPlusFriend
를 통해 호출KOSessionTask
를 통해 호출KakaoSDKTalk
모듈의 TalkApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
카카오톡 채널 추가하기 | addFriend:plusFriendId: | makeUrlForAddChannel(channelPublicId:) |
카카오톡 채널 채팅 | chat:plusFriendId: | makeUrlForChannelChat(channelPublicId:) |
채널 관계 확인하기 | talkPlusFriendsTask | channels() |
KOSessionTask
를 통해 호출KOSession
를 통해 호출KakaoSDKUser
모듈의 UserApi
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
배송지 조회하기 | shippingAddressTask | shippingAddresses() |
동의한 약관 확인하기 | serviceTermsTask | serviceTerms() |
약관 선택해 동의 받기 | open | loginWithKakaoTalk(serviceTerms:) loginWithKakaoAccount(serviceTerms:) |
KNVNaviLauncher
를 통해 API 호출KakaoSDKNavi
모듈의 NaviApi
통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
길 안내 | navigateWithParams:params: | navigateUrl(destination:) |
목적지 공유하기 | shareDestinationWithParams:params: | shareUrl(destination:) |
길 안내 조건 설정하기 | locationWithName | NaviOption() |
목적지 정보 설정하기 | paramsWithDestination | NaviLocation() |
* webNavigateUrl(destination:): Deprecated, 웹 길 안내 서비스 종료, 공지 참고
KOSessionTask
를 통해 API 호출Name | iOS SDK v1 | iOS SDK v2 |
---|---|---|
푸시 토큰 등록하기 | pushRegisterDeviceWithToken:deviceToken: | - |
푸시 토큰 보기 | pushGetTokensTaskWithCompletionHandler | - |
푸시 토큰 삭제하기 | pushDeregisterDeviceWithToken:deviceToken: | - |
기존 버전인 Legacy iOS SDK(iOS SDK v1) 사용 방법은 아래 바로가기를 통해 확인할 수 있습니다. 추후 Legacy iOS SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 iOS SDK로 변경할 것을 권장합니다.