소셜 로그인 연동

카카오, 네이버, 구글, 애플 로그인을 통합된 인터페이스로 구현합니다.

개요

Appify SDK는 네 가지 소셜 로그인 제공자를 단일 인터페이스로 제공합니다. 각 제공자는 appify.auth.<provider> 네임스페이스 아래에 위치하며, 모든 로그인 메서드는 동일한 AuthResult 타입을 반환합니다.

지원 제공자:

• 카카오 (kakao)
• 네이버 (naver)
• 구글 (google)
• 애플 (apple)

공통 응답 구조

모든 소셜 로그인 메서드는 Promise<AuthResult>를 반환합니다.

interface AuthResult {
  success: boolean;
  accessToken?: string;
  refreshToken?: string;
  idToken?: string;
  user?: {
    id?: string;
    email?: string;
    name?: string;
    profileImage?: string;
  };
  error?: string;
}

필드	타입	설명
success	boolean	로그인 성공 여부. 항상 존재합니다.
accessToken	string	제공자 액세스 토큰. 서버에서 반드시 검증해야 합니다.
refreshToken	string	액세스 토큰 갱신에 사용합니다. 제공자에 따라 없을 수 있습니다.
idToken	string	OIDC ID 토큰. 구글, 애플에서 제공합니다.
user.id	string	제공자 기준 사용자 고유 식별자.
user.email	string	사용자 이메일. 제공자 설정에 따라 없을 수 있습니다.
user.name	string	사용자 이름.
user.profileImage	string	프로필 이미지 URL.
error	string	success가 false일 때 오류 메시지.

카카오 로그인

카카오 로그인은 카카오톡 앱이 설치된 환경에서는 앱 로그인을, 미설치 환경에서는 카카오 웹 로그인으로 자동 전환합니다. 별도 분기 처리 없이 login()을 호출하면 SDK가 환경을 감지해 적절한 방식으로 인증합니다.

로그인

import appify from '@nolraunsoft/appify-sdk';

async function kakaoLogin() {
  const result = await appify.auth.kakao.login();

  if (result.success) {
    console.log('카카오 로그인 성공');
    console.log('사용자 ID:', result.user?.id);
    console.log('이메일:', result.user?.email);
    // result.accessToken을 서버로 전송해 검증하세요
  } else {
    console.error('카카오 로그인 실패:', result.error);
  }
}

로그아웃

async function kakaoLogout() {
  const success = await appify.auth.kakao.logout();

  if (success) {
    console.log('카카오 로그아웃 완료');
  }
}

연동 해제

연동 해제는 사용자와 앱 간의 카카오 계정 연결을 끊습니다. 로그아웃과 달리 서비스 탈퇴 시 사용합니다.

async function kakaoUnlink() {
  const success = await appify.auth.kakao.unlink();

  if (success) {
    console.log('카카오 연동 해제 완료');
  }
}

네이버 로그인

네이버 로그인은 카카오와 동일한 패턴을 사용합니다.

로그인

async function naverLogin() {
  const result = await appify.auth.naver.login();

  if (result.success) {
    console.log('네이버 로그인 성공');
    console.log('사용자 이름:', result.user?.name);
  } else {
    console.error('네이버 로그인 실패:', result.error);
  }
}

로그아웃

async function naverLogout() {
  const success = await appify.auth.naver.logout();

  if (success) {
    console.log('네이버 로그아웃 완료');
  }
}

연동 해제

async function naverUnlink() {
  const success = await appify.auth.naver.unlink();

  if (success) {
    console.log('네이버 연동 해제 완료');
  }
}

구글 로그인

구글 로그인은 OIDC 프로토콜을 사용하므로 idToken이 함께 반환됩니다. 서버에서 사용자를 식별할 때 idToken을 활용할 수 있습니다.

로그인

async function googleLogin() {
  const result = await appify.auth.google.login();

  if (result.success) {
    console.log('구글 로그인 성공');
    console.log('ID 토큰:', result.idToken);
    // idToken을 서버로 전송해 Google API로 검증하세요
  } else {
    console.error('구글 로그인 실패:', result.error);
  }
}

로그아웃

async function googleLogout() {
  const success = await appify.auth.google.logout();

  if (success) {
    console.log('구글 로그아웃 완료');
  }
}

연동 해제

async function googleUnlink() {
  const success = await appify.auth.google.unlink();

  if (success) {
    console.log('구글 연동 해제 완료');
  }
}

애플 로그인

애플 로그인은 다른 제공자와 두 가지 차이점이 있습니다.

첫째, login()이 반환하는 타입이 AppleAuthResult입니다. identityToken과 authorizationCode가 추가로 포함됩니다.

