페이지 이동경로
  • 문서>
  • 시작하기>
  • iOS

시작하기

iOS

이 문서는 Kakao SDK for iOS(이하 iOS SDK) 사용법을 설명합니다.

요구 사양

iOS SDK를 사용하기 위한 최소 요구 사양은 아래와 같습니다.

  • Xcode 11.0 이상
  • iOS 11.0 이상
  • iOS Deployment Target 11.0 이상
  • Swift 5.0 이상
참고: 외부 라이브러리 의존성

iOS SDK는 다음과 같은 외부 라이브러리를 사용합니다. iOS SDK 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.

설치하기

Cocoapods 또는 Swift Package Manager(이하 SPM) 를 통해 iOS SDK를 설치할 수 있습니다.

Cocoapods를 통해 설치하기

Cocoapods를 이용하여 iOS SDK를 설치할 수 있습니다. Cocoapods 1.8 버전 이상이 필요합니다.

프로젝트의 Podfile에 Kakao SDK를 전체 또는 모듈(Module)별로 추가합니다.

Swift
RxSwift
# 전체 추가
pod 'KakaoSDK'

# or

# 필요한 모듈 추가
pod 'KakaoSDKCommon'  # 필수 요소를 담은 공통 모듈
pod 'KakaoSDKAuth'  # 사용자 인증
pod 'KakaoSDKUser'  # 카카오 로그인, 사용자 관리
pod 'KakaoSDKTalk'  # 친구, 메시지(카카오톡)
pod 'KakaoSDKStory'  # 카카오스토리 
pod 'KakaoSDKLink'  # 메시지(카카오톡 공유)
pod 'KakaoSDKTemplate'  # 메시지 템플릿 
pod 'KakaoSDKNavi'  # 카카오내비 
pod 'KakaoSDKFriend' # 카카오톡 소셜 피커, 리소스 번들 파일 포함
# 전체 추가
pod 'RxKakaoSDK'

# or

# 필요한 모듈 추가
pod 'RxKakaoSDKCommon'  # 필수 요소를 담은 공통 모듈
pod 'RxKakaoSDKAuth'  # 카카오 로그인
pod 'RxKakaoSDKUser'  # 사용자 관리
pod 'RxKakaoSDKTalk'  # 친구, 메시지(카카오톡)
pod 'RxKakaoSDKStory'  # 카카오스토리 
pod 'RxKakaoSDKLink'  # 메시지(카카오톡 공유)
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

SPM을 통해 설치하기

Xcode에서 SPM을 통해 iOS SDK를 설치하려면 다음 순서에 따라 설치를 진행합니다.

피커 모듈 설치

KakaoSDKFriend, RxKakaoSDKFriend 모듈은 SPM을 통해 설치할 수 없습니다. Cocoapod를 통한 설치가 불가능한 경우 데브톡으로 문의합니다.

Step 1. 패키지 추가 화면 띄우기

➊[Project Target] > ➋[Package Dependencies] > ➌[Packages] 메뉴의 [+] 버튼을 눌러 패키지 추가 화면을 띄웁니다.

SPM 설정 화면 경로
Step 2. 레포지토리 검색

패키지 추가 화면 우측 상단의 ➍검색창에 설치할 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] 버튼을 누릅니다.

SPM 레포지토리 검색 화면
참고: 특정 버전을 지정하여 설치하는 방법

[Dependency Rule] 설정을 통해 iOS SDK의 특정 버전을 지정하여 설치할 수 있습니다. 단, SPM을 통한 설치는 2.8.5 이상 버전에서만 제공되므로, 그 이하 버전은 지정 설치가 불가능합니다.

Step 3. 모듈 선택 및 설치

설치할 수 있는 패키지 목록 화면이 나타납니다. ➐[Package Product] 목록에서 필요한 모듈에 체크하고 ➑[Add Packages] 버튼을 눌러 설치합니다.

추가할 패키지 선택 화면

아래는 모듈 정보입니다. 각 모듈은 의존하는 모듈을 자동으로 함께 설치하므로, 필요한 모듈만 체크하여 설치해도 SDK가 정상 동작합니다.

Swift
RxSwift
Module Description
KakaoSDK 모든 모듈 전체 설치
KakaoSDKCommon 카카오 SDK 공통 모듈
KakaoSDKCommonCore 네트워크 기능이 제외된 공통 모듈
KakaoSDKAuth 사용자 인증 및 토큰 관리 모듈
KakaoSDKUser 카카오 로그인 모듈
KakaoSDKLink 카카오톡 공유 모듈
KakaoSDKTalk 카카오톡 소셜, 카카오톡 메시지 모듈
KakaoSDKTemplate 카카오톡 공유, 카카오톡 메시지에 사용되는 메시지 템플릿 모듈
KakaoSDKNavi 카카오내비 모듈
KakaoSDKStory 카카오스토리 모듈
Module Description
RxKakaoSDK 모든 모듈 전체 설치
RxKakaoSDKCommon 카카오 SDK 공통 모듈
RxKakaoSDKCommonCore 네트워크 기능이 제외된 공통 모듈
RxKakaoSDKAuth 사용자 인증 및 토큰 관리 모듈
RxKakaoSDKUser 카카오 로그인 모듈
RxKakaoSDKLink 카카오톡 공유 모듈
RxKakaoSDKTalk 카카오톡 소셜, 카카오톡 메시지 모듈
RxKakaoSDKStory 카카오스토리 모듈

