@chuseok22/capacitor-kakao-login 0.1.4 → 0.1.6

package/README.md

@@ -1,65 +1,122 @@
 # @chuseok22/capacitor-kakao-login
 
-Capacitor 앱에서 카카오 소셜 로그인을 `npm install` + `npx cap sync` 만으로 쉽게 사용할 수 있는 플러그인입니다. iOS와 Android 모두 지원합니다.
+Capacitor 앱에서 카카오 소셜 로그인을 최소한의 설정으로 사용할 수 있는 플러그인입니다.
 
-## 왜 이 패키지가 필요한가
+- iOS / Android 지원
+- 카카오톡 앱 로그인 우선, 미설치 시 카카오 계정 웹뷰 로그인으로 자동 폴백
+- Capacitor 6.x 이상
 
-`npx cap sync` 실행 시 Capacitor CLI는 `node_modules/` 내 npm 패키지만 플러그인으로 스캔합니다. 로컬 Swift 파일은 자동으로 `packageClassList`에 등록되지 않아 `UNIMPLEMENTED` 에러가 발생합니다. 이 패키지는 올바른 Capacitor 플러그인 구조를 갖추어 `npx cap sync`만으로 자동 등록되게 합니다.
+---
 
-## 설치
+## 빠른 시작
+
+**사용자가 해야 할 일은 총 4가지입니다.**
 
-```bash
-npm install @chuseok22/capacitor-kakao-login
-npx cap sync
+```
+1. npm install + cap sync
+2. capacitor.config.ts에 appKey 설정
+3. iOS Info.plist에 URL 스킴 등록
+4. Android build.gradle에 manifestPlaceholders 1줄 추가
 ```
 
-## 사용법
+SDK 초기화, URL 핸들러 등록, AuthCodeHandlerActivity는 플러그인이 자동으로 처리합니다.
 
-```typescript
-import { KakaoLogin } from '@chuseok22/capacitor-kakao-login';
+---
 
-try {
-  const { socialId } = await KakaoLogin.login();
-  console.log('카카오 사용자 ID:', socialId);
-} catch (error) {
-  console.error('카카오 로그인 실패:', error);
-}
-```
+## 목차
 
-## iOS 설정
+1. [사전 요구사항](#1-사전-요구사항)
+2. [카카오 개발자 콘솔 설정](#2-카카오-개발자-콘솔-설정)
+3. [설치](#3-설치)
+4. [앱 키 설정 (공통)](#4-앱-키-설정-공통)
+5. [iOS 설정](#5-ios-설정)
+6. [Android 설정](#6-android-설정)
+7. [사용법](#7-사용법)
+8. [API](#8-api)
+9. [지원 플랫폼](#9-지원-플랫폼)
+10. [트러블슈팅](#10-트러블슈팅)
 
-### 1. KakaoSDK 초기화 (`AppDelegate.swift`)
+---
 
-```swift
-import KakaoSDKCommon
+## 1. 사전 요구사항
 
