@package-kr/react-native-kakao-signin

React Native 전용 카카오 로그인 라이브러리 입니다.

Getting started

해당 라이브러리는 React Native 0.68 이상을 지원합니다. TurboModule 기반으로 구현되어 있어 New Architecture를 지원하며, Auto Linking이 적용되어 있어 별도 네이티브 모듈 연결 작업이 필요 없습니다.

Expo와 React Native CLI 프로젝트 모두 지원합니다.

Prerequisites

라이브러리를 사용하려면 먼저 카카오 개발자 콘솔에서 앱 등록과 플랫폼 설정을 완료해야 합니다.

Installation

npm install @package-kr/react-native-kakao-signin

React Native CLI

Android

1. Redirect URI 설정

app/src/main/AndroidManifest.xml에 카카오 리다이렉트 액티비티를 추가합니다. {KAKAO_APP_KEY} 부분을 카카오 네이티브 앱 키로 교체해주세요. 앱 키에는 kakao 접두사를 붙이지 않고, android:scheme에만 kakao{KAKAO_APP_KEY} 형식으로 사용합니다.

사용자 휴대폰에 카카오 앱이 설치되어 있을 경우 로그인 후 앱으로 돌아오기 위한 설정입니다. Android 12(API 31) 이상을 타깃하는 경우 android:exported="true" 를 반드시 선언해주셔야 합니다.

	  <!-- AndroidManifest.xml -->
      <activity
        android:name="com.kakao.sdk.auth.AuthCodeHandlerActivity"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:host="oauth" android:scheme="kakao{KAKAO_APP_KEY}" />
        </intent-filter>
      </activity>

2. 카카오 앱 키 설정

app/src/main/res/values/strings.xml에 카카오 앱 키를 추가합니다. 카카오 SDK가 앱 키를 자동으로 읽어오기 위한 설정입니다.

  <resources>
      <string name="app_name">YourAppName</string>
+     <string name="kakao_app_key">{KAKAO_APP_KEY}</string>
+     <!-- 선택 사항: 멀티 플랫폼 앱 구현이나 커스텀 URL scheme 사용 시에만 추가합니다. -->
+     <!-- <string name="kakao_custom_scheme">{CUSTOM_SCHEME}</string> -->
  </resources>

iOS

1. Info.plist 설정

ios/{ProjectName}/Info.plist에서 {KAKAO_APP_KEY} 부분을 카카오 네이티브 앱 키로 교체해주세요. 앱 키에는 kakao 접두사를 붙이지 않습니다. URL scheme은 기본적으로 kakao{KAKAO_APP_KEY} 형식을 사용합니다.

	<key>CFBundleURLTypes</key>
	<array>
		<dict>
			<key>CFBundleTypeRole</key>
			<string>Editor</string>
			<key>CFBundleURLName</key>
			<string>KAKAO</string>
			<key>CFBundleURLSchemes</key>
			<array>
				<string>kakao{KAKAO_APP_KEY}</string>
			</array>
		</dict>
	</array>
	<key>KAKAO_APP_KEY</key>
	<string>{KAKAO_APP_KEY}</string>
	<!-- 선택 사항: 멀티 플랫폼 앱 구현이나 커스텀 URL scheme 사용 시에만 추가합니다. -->
	<!--
	<key>KAKAO_APP_SCHEME</key>
	<string>{CUSTOM_SCHEME}</string>
	-->
	<key>LSApplicationQueriesSchemes</key>
	<array>
		<string>kakao{KAKAO_APP_KEY}</string>
		<string>kakaokompassauth</string>
		<string>kakaotalk</string>
	</array>

	<!-- Info.plist -->
+ 	<key>CFBundleURLTypes</key>
+	  <array>
+		<dict>
+			<key>CFBundleTypeRole</key>
+			<string>Editor</string>
+			<key>CFBundleURLName</key>
+			<string>KAKAO</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>kakao{KAKAO_APP_KEY}</string>
+			</array>
+		</dict>
+	  </array>
+	<key>KAKAO_APP_KEY</key>
+	<string>{KAKAO_APP_KEY}</string>
+	<!-- 선택 사항: 멀티 플랫폼 앱 구현이나 커스텀 URL scheme 사용 시에만 추가합니다. -->
+	<!--
+	<key>KAKAO_APP_SCHEME</key>
+	<string>{CUSTOM_SCHEME}</string>
+	-->
+	<key>LSApplicationQueriesSchemes</key>
+	<array>
+		<string>kakao{KAKAO_APP_KEY}</string>
+		<string>kakaokompassauth</string>
+		<string>kakaotalk</string>
+	</array>

2. AppDelegate 설정

ios/{ProjectName}/AppDelegate.swift에 카카오 로그인 URL 처리 코드를 추가합니다.

import React
import RNKakaoSignin

