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

시작하기

iOS

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

애플리케이션 설정 확인

iOS SDK를 사용하려면 카카오디벨로퍼스(Kakao Developers, 이하 개발자 웹사이트) 애플리케이션(이하 앱) 설정에 iOS 플랫폼 및 번들 ID 등 정보가 등록되어 있어야 합니다. 자세한 내용은 애플리케이션 등록을 참고합니다.

요구사양

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

  • Xcode 11.0 이상
  • iOS 11.0 이상
  • iOS Deployment Target 11.0 이상
  • Swift 4.2 이상

설치하기

Cocoapods를 이용하여 간단하게 SDK를 설치할 수 있습니다. 프로젝트의 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 'RxKakaoSDK'

# or

# 필요한 모듈 추가
pod 'RxKakaoSDKCommon'  # 필수 요소를 담은 공통 모듈
pod 'RxKakaoSDKAuth'  # 카카오 로그인
pod 'RxKakaoSDKUser'  # 사용자 관리
pod 'RxKakaoSDKTalk'  # 친구, 메시지(카카오톡)
pod 'RxKakaoSDKStory'  # 카카오스토리 
pod 'RxKakaoSDKLink'  # 메시지(카카오링크)
pod 'RxKakaoSDKTemplate'  # 메시지 템플릿 
pod 'RxKakaoSDKNavi'  # 카카오내비
참고: 외부 라이브러리 디펜던시 자동 설치

Cocoapods를 통해 iOS SDK 설치 시, iOS SDK에 필요한 외부 라이브러리(External library dependency)가 자동으로 설치됩니다.

Info.plist 설정

앱 실행 허용 목록(Allowlist) 등록하기

iOS 9.0 이상에서 iOS SDK를 통해 카카오톡이나 카카오스토리, 카카오내비 등 애플리케이션(이하 앱)을 실행시키는 기능을 이용하려면 Info.plist 파일에 설정을 추가하여 커스텀 URL 스킴 정보를 등록합니다. 이 설정은 사용자 정보 보호를 위한 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 초기화 코드를 추가합니다.

아래 예제를 참고합니다.

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:)
길안내 URL 구하기 - Deprecated, 웹 길안내 서비스 종료 예정
webNavigateUrl(destination:)
목적지 공유하기 shareDestinationWithParams:params: shareUrl(destination:)
길안내 조건 설정하기 locationWithName NaviOption()
목적지 정보 설정하기 paramsWithDestination NaviLocation()
푸시 알림
  • Legacy: KOSessionTask를 통해 API 호출
  • 최신 버전: 푸시 알림 API 미지원, REST API 사용 가능
Name Legacy SDK SDK
푸시 토큰 등록하기 pushRegisterDeviceWithToken:deviceToken: -
푸시 토큰 보기 pushGetTokensTaskWithCompletionHandler -
푸시 토큰 삭제하기 pushDeregisterDeviceWithToken:deviceToken: -

더보기