@chuseok22/capacitor-kakao-login 0.1.8 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ Capacitor 앱에서 카카오 소셜 로그인을 최소한의 설정으로 사
 - iOS / Android 지원
 - 카카오톡 앱 로그인 우선, 미설치 시 카카오 계정 웹뷰 로그인으로 자동 폴백
 - Capacitor 6.x 이상
+- 닉네임, 이메일, 성별 등 카카오 사용자 정보 추가 반환 지원
 
 ---
 
@@ -74,6 +75,26 @@ SDK 초기화, URL 핸들러 등록, AuthCodeHandlerActivity는 플러그인이
 
 앱 설정 → **카카오 로그인 → 활성화 설정 → ON**
 
+### 2-4. 동의 항목 설정 (추가 사용자 정보가 필요한 경우)
+
+`socialId` 외에 닉네임, 이메일 등 추가 정보를 받으려면 카카오 개발자 콘솔에서 동의 항목을 활성화해야 합니다.
+
+**앱 설정 → 카카오 로그인 → 동의 항목** 에서 필요한 항목을 선택합니다.
+
+| 동의 항목 | 반환 필드 | 필수/선택 |
+|-----------|-----------|-----------|
+| 프로필 정보 (닉네임/프로필 사진) | `nickname`, `profileImageUrl`, `thumbnailImageUrl` | 선택 |
+| 카카오계정 (이메일) | `email` | 선택 |
+| 이름 | `name` | 선택 |
+| 전화번호 | `phoneNumber` | 선택 |
+| 성별 | `gender` | 선택 |
+| 생일 | `birthday`, `birthyear` | 선택 |
+
+> **주의사항:**
+> - 동의 항목을 활성화하지 않으면 해당 필드는 `undefined`로 반환됩니다.
+> - 사용자가 동의를 거부한 경우에도 해당 필드는 `undefined`입니다.
+> - 카카오 비즈앱 심사를 통과해야 일부 항목(이름, 전화번호 등)을 실제 서비스에서 사용할 수 있습니다.
+
 ---
 
 ## 3. 설치
@@ -178,6 +199,11 @@ classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21'
 
 ## 7. 사용법
 
+### 기본 사용 (socialId만 필요한 경우)
+
+대부분의 서비스는 서버 인증에 `socialId`만 사용합니다.  
+카카오 개발자 콘솔에서 별도 동의 항목 설정 없이 바로 사용할 수 있습니다.
+
 ```typescript
 import { KakaoLogin } from '@chuseok22/capacitor-kakao-login';
 
@@ -192,6 +218,52 @@ async function loginWithKakao() {
 }
 ```
 
+### 추가 사용자 정보 활용 (동의 항목 활성화 후)
+
+카카오 개발자 콘솔에서 동의 항목을 활성화한 경우, 로그인 결과에서 바로 추가 정보를 꺼낼 수 있습니다.
+
+```typescript
+import { KakaoLogin } from '@chuseok22/capacitor-kakao-login';
+
+async function loginWithKakao() {
+  try {
+    const result = await KakaoLogin.login();
+
+    // socialId는 항상 반환됩니다
+    console.log('카카오 ID:', result.socialId);
+
+    // 아래 필드는 카카오 개발자 콘솔에서 동의 항목을 활성화한 경우에만 값이 있습니다
+    if (result.nickname) {
+      console.log('닉네임:', result.nickname);
+    }
+    if (result.profileImageUrl) {
+      console.log('프로필 이미지:', result.profileImageUrl);
+    }
+    if (result.email) {
+      console.log('이메일:', result.email);
+    }
+    if (result.gender) {
+      console.log('성별:', result.gender); // 'male' | 'female' | 'other'
+    }
+    if (result.birthday) {
+      console.log('생일:', result.birthday); // 'MMDD' 형식, 예: '0101'
+    }
+
+    // 서버에 전달
+    await registerUser({
+      socialId: result.socialId,
+      nickname: result.nickname,
+      email: result.email,
+    });
+  } catch (error) {
+    console.error('카카오 로그인 실패:', error);
+  }
+}
+```
+
+> **동의하지 않은 항목은 `undefined`입니다.**  
+> 사용 전 반드시 값이 존재하는지 확인하세요. (`result.nickname ?? '익명'` 패턴 권장)
+
 ---
 
 ## 8. API