interface AppleAuthResult extends AuthResult {
  identityToken?: string;
  authorizationCode?: string;
}

둘째, 로그아웃과 연동 해제는 운영 체제가 관리하므로 SDK에서 별도 메서드를 제공하지 않습니다. iOS에서는 설정 앱에서, Android에서는 Google Play 설정에서 처리합니다.

플랫폼별 동작 차이도 있습니다. iOS에서는 네이티브 Sign in with Apple 시트가 표시됩니다. Android에서는 웹 기반 OAuth 플로우가 실행됩니다.

로그인

import appify from '@nolraunsoft/appify-sdk';
import type { AppleAuthResult } from '@nolraunsoft/appify-sdk';

async function appleLogin() {
  const result: AppleAuthResult = await appify.auth.apple.login();

  if (result.success) {
    console.log('애플 로그인 성공');
    console.log('Identity Token:', result.identityToken);
    console.log('Authorization Code:', result.authorizationCode);
    // identityToken을 서버로 전송해 Apple API로 검증하세요
  } else {
    console.error('애플 로그인 실패:', result.error);
  }
}

통합 로그인 버튼 구현 예제

네 가지 제공자를 하나의 함수에서 처리하는 패턴입니다.

import appify from '@nolraunsoft/appify-sdk';
import type { AuthResult } from '@nolraunsoft/appify-sdk';

type SocialProvider = 'kakao' | 'naver' | 'google' | 'apple';

async function socialLogin(provider: SocialProvider): Promise<AuthResult> {
  switch (provider) {
    case 'kakao':
      return appify.auth.kakao.login();
    case 'naver':
      return appify.auth.naver.login();
    case 'google':
      return appify.auth.google.login();
    case 'apple':
      return appify.auth.apple.login();
  }
}

// 사용 예시
async function handleLoginButton(provider: SocialProvider) {
  try {
    const result = await socialLogin(provider);

    if (!result.success) {
      // 사용자에게 오류를 표시합니다
      showErrorMessage(result.error ?? '로그인에 실패했습니다.');
      return;
    }

    // 서버로 토큰을 전송해 세션을 생성합니다
    await createServerSession({
      provider,
      accessToken: result.accessToken,
      idToken: result.idToken,
    });

    navigateToHome();
  } catch (error) {
    // 네트워크 오류 등 예기치 못한 예외를 처리합니다
    showErrorMessage('로그인 중 오류가 발생했습니다. 다시 시도해 주세요.');
    console.error(`[${provider}] 로그인 예외:`, error);
  }
}

서버 연동 시 주의사항

클라이언트에서 받은 토큰을 그대로 신뢰해서는 안 됩니다. 모든 토큰은 서버에서 각 제공자의 API를 통해 검증해야 합니다.

accessToken 검증

카카오, 네이버는 accessToken을 각 제공자의 사용자 정보 API에 전송해 유효성을 확인합니다.

GET https://kapi.kakao.com/v2/user/me
Authorization: Bearer {accessToken}

idToken / identityToken 검증

구글과 애플은 JWT 형태의 토큰을 반환합니다. 서버에서 공개 키로 서명을 검증합니다.

• 구글: https://oauth2.googleapis.com/tokeninfo?id_token={idToken}
• 애플: https://appleid.apple.com/auth/keys 엔드포인트의 공개 키로 identityToken을 검증합니다.

authorizationCode 활용 (애플)

애플의 authorizationCode는 일회성입니다. 서버에서 https://appleid.apple.com/auth/token으로 교환해 refresh_token을 발급받아 저장합니다. 이후 사용자 연동 해제 시 이 refresh_token이 필요합니다.

에러 처리

SDK 메서드는 네트워크 오류나 예기치 못한 상황에서 예외를 던질 수 있습니다. result.success가 false인 경우와 예외 발생을 모두 처리하는 패턴을 권장합니다.

async function loginWithErrorHandling(provider: SocialProvider) {
  let result: AuthResult;

  try {
    result = await socialLogin(provider);
  } catch (error) {
    // SDK 자체의 예외: 네트워크 단절, 앱 설정 오류 등
    console.error('로그인 중 예외 발생:', error);
    return;
  }

  if (!result.success) {
    // 제공자가 반환한 인증 실패: 사용자 취소, 권한 거부 등
    console.warn(`로그인 실패 (${provider}):`, result.error);
    return;
  }

  // 로그인 성공 처리
  console.log('로그인 성공:', result.user?.name);
}

result.error 필드는 사용자가 로그인 창을 취소했거나 제공자 서버에서 거부한 경우에 오류 사유를 담습니다. 이 값을 그대로 사용자에게 노출하지 말고, 앱에 맞는 메시지로 변환해 표시하는 것을 권장합니다.