K-Auth Flutter #

한국 앱을 위한 소셜 로그인 SDK. 카카오, 네이버, 구글, 애플을 하나의 API로 구현하세요.

Next.js 버전: k-auth/next

왜 K-Auth인가요? #

설치 #

dependencies:
  k_auth: ^0.2.0

flutter pub add k_auth

빠른 시작 #

1. 초기화 #

import 'package:k_auth/k_auth.dart';

void main() {
  final kAuth = KAuth(
    config: KAuthConfig(
      kakao: KakaoConfig(appKey: 'YOUR_KAKAO_APP_KEY'),
      naver: NaverConfig(
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET',
        appName: 'Your App',
      ),
      google: GoogleConfig(),
      apple: AppleConfig(),
    ),
  );

  kAuth.initialize();
  runApp(MyApp());
}

2. 로그인 (함수형 스타일 권장) #

final result = await kAuth.signIn(AuthProvider.kakao);

// ✅ fold: 성공/실패 분기
result.fold(
  onSuccess: (user) => print('환영합니다, ${user.displayName}!'),
  onFailure: (error) => print('로그인 실패: $error'),
);

// ✅ when: 성공/취소/실패 세분화
result.when(
  success: (user) => navigateToHome(user),
  cancelled: () => showToast('로그인을 취소했습니다'),
  failure: (code, msg) => showError(msg),
);

// ✅ 체이닝
result
  .onSuccess((user) => saveUser(user))
  .onFailure((code, msg) => logError(msg));

// ✅ 값 추출
final name = result.mapUserOr((u) => u.displayName, 'Guest');

3. 인증 상태 감지 #

// Firebase Auth 스타일의 Stream
kAuth.authStateChanges.listen((user) {
  if (user != null) {
    print('로그인됨: ${user.displayName}');
  } else {
    print('로그아웃됨');
  }
});

4. 로그아웃 #

// 현재 로그인된 Provider로 자동 로그아웃
await kAuth.signOut();

// 또는 특정 Provider 지정
await kAuth.signOut(AuthProvider.kakao);

5. UI 버튼 #

// 개별 버튼
KakaoLoginButton(
  onPressed: () => kAuth.signInWithKakao(),
)

// 버튼 그룹
LoginButtonGroup(
  providers: kAuth.configuredProviders,
  onPressed: (provider) => kAuth.signIn(provider),
)

디버그 로깅 #

개발 중 디버깅을 위해 로그를 활성화할 수 있습니다:

// 개발 환경에서 로그 활성화
KAuthLogger.level = KAuthLogLevel.debug;

// 프로덕션에서는 비활성화 (기본값)
KAuthLogger.level = KAuthLogLevel.none;

// 커스텀 로거 (Firebase Crashlytics 등)
KAuthLogger.onLog = (event) {
  if (event.level == KAuthLogLevel.error) {
    FirebaseCrashlytics.instance.recordError(
      event.error,
      event.stackTrace,
      reason: event.message,
    );
  }
};

Provider 설정 #

카카오 #

KakaoConfig(
  appKey: 'YOUR_KAKAO_NATIVE_APP_KEY',  // Native App Key (REST API Key 아님!)
  collect: KakaoCollectOptions(
    email: true,      // 이메일
    profile: true,    // 닉네임, 프로필 이미지
    phone: false,     // 전화번호 (개발자센터 활성화 필요)
    birthday: false,  // 생일
    gender: false,    // 성별
  ),
)

📖 카카오 공식 문서

네이버 #

NaverConfig(
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  appName: 'Your App Name',
)

⚠️ 네이버는 scope 파라미터를 지원하지 않습니다. 수집 항목은 네이버 개발자센터에서 직접 설정하세요.

구글 #

GoogleConfig(
  iosClientId: 'YOUR_IOS_CLIENT_ID',      // iOS 필수
  serverClientId: 'YOUR_SERVER_CLIENT_ID', // 백엔드 연동 시
  forceConsent: true,                      // refresh token 획득
)

📖 Google Cloud Console

애플 #

AppleConfig(
  collect: AppleCollectOptions(
    email: true,
    fullName: true,  // 첫 로그인 시에만 제공
  ),
)

⚠️ iOS 13+, macOS에서만 지원됩니다.

API 레퍼런스 #

KAuthUser (표준화된 사용자 정보) #

AuthResult #

KAuth #

에러 처리 #

모든 에러는 한글 메시지와 해결 힌트를 포함합니다:

result.when(
  success: (user) => ...,
  cancelled: () => showToast('로그인을 취소했습니다'),
  failure: (code, message) {
    switch (code) {
      case ErrorCodes.networkError:
        showRetryDialog();
        break;
      case ErrorCodes.kakaoPhoneNotEnabled:
        // 힌트: 카카오 개발자센터에서 전화번호 수집을 활성화하세요
        showSettingsGuide();
        break;
      default:
        showError(message);
    }
  },
);

주요 에러 코드 #

플랫폼 설정 #

iOS (ios/Runner/Info.plist) #

<!-- 카카오 -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>kakao{YOUR_APP_KEY}</string>
    </array>
  </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>kakaokompassauth</string>
  <string>kakaolink</string>
</array>

<!-- 애플: Signing & Capabilities에서 "Sign in with Apple" 추가 -->

Android (android/app/src/main/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{YOUR_APP_KEY}" />
    </intent-filter>
</activity>

마이그레이션 #

0.1.x → 0.2.0 #

// Before
if (result.success) {
  print(result.user!.name);
} else {
  print(result.errorMessage);
}

// After (권장)
result.fold(
  onSuccess: (user) => print(user.name),
  onFailure: (error) => print(error),
);

// Before
await kAuth.signOut(AuthProvider.kakao);

// After (현재 Provider로 자동)
await kAuth.signOut();

라이선스 #

MIT License

관련 링크 #

• GitHub
• pub.dev
• 이슈 등록
• Contributing