-func application(_ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-    KakaoSDK.initSDK(appKey: "YOUR_NATIVE_APP_KEY")
-    return true
-}
+| 항목 | 최소 버전 |
+|------|-----------|
+| Capacitor | 6.x 이상 |
+| iOS | 13.0 이상 |
+| Android | API 22 (Android 5.1) 이상 |
+
+---
+
+## 2. 카카오 개발자 콘솔 설정
+
+### 2-1. 앱 등록 및 네이티브 앱 키 발급
+
+1. [카카오 개발자 콘솔](https://developers.kakao.com) → **내 애플리케이션 → 애플리케이션 추가하기**
+2. 앱 이름, 회사명 입력 후 저장
+3. **앱 키** 탭에서 **네이티브 앱 키** 복사
+
+### 2-2. 플랫폼 등록
+
+**iOS:** 앱 설정 → 플랫폼 → iOS 플랫폼 등록 → **번들 ID** 입력 (Xcode 프로젝트의 Bundle Identifier)
+
+**Android:** 앱 설정 → 플랫폼 → Android 플랫폼 등록 → **패키지명** 입력 + **키 해시** 등록
+
+> **키 해시 추출 (개발용):**
+> ```bash
+> keytool -exportcert -alias androiddebugkey \
+>   -keystore ~/.android/debug.keystore \
+>   -storepass android -keypass android \
+>   | openssl sha1 -binary | openssl base64
+> ```
+
+### 2-3. 카카오 로그인 활성화
+
+앱 설정 → **카카오 로그인 → 활성화 설정 → ON**
+
+---
+
+## 3. 설치
+
+```bash
+npm install @chuseok22/capacitor-kakao-login
+npx cap sync
 ```
 
-### 2. URL 핸들러 등록 (`AppDelegate.swift`)
+---
 
-```swift
-import KakaoSDKAuth
+## 4. 앱 키 설정 (공통)
 
-func application(_ app: UIApplication, open url: URL,
-    options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
-    if AuthApi.isKakaoTalkLoginUrl(url) {
-        return AuthController.handleOpenUrl(url: url)
+`capacitor.config.ts`에 카카오 네이티브 앱 키를 설정합니다.  
+플러그인이 이 값을 읽어 iOS/Android 모두 SDK를 자동 초기화합니다.
+
+```typescript
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',
+  appName: 'My App',
+  webDir: 'dist',
+  plugins: {
+    KakaoLogin: {
+      appKey: 'YOUR_NATIVE_APP_KEY'   // ← 여기에 네이티브 앱 키 입력
     }
-    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
-}
+  }
+};
+
+export default config;
 ```
 
-### 3. `Info.plist` 설정
+---
+
+## 5. iOS 설정
+
+**AppDelegate 수정 없이 Info.plist만 설정하면 됩니다.**
 
-카카오톡 앱 연동 및 URL 스킴을 등록합니다.
+`ios/App/App/Info.plist`에 아래 항목을 추가합니다.
 
 ```xml
-<!-- 카카오톡 앱 링크 허용 -->
+<!-- 카카오톡 설치 여부 확인을 위한 URL 스킴 허용 -->
 <key>LSApplicationQueriesSchemes</key>
 <array>
   <string>kakaokompassauth</string>