// AppDelegate 클래스 안에 메서드 추가
func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  if RNKakaoSignin.handleOpen(url) {
    return true
  }

  return RCTLinkingManager.application(app, open: url, options: options)
}

3. CocoaPods 설치

cd ios && pod install

Expo

1. Config Plugin 설정

app.json 또는 app.config.js에 플러그인을 추가합니다.

{
  "expo": {
    "plugins": [
      [
        "@package-kr/react-native-kakao-signin",
        {
          "kakaoAppKey": "{KAKAO_APP_KEY}"
        }
      ]
    ]
  }
}

iOS Info.plist/AppDelegate와 Android Manifest/strings.xml/Kakao Maven 저장소 설정이 자동으로 처리됩니다. kakaoAppKey에는 kakao 접두사를 붙이지 않습니다. 기본 URL scheme은 kakao{KAKAO_APP_KEY}로 자동 설정됩니다.

커스텀 URL scheme을 사용하는 경우 kakaoAppScheme을 추가합니다.

{
  "expo": {
    "plugins": [
      [
        "@package-kr/react-native-kakao-signin",
        {
          "kakaoAppKey": "{KAKAO_APP_KEY}",
          "kakaoAppScheme": "{CUSTOM_SCHEME}"
        }
      ]
    ]
  }
}

2. 빌드

npx expo run:ios

Usage

더 많은 사용 예제는 RNKakaoSigninCliExample 프로젝트를 참고해주세요.

import {
  login,
  loginWithKakaoAccount,
  logout,
  unlink,
  getProfile,
  getAccessToken,
  shippingAddresses,
  serviceTerms,
} from '@package-kr/react-native-kakao-signin';

// 카카오톡 앱을 먼저 사용하고, 사용할 수 없으면 카카오계정 로그인으로 전환됩니다.
const kakaoTalkToken = await login();

// 카카오톡 앱이 설치되어 있어도 앱 로그인을 건너뛰고, 카카오계정 로그인 웹 기반 화면으로 바로 이동합니다.
const kakaoAccountToken = await loginWithKakaoAccount();

// 로그아웃
await logout();

// 연결 해제
await unlink();

// 프로필 조회
const profile = await getProfile();

// 토큰 조회
const accessTokenInfo = await getAccessToken();

// 배송주소 조회
const addresses = await shippingAddresses();

// 서비스 약관 조회
const terms = await serviceTerms();

Methods

| 메서드 | 설명 | Returns | | ------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------- | | login() | 카카오톡으로 로그인합니다. 카카오톡 미설치 시 카카오계정 로그인으로 자동 전환됩니다. | Promise<KakaoOAuthToken> | | loginWithKakaoAccount() | 카카오톡 앱이 설치되어 있어도 앱 로그인을 건너뛰고, 카카오계정 로그인 웹 기반 화면으로 바로 이동합니다. | Promise<KakaoOAuthToken> | | logout() | 로그아웃합니다. | Promise<boolean> | | unlink() | 카카오 계정 연결을 해제합니다. | Promise<boolean> | | getProfile() | 사용자 프로필을 조회합니다. | Promise<KakaoProfile> | | getAccessToken() | 현재 저장된 액세스 토큰을 조회합니다. | Promise<KakaoAccessTokenInfo \| null> | | shippingAddresses() | 사용자 배송주소 목록을 조회합니다. | Promise<KakaoShippingAddresses> | | serviceTerms() | 서비스 약관 동의 내역을 조회합니다. | Promise<KakaoServiceTerms> |

Error Handling

네이티브 설정, SDK 초기화, 로그인, API 호출 중 오류가 발생하면 Promise가 reject됩니다.

이 라이브러리는 Kakao SDK 원문 오류를 그대로 message에 넣지 않고, 아래 구조로 정리해서 전달합니다.

{
  code: 'KAKAO_INVALID_APP_KEY',
  message: 'The Kakao native app key is invalid. Please check your Kakao app key configuration.',
  userInfo: {
    sdkMessage: 'invalid_client ...',
  },
}

| 필드 | 설명 | | --------------------- | ------------------------------------------------ | | code | 앱에서 분기 처리하기 위한 안정적인 에러 코드 | | message | 라이브러리가 제공하는 기본 영어 원인/조치 메시지 | | userInfo.sdkMessage | Kakao SDK 또는 네이티브에서 전달된 원문 메시지 |

userInfo.sdkMessage는 SDK가 원문 메시지를 제공할 때만 포함됩니다. 사용자에게 그대로 노출하기보다는 개발 중 설정 문제를 확인하는 용도로 사용하는 것을 권장합니다.

Types

아래 타입 표는 필드가 포함될 때의 값 타입을 기준으로 설명합니다. 선택 필드는 값이 없으면 null로 내려오지 않고 응답에서 생략됩니다.