@@ -206,12 +278,35 @@ login(): Promise<KakaoLoginResult>
 - 카카오톡 설치 → 카카오톡 앱 로그인
 - 카카오톡 미설치 → 카카오 계정 웹뷰 로그인 (자동 폴백)
 
-**반환값:**
+**반환값 `KakaoLoginResult`:**
+
+| 필드 | 타입 | 필수 여부 | 설명 | 필요한 동의 항목 |
+|------|------|-----------|------|-----------------|
+| `socialId` | `string` | 필수 | 카카오 회원 고유 ID. 서버 사용자 식별에 사용 | 없음 (기본 제공) |
+| `nickname` | `string` | 선택 | 카카오 프로필 닉네임 | 프로필 정보 (닉네임/프로필 사진) |
+| `profileImageUrl` | `string` | 선택 | 프로필 이미지 원본 URL | 프로필 정보 (닉네임/프로필 사진) |
+| `thumbnailImageUrl` | `string` | 선택 | 프로필 이미지 썸네일 URL | 프로필 정보 (닉네임/프로필 사진) |
+| `email` | `string` | 선택 | 카카오계정 이메일 | 카카오계정 (이메일) |
+| `name` | `string` | 선택 | 카카오계정 실명 | 이름 |
+| `phoneNumber` | `string` | 선택 | 카카오계정 전화번호. `+82 10-1234-5678` 형식 | 전화번호 |
+| `gender` | `string` | 선택 | 성별. `'male'` \| `'female'` \| `'other'` | 성별 |
+| `birthyear` | `string` | 선택 | 출생연도 4자리. 예: `'1990'` | 생일 |
+| `birthday` | `string` | 선택 | 생일 MMDD 형식. 예: `'0101'` | 생일 |
+
+**타입 정의:**
 
 ```typescript
 interface KakaoLoginResult {
-  /** 카카오 회원 고유 ID. 서버에서 사용자를 식별하는 데 사용합니다. */
   socialId: string;
+  nickname?: string;
+  profileImageUrl?: string;
+  thumbnailImageUrl?: string;
+  email?: string;
+  name?: string;
+  phoneNumber?: string;
+  gender?: string;
+  birthyear?: string;
+  birthday?: string;
 }
 ```
 
@@ -220,7 +315,7 @@ interface KakaoLoginResult {
 | 에러 메시지 | 원인 |
 |------------|------|
 | `카카오 로그인 실패: ...` | 사용자 취소 또는 카카오 인증 오류 |
-| `사용자 정보 조회 실패: ...` | 카카오 API 호출 오류 |
+| `카카오 사용자 정보 조회 실패: ...` | 카카오 API 호출 오류 |
 | `카카오 사용자 ID를 가져올 수 없습니다` | 예상치 못한 응답 형식 |
 
 ---
@@ -263,6 +358,14 @@ interface KakaoLoginResult {
 
 디버그 키해시와 릴리즈 키해시를 각각 콘솔에 등록해야 합니다.
 
+### 동의 항목을 활성화했는데 필드가 `undefined`인 경우
+
+아래 순서로 확인하세요.
+
+1. 카카오 개발자 콘솔 → 앱 설정 → **카카오 로그인 → 동의 항목**에서 해당 항목이 **ON** 상태인지 확인
+2. 이미 로그인한 사용자는 동의 화면이 다시 뜨지 않을 수 있습니다. 카카오 연결을 해제 후 재로그인하여 새 동의를 받아야 합니다.
+3. 카카오 비즈앱 심사가 필요한 항목(이름, 전화번호 등)은 심사 전에는 테스트 계정에서만 동작합니다.
+
 ---
 
 ## License

package/android/src/main/java/com/capacitorkakaologin/KakaoLoginPlugin.kt

@@ -56,8 +56,20 @@ class KakaoLoginPlugin : Plugin() {
                     return@me
                 }
 
+                val account = user.kakaoAccount
+                val profile = account?.profile
+
                 val result = JSObject()
                 result.put("socialId", userId.toString())
+                profile?.nickname?.let           { result.put("nickname", it) }
+                profile?.profileImageUrl?.let    { result.put("profileImageUrl", it) }
+                profile?.thumbnailImageUrl?.let  { result.put("thumbnailImageUrl", it) }
+                account?.email?.let              { result.put("email", it) }
+                account?.name?.let               { result.put("name", it) }
+                account?.phoneNumber?.let        { result.put("phoneNumber", it) }
+                account?.gender?.let             { result.put("gender", it.name.lowercase()) }
+                account?.birthyear?.let          { result.put("birthyear", it) }
+                account?.birthday?.let           { result.put("birthday", it) }
                 call.resolve(result)
             }
         }