@@ -67,98 +124,93 @@ func application(_ app: UIApplication, open url: URL,
   <string>kakaolink</string>
 </array>
 
-<!-- 앱 URL 스킴 등록 (kakao + 네이티브 앱 키) -->
+<!-- OAuth 콜백 수신을 위한 커스텀 URL 스킴 등록 -->
 <key>CFBundleURLTypes</key>
 <array>
   <dict>
     <key>CFBundleURLSchemes</key>
     <array>
-      <string>kakao{NATIVE_APP_KEY}</string>
+      <string>kakaoYOUR_NATIVE_APP_KEY</string>
     </array>
   </dict>
 </array>
 ```
 
-`{NATIVE_APP_KEY}`를 [카카오 개발자 콘솔](https://developers.kakao.com)의 네이티브 앱 키로 교체하세요.
+`YOUR_NATIVE_APP_KEY`를 실제 네이티브 앱 키로 교체하세요.  
+예: 앱 키가 `abc1234567` 이면 → `kakaoabc1234567`
 
-## Android 설정
+> **왜 Info.plist는 직접 수정해야 하나요?**  
+> iOS는 외부 패키지가 호스트 앱의 Info.plist를 수정할 수 없습니다. 이 2가지 항목은 OS 제약상 불가피하게 수동 설정이 필요합니다.
 
-### 0. Kotlin Gradle 플러그인 classpath 추가
+---
 
-`android/build.gradle`의 `buildscript` 블록에 Kotlin 플러그인 classpath를 추가합니다.
+## 6. Android 설정
+
+**Application 클래스 생성, AndroidManifest 수정 없이 build.gradle 1줄만 추가하면 됩니다.**
+
+`android/app/build.gradle`의 `defaultConfig` 블록에 아래 한 줄을 추가합니다.
 
 ```groovy
-buildscript {
-    repositories {
-        google()
-        mavenCentral()
-    }
-    dependencies {
-        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21'
+android {
+    defaultConfig {
+        // 기존 항목들 유지...
+
+        manifestPlaceholders = [kakaoNativeAppKey: "YOUR_NATIVE_APP_KEY"]  // ← 이 줄만 추가
     }
 }
 ```
 
-> 이 단계가 없으면 `cap add android` 또는 `cap sync` 후 Gradle sync 오류가 발생합니다.
+`YOUR_NATIVE_APP_KEY`를 실제 네이티브 앱 키로 교체하세요.
 
-### 1. KakaoSDK 초기화 (`Application` 클래스)
+> **이것만으로 충분한 이유:**
+> - `AuthCodeHandlerActivity`는 플러그인 AndroidManifest에 선언되어 Gradle이 자동으로 호스트 앱 Manifest에 병합합니다.
+> - `KakaoSdk.init()`는 플러그인 `load()` 시 자동으로 호출됩니다.
 
-`Application` 서브클래스를 생성하고 KakaoSDK를 초기화합니다.
+### Kotlin Gradle 플러그인 (필요한 경우)
 
-```kotlin
-import com.kakao.sdk.common.KakaoSdk
+Gradle sync 오류가 발생하면 `android/build.gradle`의 `buildscript.dependencies`에 아래를 추가하세요.
 
-class MyApplication : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        KakaoSdk.init(this, "YOUR_NATIVE_APP_KEY")
-    }
-}
+```groovy
+classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21'
 ```
 
-`AndroidManifest.xml`에 Application 클래스를 등록합니다:
-
-```xml
-<application
-    android:name=".MyApplication"
-    ...>
-```
+---
 
-### 2. `AndroidManifest.xml` — 카카오 로그인 Activity 등록
+## 7. 사용법
 
-카카오 계정 웹뷰 로그인 후 앱으로 돌아오기 위한 Activity를 등록합니다.
+```typescript
+import { KakaoLogin } from '@chuseok22/capacitor-kakao-login';
 
-```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{NATIVE_APP_KEY}" />
-  </intent-filter>
-</activity>
+async function loginWithKakao() {
+  try {
+    const { socialId } = await KakaoLogin.login();
+    // socialId를 서버에 전달해 사용자 인증 처리
+    await authenticateWithServer(socialId);
+  } catch (error) {
+    console.error('카카오 로그인 실패:', error);
+  }
+}
 ```
 
-`{NATIVE_APP_KEY}`를 [카카오 개발자 콘솔](https://developers.kakao.com)의 네이티브 앱 키로 교체하세요.
+---
 
-## API
+## 8. API
 
-### `login() → Promise<KakaoLoginResult>`
+### `KakaoLogin.login()`
 
-카카오 로그인을 실행합니다.
+```typescript
+login(): Promise<KakaoLoginResult>
+```
 
-- 카카오톡 앱이 설치된 경우: 카카오톡 앱을 통한 로그인
-- 미설치 시: 카카오 계정 웹뷰 로그인
+**동작:**
+- 카카오톡 설치 → 카카오톡 앱 로그인
+- 카카오톡 미설치 → 카카오 계정 웹뷰 로그인 (자동 폴백)
 
 **반환값:**
 
 ```typescript
 interface KakaoLoginResult {
-  /** 카카오 회원 고유 ID. 서버 사용자 식별에 사용합니다. */
+  /** 카카오 회원 고유 ID. 서버에서 사용자를 식별하는 데 사용합니다. */
   socialId: string;
 }
 ```
@@ -171,13 +223,47 @@ interface KakaoLoginResult {
 | `사용자 정보 조회 실패: ...` | 카카오 API 호출 오류 |
 | `카카오 사용자 ID를 가져올 수 없습니다` | 예상치 못한 응답 형식 |
 
-## 지원 플랫폼
+---
+
+## 9. 지원 플랫폼
+
+| 플랫폼 | 지원 | 최소 버전 |
+|--------|------|-----------|
+| iOS | ✅ | iOS 13.0+ |
+| Android | ✅ | API 22+ |
+| Web | ❌ | — |
+
+---
+
+## 10. 트러블슈팅
+
+### `appKey is not set` 경고가 콘솔에 출력되는 경우
+
+`capacitor.config.ts`의 `plugins.KakaoLogin.appKey`가 설정되어 있는지 확인하세요.  
+설정 후 `npx cap sync`를 다시 실행해야 반영됩니다.
+
+### iOS — 카카오톡 앱 로그인 후 앱으로 돌아오지 않는 경우
+
+`Info.plist`의 `CFBundleURLSchemes`에 `kakao{네이티브앱키}` 형식으로 등록되어 있는지 확인하세요.
+
+### iOS — `UNIMPLEMENTED` 에러
+
+`npx cap sync`를 다시 실행하고, Xcode에서 **Product → Clean Build Folder** 후 재빌드하세요.
+
+### Android — Gradle sync 오류 (`Unresolved reference: kotlin`)
+
+`android/build.gradle`의 `buildscript.dependencies`에 Kotlin 플러그인 classpath를 추가하세요. ([6번 참고](#6-android-설정))
+
+### Android — 로그인 후 앱으로 돌아오지 않는 경우
+
+`android/app/build.gradle`의 `manifestPlaceholders`에 앱 키가 올바르게 입력되어 있는지 확인하세요.  
+값을 변경하면 `npx cap sync` 후 앱을 다시 빌드해야 합니다.
+
+### 카카오 개발자 콘솔 — 키 해시 불일치 오류 (Android)
+
+디버그 키해시와 릴리즈 키해시를 각각 콘솔에 등록해야 합니다.
 
-| 플랫폼 | 지원 |
-|--------|------|
-| iOS | ✅ iOS 13+ |
-| Android | ✅ API 22+ |
-| Web | ❌ 미지원 (네이티브 전용) |
+---
 
 ## License
 

package/android/src/main/AndroidManifest.xml

@@ -1,3 +1,24 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!--
+        Gradle manifest merging으로 호스트 앱의 AndroidManifest.xml에 자동 주입된다.
+        사용자는 android/app/build.gradle에 다음 한 줄만 추가하면 된다:
+            manifestPlaceholders = [kakaoNativeAppKey: "YOUR_NATIVE_APP_KEY"]
+    -->
+    <application>
+        <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${kakaoNativeAppKey}" />
+            </intent-filter>
+        </activity>
+    </application>
+
 </manifest>

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

@@ -6,15 +6,32 @@ import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
 import com.kakao.sdk.auth.model.OAuthToken
+import com.kakao.sdk.common.KakaoSdk
 import com.kakao.sdk.user.UserApiClient
 
 // name 값은 TypeScript registerPlugin('KakaoLogin', ...) 과 반드시 일치해야 한다
 @CapacitorPlugin(name = "KakaoLogin")
 class KakaoLoginPlugin : Plugin() {
 
+    /**
+     * 플러그인 로드 시 KakaoSDK를 자동 초기화한다.
+     * capacitor.config.ts의 plugins.KakaoLogin.appKey 값을 읽는다.
+     * Application 서브클래스를 별도로 만들 필요가 없다.
+     */
+    override fun load() {
+        val appKey = config.getString("appKey")
+        if (appKey.isNullOrBlank()) {
+            println("[KakaoLoginPlugin] ⚠️ appKey가 capacitor.config.ts에 설정되지 않았습니다.")
+            println("[KakaoLoginPlugin]   plugins: { KakaoLogin: { appKey: 'YOUR_NATIVE_APP_KEY' } }")
+            return
+        }
+
+        // Application context 사용 — KakaoSdk.init은 앱 수명 동안 유지되어야 하므로
+        KakaoSdk.init(context, appKey)
+    }
+
     @PluginMethod
     fun login(call: PluginCall) {
-        // ApplicationContext 대신 Activity 사용 — startActivity() 호출이 내부적으로 필요하기 때문
         val activity = activity ?: run {
             call.reject("Activity를 사용할 수 없습니다")
             return

package/dist/esm/constants/version.js

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

package/ios/Sources/Chuseok22CapacitorKakaoLogin/KakaoLoginPlugin.swift

@@ -1,11 +1,9 @@
 import Foundation
 import Capacitor
+import KakaoSDKCommon
 import KakaoSDKAuth
 import KakaoSDKUser
 
-/// Capacitor 플러그인 — 카카오 소셜 로그인
-/// @objc(KakaoLoginPlugin)과 identifier는 Capacitor JS 브릿지 식별자로 변경 불가.
-/// SPM 모듈명은 Chuseok22CapacitorKakaoLogin이나, 플러그인 등록명은 KakaoLoginPlugin을 유지한다.
 @objc(KakaoLoginPlugin)
 public class KakaoLoginPlugin: CAPPlugin, CAPBridgedPlugin {
 
@@ -15,15 +13,32 @@ public class KakaoLoginPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "login", returnType: CAPPluginReturnPromise)
     ]
 
+    public override func load() {
+        guard let appKey = getConfigValue("appKey") as? String, !appKey.isEmpty else {
+            print("[KakaoLoginPlugin] ⚠️ appKey가 capacitor.config.ts에 설정되지 않았습니다.")
+            print("[KakaoLoginPlugin]   plugins: { KakaoLogin: { appKey: 'YOUR_NATIVE_APP_KEY' } }")
+            return
+        }
+        KakaoSDK.initSDK(appKey: appKey)
+        // handleOpenUrl 오버라이드로 URL 처리 — ApplicationDelegateProxy.add() 불필요
+    }
+
+    // Capacitor가 AppDelegate.application(_:open:options:)를 플러그인으로 라우팅
+    @objc public override func handleOpenUrl(_ url: URL, _ options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
+        guard AuthApi.isKakaoTalkLoginUrl(url) else { return false }
+        // AuthController.handleOpenUrl은 @MainActor — URL 콜백은 메인 스레드 보장
+        return MainActor.assumeIsolated {
+            AuthController.handleOpenUrl(url: url)
+        }
+    }
+
     @objc func login(_ call: CAPPluginCall) {
         DispatchQueue.main.async {
             if UserApi.isKakaoTalkLoginAvailable() {
-                // 카카오톡 앱 로그인
                 UserApi.shared.loginWithKakaoTalk { [weak self] oauthToken, error in
                     self?.handleLoginResult(call: call, oauthToken: oauthToken, error: error)
                 }
             } else {
-                // 카카오 계정 웹뷰 로그인 (카카오톡 미설치 환경)
                 UserApi.shared.loginWithKakaoAccount { [weak self] oauthToken, error in
                     self?.handleLoginResult(call: call, oauthToken: oauthToken, error: error)
                 }
@@ -45,12 +60,10 @@ public class KakaoLoginPlugin: CAPPlugin, CAPBridgedPlugin {
                     call.reject("카카오 사용자 정보 조회 실패", nil, error)
                     return
                 }
-
                 guard let userId = user?.id else {
                     call.reject("카카오 사용자 ID를 가져올 수 없습니다")
                     return
                 }
-
                 call.resolve(["socialId": String(userId)])
             }
         }

package/package.json

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

package/ios/Sources/KakaoLoginPlugin/KakaoLoginPlugin.swift

@@ -1,3 +0,0 @@
-// 이 파일은 더 이상 사용되지 않습니다.
-// 소스는 ios/Sources/Chuseok22CapacitorKakaoLogin/KakaoLoginPlugin.swift 로 이동되었습니다.
-// This file is intentionally left empty to prevent duplicate symbol compilation errors.