KakaoSigninError

| 필드 | 타입 | 설명 | | --------------------- | --------------------- | ----------------------------------------------------------- | | code | KakaoErrorCode | 네이티브 모듈에서 전달한 안정적인 에러 코드 | | message | string | 라이브러리가 제공하는 영어 원인/조치 메시지 | | sdkMessage | string \| undefined | 일부 React Native 런타임에서 노출될 수 있는 SDK 원문 메시지 | | userInfo.sdkMessage | string \| undefined | Kakao SDK 또는 네이티브에서 전달된 원문 메시지 |

KakaoErrorCode

| 코드 | 설명 | | ------------------------------------ | ------------------------------------------- | | KAKAO_ACTIVITY_DOES_NOT_EXIST | 현재 Activity 없음 | | KAKAO_ACCESS_DENIED | 사용자 취소 또는 접근 거부 | | KAKAO_API_ERROR | 카카오 API 오류 | | KAKAO_AUTH_ERROR | 카카오 인증 오류 | | KAKAO_BAD_PARAMETER | 잘못된 파라미터 | | KAKAO_CANCELLED | 사용자 취소 | | KAKAO_CLIENT_ERROR | 클라이언트 오류 | | KAKAO_ERROR | 일반 오류 | | KAKAO_FORBIDDEN | 권한 부족 | | KAKAO_ILLEGAL_STATE | 잘못된 상태 | | KAKAO_INVALID_APP_KEY | 앱 키 설정 오류 | | KAKAO_INVALID_BUNDLE_ID | iOS 번들 ID 또는 Android 패키지명 설정 오류 | | KAKAO_INVALID_CLIENT | 클라이언트 설정 오류 | | KAKAO_INVALID_GRANT | 인가 정보 오류 | | KAKAO_INVALID_REQUEST | 잘못된 로그인 요청 | | KAKAO_INVALID_SCOPE | 잘못된 동의 항목 | | KAKAO_INVALID_URL_SCHEME | URL scheme 설정 오류 | | KAKAO_LOGIN_REQUIRED | 로그인 권한 필요 | | KAKAO_MISCONFIGURED | 카카오 플랫폼 설정 오류 | | KAKAO_NOT_SUPPORTED | 지원하지 않는 기능 | | KAKAO_PROFILE_NOT_FOUND | 프로필 정보 없음 | | KAKAO_RATE_LIMIT | 요청 제한 초과 | | KAKAO_SERVER_ERROR | 카카오 서버 오류 | | KAKAO_SHIPPING_ADDRESSES_NOT_FOUND | 배송지 정보 없음 | | KAKAO_TOKEN_EXPIRED | 토큰 만료 | | KAKAO_TOKEN_NOT_FOUND | 토큰 없음 | | KAKAO_UNKNOWN_ERROR | 알 수 없는 오류 |

KakaoOAuthToken

| 필드 | 타입 | 설명 | | ----------------------- | ---------- | ------------------------ | | accessToken | string | 액세스 토큰 | | refreshToken | string | 리프레시 토큰 | | idToken | string | ID 토큰 (OpenID Connect) | | accessTokenExpiresAt | string | 액세스 토큰 만료 시각 | | refreshTokenExpiresAt | string | 리프레시 토큰 만료 시각 | | scopes | string[] | 인증된 스코프 목록 |

KakaoProfile

| 필드 | 타입 | 설명 | | ------------------------------- | --------------------------------- | --------------------------------- | | id | string | 사용자 ID | | nickname | string | 닉네임 | | name | string | 이름 | | email | string | 이메일 | | profileImageUrl | string | 프로필 이미지 URL | | thumbnailImageUrl | string | 프로필 썸네일 이미지 URL | | gender | string | 성별 | | ageRange | string | 연령대 | | birthday | string | 생일 (MMDD) | | birthdayType | 'solar' \| 'lunar' \| 'unknown' | 생일 타입 | | birthyear | string | 출생 연도 | | phoneNumber | string | 전화번호 | | isEmailValid | boolean | 이메일 유효 여부 | | isEmailVerified | boolean | 이메일 인증 여부 | | isKorean | boolean | 한국인 여부 | | isDefaultImage | boolean | 기본 프로필 이미지 여부 | | isLeapMonth | boolean | 생일 윤달 여부 (Android only) | | connectedAt | string | 서비스 연결 시각 | | synchedAt | string | 카카오싱크 로그인 시각 | | ci | string | 연계정보 (iOS only) | | ciAuthenticatedAt | string | CI 발급 시각 (iOS only) | | legalName | string | 법정 이름 | | legalBirthDate | string | 법정 생년월일 | | legalGender | string | 법정 성별 | | emailNeedsAgreement | boolean | 이메일 제공 동의 필요 여부 | | profileNeedsAgreement | boolean | 프로필 제공 동의 필요 여부 | | phoneNumberNeedsAgreement | boolean | 전화번호 제공 동의 필요 여부 | | genderNeedsAgreement | boolean | 성별 제공 동의 필요 여부 | | ageRangeNeedsAgreement | boolean | 연령대 제공 동의 필요 여부 | | birthdayNeedsAgreement | boolean | 생일 제공 동의 필요 여부 | | birthyearNeedsAgreement | boolean | 출생 연도 제공 동의 필요 여부 | | isKoreanNeedsAgreement | boolean | 한국인 여부 제공 동의 필요 여부 | | profileNicknameNeedsAgreement | boolean | 닉네임 제공 동의 필요 여부 | | profileImageNeedsAgreement | boolean | 프로필 이미지 제공 동의 필요 여부 | | nameNeedsAgreement | boolean | 이름 제공 동의 필요 여부 | | ciNeedsAgreement | boolean | CI 제공 동의 필요 여부 (iOS only) | | legalNameNeedsAgreement | boolean | 법정 이름 제공 동의 필요 여부 | | legalBirthDateNeedsAgreement | boolean | 법정 생년월일 제공 동의 필요 여부 | | legalGenderNeedsAgreement | boolean | 법정 성별 제공 동의 필요 여부 |