package/dist/esm/constants/version.js

@@ -1,2 +1,2 @@
-export const APP_VERSION = '0.1.8';
+export const APP_VERSION = '0.3.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/definitions.d.ts

@@ -3,11 +3,29 @@ export interface KakaoLoginPlugin {
      * 카카오 로그인을 실행한다.
      * - 카카오톡 앱이 설치된 경우: 앱을 통한 로그인
      * - 미설치 시: 카카오 계정 웹뷰 로그인
-     * @returns 카카오 사용자 고유 ID (socialId)
+     * @returns 카카오 사용자 정보. 동의한 스코프의 필드만 값이 채워진다.
      */
     login(): Promise<KakaoLoginResult>;
 }
 export interface KakaoLoginResult {
     /** 카카오 회원 고유 ID. 서버에 전달하여 사용자 식별에 사용한다. */
     socialId: string;
+    /** 닉네임. 카카오 개발자 콘솔에서 profile 동의 항목 활성화 필요. */
+    nickname?: string;
+    /** 프로필 이미지 URL. profile 동의 항목 활성화 필요. */
+    profileImageUrl?: string;
+    /** 썸네일 이미지 URL. profile 동의 항목 활성화 필요. */
+    thumbnailImageUrl?: string;
+    /** 이메일. account_email 동의 항목 활성화 필요. */
+    email?: string;
+    /** 실명. name 동의 항목 활성화 필요. */
+    name?: string;
+    /** 전화번호. phone_number 동의 항목 활성화 필요. */
+    phoneNumber?: string;
+    /** 성별. 'male' | 'female' | 'other'. gender 동의 항목 활성화 필요. */
+    gender?: string;
+    /** 출생연도 4자리 (예: '1990'). birthdate 동의 항목 활성화 필요. */
+    birthyear?: string;
+    /** 생일 MMDD 형식 (예: '0101'). birthdate 동의 항목 활성화 필요. */
+    birthday?: string;
 }

package/ios/Sources/Chuseok22CapacitorKakaoLogin/KakaoLoginPlugin.swift

@@ -77,7 +77,22 @@ public class KakaoLoginPlugin: CAPPlugin, CAPBridgedPlugin {
                     call.reject("카카오 사용자 ID를 가져올 수 없습니다")
                     return
                 }
-                call.resolve(["socialId": String(userId)])
+
+                let account = user?.kakaoAccount
+                let profile = account?.profile
+
+                var result: [String: Any] = ["socialId": String(userId)]
+                if let v = profile?.nickname           { result["nickname"] = v }
+                if let v = profile?.profileImageUrl    { result["profileImageUrl"] = v.absoluteString }
+                if let v = profile?.thumbnailImageUrl  { result["thumbnailImageUrl"] = v.absoluteString }
+                if let v = account?.email              { result["email"] = v }
+                if let v = account?.name               { result["name"] = v }
+                if let v = account?.phoneNumber        { result["phoneNumber"] = v }
+                if let v = account?.gender             { result["gender"] = v.rawValue }
+                if let v = account?.birthyear          { result["birthyear"] = v }
+                if let v = account?.birthday           { result["birthday"] = v }
+
+                call.resolve(result)
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chuseok22/capacitor-kakao-login",
-  "version": "0.1.8",
+  "version": "0.3.0",
   "description": "Capacitor plugin for Kakao social login (iOS & Android)",
   "main": "dist/plugin.cjs.js",
   "module": "dist/plugin.esm.mjs",