설치된 iOS SDK는 아래와 같이 [Packages] 메뉴에서 확인할 수 있습니다.

설치 확인 화면
참고: 타겟 선택

iOS SDK는 타겟별로 각각 설치해야 합니다. 테스트 앱에도 iOS SDK를 설치하려면 Step 3의 모듈 선택 시 [Add to Target]을 테스트 앱으로 설정합니다.

참고: 모듈간 의존성

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 설정 화면

위 설정은 Info.plist 파일을 직접 수정하여 적용할 수도 있습니다. 상세한 설정 값은 아래 예제를 참고합니다.

 <key>LSApplicationQueriesSchemes</key>
  <array>
      <!-- 카카오톡으로 로그인 -->
      <string>kakaokompassauth</string>
      <!-- 카카오톡 공유 -->
      <string>kakaolink</string>
  </array>

URL Schemes 설정하기

카카오계정을 통한 인증과 카카오톡 메시지를 통한 앱 실행을 위해 [URL Schemes] 설정을 합니다. [Info] > [URL Types] > [URL Schemes] 항목에 네이티브 앱 키(Native App Key)를 kakao${NATIVE_APP_KEY} 형식으로 등록합니다. 예를 들어 네이티브 앱 키가 "123456789"라면 [URL Schemes]에 "kakao123456789"를 입력합니다.

URL Schemes 설정 화면

이 설정은 커스텀 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 초기화 코드를 추가합니다.

아래 예제를 참고합니다.

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() {
        // Kakao SDK 초기화
        KakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
    }
    ...

}
클래스명 변경

iOS SDK 2.8.3 버전부터 SDK 초기화에 사용하는 클래스의 이름이 변경되었습니다.
- KakaoSDKCommon → KakaoSDK
- RxKakaoSDKCommon → RxKakaoSDK

Legacy

기존 버전인 Legacy iOS SDK 사용 방법은 다음 링크를 통해 확인할 수 있습니다. 추후 Legacy iOS SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 iOS SDK로 변경할 것을 권장합니다.

v1→v2 마이그레이션

다음은 Legacy iOS SDK(1.x.x 버전)에서 최신 버전 iOS SDK(2.x.x 버전)로 업그레이드하는 사용자를 위한 참고 정보입니다.

초기화

Legacy iOS SDK 사용 시, 프로젝트 설정 및 임포트(import) 후 API를 필요한 시점에 호출할 수 있습니다. 이와 달리 최신 버전 iOS SDK는 명시적인 초기화를 필요로 합니다. 앱 실행 후 초기화 이후에 각 API를 호출하도록 구현해야 합니다.

카카오 로그인이 필요한 API 사용 시 주의사항

Legacy iOS SDK 사용 시, 카카오 로그인을 통해 발급 받은 액세스 토큰을 전달해야 하는 API를 KOSessionTask를 통해 호출해야 합니다. Legacy iOS SDK의 세션은 사용자의 카카오 로그인 상태에 따라 변경되며, 세션이 열려 있는 상태에서만 호출할 수 있는 API들이 있습니다.

최신 버전 iOS SDK의 API는 모듈 단위로 분리되어 있고, 필요한 모듈을 선택하여 효율적으로 사용할 수 있습니다. 카카오 로그인을 통해 발급 받은 액세스 토큰을 전달해야 하는 API를 사용하려면 카카오 로그인 모듈을 함께 설치하고 기능을 구현해야 합니다.

이러한 구조적 차이로 인해 최신 버전 iOS SDK 사용 시에는 사용하려는 모듈의 카카오 로그인에 대한 의존도를 먼저 파악해야 합니다. 카카오 로그인 모듈 및 기능 구현이 필요한 API의 경우, 개발 가이드마다 설치해야 하는 모듈과 카카오 로그인 구현이 필요한지 안내합니다.

버전별 API 비교

공통
  • 최신 버전: KakaoSDKCommon을 통해 초기화 API 호출
Name Legacy SDK SDK
Kakao SDK 초기화 - initSDK()
카카오 로그인
  • Legacy
    • 카카오 로그인 API는 KOSession을 통해 호출
    • 카카오 로그인 이후 호출하는 API는 KOSessionTask를 통해 호출
  • 최신 버전
    • 카카오 로그인 API는 KakaoSDKUser 모듈의 UserApi를 통해 호출
    • 토큰 존재 여부 확인하기 API는 KakaoSDKAuth 모듈의 AuthApi를 통해 호출