KakaoAccessTokenInfo

| 필드 | 타입 | 설명 | | ------------- | -------- | ----------------------- | | accessToken | string | 액세스 토큰 | | expiresIn | number | 만료까지 남은 시간 (초) |

KakaoShippingAddresses

| 필드 | 타입 | 설명 | | ------------------- | ------------------------ | -------------- | | userId | string | 사용자 ID | | needsAgreement | boolean | 동의 필요 여부 | | shippingAddresses | KakaoShippingAddress[] | 배송주소 목록 |

KakaoShippingAddress

| 필드 | 타입 | 설명 | | ---------------------- | ----------------------------- | ----------------- | | id | string | 배송주소 ID | | name | string | 배송지명 | | isDefault | boolean | 기본 배송지 여부 | | updatedAt | string | 수정 시각 | | type | 'old' \| 'new' \| 'unknown' | 배송지 타입 | | baseAddress | string | 기본 주소 | | detailAddress | string | 상세 주소 | | receiverName | string | 수령인 이름 | | receiverPhoneNumber1 | string | 수령인 전화번호 1 | | receiverPhoneNumber2 | string | 수령인 전화번호 2 | | zoneNumber | string | 우편번호 | | zipCode | string | 구 우편번호 |

KakaoServiceTerms

| 필드 | 타입 | 설명 | | -------------- | -------------------- | ---------------- | | userId | string | 사용자 ID | | serviceTerms | KakaoServiceTerm[] | 서비스 약관 목록 |

KakaoServiceTerm

| 필드 | 타입 | 설명 | | ----------- | --------------------- | -------------- | | tag | string | 약관 태그 | | agreed | boolean | 동의 여부 | | required | boolean | 필수 여부 | | revocable | boolean | 철회 가능 여부 | | agreedAt | string \| undefined | 동의 시각 |

Kakao SDK 버전 오버라이드

기본적으로 Kakao SDK 2.22.0을 사용합니다. 호스트 앱에서 다른 버전을 사용해야 하는 경우 아래와 같이 오버라이드할 수 있습니다.

Expo

app.json에서 overrideKakaoSDKVersion을 지정합니다.

{
  "expo": {
    "plugins": [
      [
        "@package-kr/react-native-kakao-signin",
        {
          "kakaoAppKey": "{KAKAO_APP_KEY}",
          "overrideKakaoSDKVersion": "2.23.0"
        }
      ]
    ]
  }
}

CLI (iOS)

ios/Podfile 상단에 전역변수를 선언합니다.

$KakaoSDKVersion = "2.23.0"

CLI (Android)

android/build.gradle의 ext 블록에 속성을 추가합니다.

buildscript {
    ext {
        kakaoSdkVersion = "2.23.0"
    }
}

테스트 환경

| 환경 | 패키지 버전 | RN / Expo 버전 | KakaoSDK 버전 | 마지막 테스트 | 동작 여부 | | ------------ | ----------- | ----------------------- | ------------- | ------------- | --------- | | CLI iOS | 최신 버전 | React Native 0.85.3 | 2.22.0 | 2026-05-08 | ✅ | | CLI Android | 최신 버전 | React Native 0.85.3 | 2.22.0 | 2026-05-08 | ✅ | | Expo iOS | 최신 버전 | Expo SDK 54 / RN 0.81.5 | 2.22.0 | 2026-05-08 | ✅ | | Expo Android | 최신 버전 | Expo SDK 54 / RN 0.81.5 | 2.22.0 | 2026-05-08 | ✅ |

라이선스

MIT