kakao developers

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 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.

• iOS SDK: Alamofire
• ReactiveX iOS SDK: RxSwift, RxCocoa, RxAlamofire

설치

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

• Cocoapods로 설치
• SPM으로 설치

Cocoapods로 설치

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

SPM으로 설치

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

➊[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가 정상 동작합니다.

Swift

RxSwift

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]을 테스트 앱으로 설정합니다.

참고: 모듈간 의존성

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>

URL Schemes 설정

카카오계정을 통한 인증과 카카오톡 메시지를 통한 앱 실행을 위해 [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")
    }
    ...

}

v1에서 v2로 마이그레이션

다음은 iOS SDK v1(2.0.0 미만 버전)에서 iOS SDK v2로 업그레이드하는 사용자를 위한 참고 정보입니다.

초기화

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

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

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

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

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

버전별 API 비교

공통

• 최신 버전: KakaoSDKCommon을 통해 초기화 API 호출

카카오 로그인

• iOS SDK v1
  • 카카오 로그인 API는 KOSession을 통해 호출
  • 카카오 로그인 이후 호출하는 API는 KOSessionTask를 통해 호출
• 최신 버전
  • 카카오 로그인 API는 KakaoSDKUser 모듈의 UserApi를 통해 호출
  • 토큰 존재 여부 확인하기 API는 KakaoSDKAuth 모듈의 AuthApi를 통해 호출

카카오톡 소셜

• iOS SDK v1: KOSessionTask를 통해 API 호출
• 최신 버전: KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출

메시지: 카카오톡 공유

• iOS SDK v1
  • 메시지 보내기 API는 KLKTalkLinkCenter를 통해 호출
  • 이미지 API는 KLKImageStorage를 통해 호출
  • 카카오톡 미설치 시 내부적으로 웹뷰를 통해 메시지 전달됨
• 최신 버전
  • KakaoSDKShare 모듈의 ShareApi를 통해 API 호출
  • 카카오톡 미설치 시 웹뷰 또는 기본 브라우저를 통해 공유되도록 구현 필요

메시지: 카카오톡

• iOS SDK v1: KOSessionTask를 통해 API 호출
• 최신 버전: KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출

카카오스토리

• iOS SDK v1: KOSessionTask를 통해 API 호출
• 최신 버전: KakaoSDKStory 모듈의 StoryApi를 통해 API 호출

카카오톡 채널

• iOS SDK v1
  • 카카오톡 채널 추가하기와 카카오톡 채널 채팅은 KPFPlusFriend를 통해 호출
  • 채널 관계 확인하기 API는 KOSessionTask를 통해 호출
• 최신 버전
  • KakaoSDKTalk 모듈의 TalkApi를 통해 API 호출
  • 카카오톡 채널 관계 확인하기 API는 카카오 로그인 구현 필요

카카오싱크

• iOS SDK v1
  • 배송지 가져오기, 동의한 약관 확인하기 API는 KOSessionTask를 통해 호출
  • 약관 선택해 동의 받기 API는 KOSession를 통해 호출
• 최신 버전
  • 배송지 가져오기, 동의한 약관 확인하기, 약관 선택해 동의 받기 API 모두 KakaoSDKUser 모듈의 UserApi를 통해 API 호출

카카오내비

• iOS SDK v1
  • KNVNaviLauncher를 통해 API 호출
  • 파라미터 설정은 각 클래스 빌더(Builder) 사용
• 최신 버전
  • KakaoSDKNavi 모듈의 NaviApi 통해 API 호출
  • 파라미터 설정은 각 클래스 생성자 사용

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

푸시 알림

• iOS SDK v1: KOSessionTask를 통해 API 호출
• 최신 버전: 푸시 알림 API 미지원, REST API 사용 가능

Legacy

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

Legacy iOS

더 보기

iOS SDK 다운로드ReactiveX iOS SDK 레퍼런스outlinkiOS SDK 레퍼런스outlink