Name Legacy SDK SDK
카카오 로그인 openWithCompletionHandler -
카카오톡으로 로그인 - loginWithKakaoTalk()
카카오계정으로 로그인 - loginWithKakaoAccount()
로그아웃 logoutAndCloseWithCompletionHandler logout()
연결 끊기 unlinkTaskWithCompletionHandler unlink()
사용자 정보 가져오기 userMeTaskWithCompletion me()
사용자 정보 저장하기 profileUpdateTaskWithProperties:properties: updateProfile(properties:)
추가 항목 동의 받기 updateScopes:needsAgreementScopes: loginWithKakaoTalk(scopes:)
loginWithKakaoAccount(scopes:)
카카오톡 설치 여부 확인하기 - isKakaoTalkLoginAvailable()
토큰 정보 보기 accessTokenInfoTaskWithCompletionHandler accessTokenInfo()
토큰 존재 여부 확인하기 isOpen hasToken()
카카오톡 소셜
  • Legacy: KOSessionTask를 통해 API 호출
  • 최신 버전: KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출
Name Legacy SDK SDK
카카오톡 프로필 가져오기 talkProfileTaskWithCompletionHandler profile()
카카오톡 친구 목록 가져오기 appFriendsWithContext:context: friends()
메시지: 카카오톡 공유
  • Legacy SDK
    • 메시지 보내기 API는 KLKTalkLinkCenter를 통해 호출
    • 이미지 API는 KLKImageStorage를 통해 호출
    • 카카오톡 미설치 시 내부적으로 웹뷰를 통해 메시지 전달됨
  • 최신 버전
    • KakaoSDKLink 모듈의 LinkApi를 통해 API 호출
    • 카카오톡 미설치 시 웹뷰 또는 기본 브라우저를 통해 공유되도록 구현 필요
Name Legacy SDK SDK
카카오톡 설치 여부 확인하기 - isKakaoLinkAvailable()
기본 메시지 보내기 sendDefaultWithTemplate:template: defaultLink(templatable:)
스크랩 메시지 보내기 sendScrapWithURL: url:templateId: scrapLink(requestUrl:templateId:)
사용자 정의 메시지 보내기 sendCustomWithTemplateId:templateId:templateArgs: customLink(templateId:templateArgs:)
이미지 업로드하기 uploadWithImage:sourceImage: imageUpload(image:)
이미지 스크랩하기 scrapWithImageURL:imageURL: imageScrap(imageUrl:)
이미지 삭제하기 deleteWithImageURL:imageURL: -
메시지: 카카오톡
  • Legacy: KOSessionTask를 통해 API 호출
  • 최신 버전: KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출
Name Legacy SDK SDK
나에게 기본 메시지 보내기 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:)
카카오스토리
  • Legacy: KOSessionTask를 통해 API 호출
  • 최신 버전: KakaoSDKStory 모듈의 StoryApi를 통해 API 호출
Name Legacy SDK SDK
사용자 확인하기 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:)
카카오톡 채널
  • Legacy
    • 카카오톡 채널 추가하기와 카카오톡 채널 채팅은 KPFPlusFriend를 통해 호출
    • 채널 관계 확인하기 API는 KOSessionTask를 통해 호출
  • 최신 버전
    • KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출
    • 카카오톡 채널 관계 확인하기 API는 카카오 로그인 구현 필요
Name Legacy SDK SDK
카카오톡 채널 추가하기 addFriend:plusFriendId: makeUrlForAddChannel(channelPublicId:)
카카오톡 채널 채팅 chat:plusFriendId: makeUrlForChannelChat(channelPublicId:)
채널 관계 확인하기 talkPlusFriendsTask channels()
카카오싱크
Name Legacy SDK SDK
배송지 조회하기 shippingAddressTask shippingAddresses()
동의한 약관 확인하기 serviceTermsTask serviceTerms()
약관 선택해 동의 받기 open loginWithKakaoTalk(serviceTerms:)
loginWithKakaoAccount(serviceTerms:)
카카오내비
  • Legacy
    • KNVNaviLauncher를 통해 API 호출
    • 파라미터 설정은 각 클래스 빌더(Builder) 사용
  • 최신 버전
    • KakaoSDKNavi 모듈의 NaviApi 통해 API 호출
    • 파라미터 설정은 각 클래스 생성자 사용
Name Legacy SDK SDK
길 안내 navigateWithParams:params: navigateUrl(destination:)
목적지 공유하기 shareDestinationWithParams:params: shareUrl(destination:)
길 안내 조건 설정하기 locationWithName NaviOption()
목적지 정보 설정하기 paramsWithDestination NaviLocation()

* webNavigateUrl(destination:): Deprecated, 웹 길 안내 서비스 종료, 공지 참고

푸시 알림
  • Legacy: KOSessionTask를 통해 API 호출
  • 최신 버전: 푸시 알림 API 미지원, REST API 사용 가능
Name Legacy SDK SDK
푸시 토큰 등록하기 pushRegisterDeviceWithToken:deviceToken: -
푸시 토큰 보기 pushGetTokensTaskWithCompletionHandler -
푸시 토큰 삭제하기 pushDeregisterDeviceWithToken:deviceToken: -

더보기