abc-waas-prebuiltui-sdk

v0.3.3

Published

2 months ago

ABC WaaS Prebuilt UI SDK for React/Next.js

0High
0Medium
0Low

dev.pyoungwoo

abc waas prebuilt sdk ui react

ABC WaaS Prebuilt UI SDK

ABC WaaS SDK를 위한 미리 만들어진 UI 컴포넌트 라이브러리입니다. abc-waas-core-sdk의 모든 기능을 포함하며, 별도로 abc-waas-core-sdk를 설치할 필요가 없습니다.

✨ 주요 기능

🔐 5개 소셜 로그인 지원: Google, Apple, Naver, Kakao, LINE
🎨 완성된 UI 컴포넌트: 별도 스타일링 없이 바로 사용 가능
📱 반응형 디자인: 모바일과 데스크톱 모두 지원
🚀 TypeScript 지원: 완벽한 타입 안전성
🔧 간편한 설정: 환경 변수만으로 모든 기능 사용 가능
📦 번들 최적화: Tree shaking과 코드 분할 지원
🌐 크로스 브라우저 호환성: 모든 브라우저에서 안전하게 작동
🔒 보안 강화: 암호학적으로 안전한 UUID 생성 및 JWT 토큰 검증
🌍 다국어 지원: 한국어/영어 언어 전환 기능
🎯 커스텀 Hook: 언어 관리를 위한 useLanguage Hook 제공
🔄 실시간 상태 관리: 로그인/로그아웃 상태 실시간 추적
🎭 로딩 애니메이션: 사용자 경험을 향상시키는 로딩 상태 표시

📋 목차

🚀 설치

npm install abc-waas-prebuiltui-sdk

또는

yarn add abc-waas-prebuiltui-sdk

또는

pnpm add abc-waas-prebuiltui-sdk

🏃‍♂️ 빠른 시작

1. Provider 설정

import React from "react";
import { AbcWaasProvider } from "abc-waas-prebuiltui-sdk";

const config = {
  API_WAAS_MYABCWALLET_URL: "https://dev-api.waas.myabcwallet.com",
  MW_MYABCWALLET_URL: "https://mw.myabcwallet.com",
  CLIENT_ID: "your_client_id_here",
  CLIENT_SECRET: "your_client_secret_here",
};

function App() {
  return (
    <AbcWaasProvider config={config}>
      <YourApp />
    </AbcWaasProvider>
  );
}

export default App;

2. 로그인 컴포넌트 사용

import { Login } from "abc-waas-prebuiltui-sdk";

function LoginPage() {
  return <Login />;
}

3. 로그아웃 컴포넌트 사용

import { Logout } from "abc-waas-prebuiltui-sdk";

function UserProfile() {
  return <Logout />;
}

📖 사용법

기본 컴포넌트

Login 컴포넌트

로그인 페이지에서 사용할 수 있는 완성된 로그인 UI입니다.

import { Login } from "abc-waas-prebuiltui-sdk";

function LoginPage() {
  return (
    <div>
      <h1>로그인</h1>
      <Login />
    </div>
  );
}

특징:

5개 소셜 로그인 제공자 지원 (Google, Apple, Naver, Kakao, LINE)
언어 전환 기능 (한국어/영어)
로딩 상태 표시
반응형 디자인
브랜드 일관성 유지

Logout 컴포넌트

사용자 프로필이나 설정 페이지에서 사용할 수 있는 로그아웃 버튼입니다.

import { Logout } from "abc-waas-prebuiltui-sdk";

function UserProfile() {
  return (
    <div>
      <h2>사용자 정보</h2>
      <Logout />
    </div>
  );
}

특징:

로그인 상태에 따른 버튼 활성화/비활성화
로딩 상태 표시
다국어 지원

커스텀 Hook

useLanguage Hook

언어 설정을 관리하는 Hook입니다.

import { useLanguage } from "abc-waas-prebuiltui-sdk";

function LanguageSelector() {
  const { language, setLanguage } = useLanguage();

  return (
    <div>
      <p>현재 언어: {language}</p>
      <button onClick={() => setLanguage("ko")}>한국어</button>
      <button onClick={() => setLanguage("en")}>English</button>
    </div>
  );
}

기능:

현재 언어 상태 관리
언어 변경 함수 제공
localStorage를 통한 언어 설정 영구 저장
브라우저 간 언어 설정 동기화

🔧 API Reference

컴포넌트

`<Login />`

로그인 UI 컴포넌트

Props: 없음 (환경 변수로 설정)

환경 변수:

REACT_APP_GOOGLE_CLIENT_ID: Google OAuth 클라이언트 ID
REACT_APP_GOOGLE_CLIENT_SECRET: Google OAuth 클라이언트 시크릿
REACT_APP_GOOGLE_REDIRECT_URI: Google OAuth 리다이렉트 URI
REACT_APP_APPLE_CLIENT_ID: Apple OAuth 클라이언트 ID
REACT_APP_APPLE_REDIRECT_URI: Apple OAuth 리다이렉트 URI
REACT_APP_APPLE_TEAM_ID: Apple Developer 팀 ID
REACT_APP_APPLE_KEY_ID: Apple Developer 키 ID
REACT_APP_APPLE_PRIVATE_KEY: Apple Developer 프라이빗 키
REACT_APP_NAVER_CLIENT_ID: Naver OAuth 클라이언트 ID
REACT_APP_NAVER_CLIENT_SECRET: Naver OAuth 클라이언트 시크릿
REACT_APP_NAVER_REDIRECT_URI: Naver OAuth 리다이렉트 URI
REACT_APP_KAKAO_REST_API_KEY: Kakao REST API 키
REACT_APP_KAKAO_REDIRECT_URI: Kakao OAuth 리다이렉트 URI
REACT_APP_LINE_CLIENT_ID: LINE OAuth 클라이언트 ID
REACT_APP_LINE_CLIENT_SECRET: LINE OAuth 클라이언트 시크릿
REACT_APP_LINE_REDIRECT_URI: LINE OAuth 리다이렉트 URI

`<Logout />`

로그아웃 버튼 컴포넌트

Props: 없음

Hook

`useLanguage()`

언어 설정을 관리하는 Hook

반환값:

{
  language: "ko" | "en";
  setLanguage: (language: "ko" | "en") => void;
}

타입

`UseLanguageType`

type UseLanguageType = "ko" | "en";

🌍 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 다음 환경 변수들을 설정하세요:

# Google OAuth
REACT_APP_GOOGLE_CLIENT_ID=your_google_client_id
REACT_APP_GOOGLE_CLIENT_SECRET=your_google_client_secret
REACT_APP_GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback

# Apple OAuth
REACT_APP_APPLE_CLIENT_ID=your_apple_client_id
REACT_APP_APPLE_REDIRECT_URI=http://localhost:3000/auth/apple/callback
REACT_APP_APPLE_TEAM_ID=your_apple_team_id
REACT_APP_APPLE_KEY_ID=your_apple_key_id
REACT_APP_APPLE_PRIVATE_KEY=your_apple_private_key

# Naver OAuth
REACT_APP_NAVER_CLIENT_ID=your_naver_client_id
REACT_APP_NAVER_CLIENT_SECRET=your_naver_client_secret
REACT_APP_NAVER_REDIRECT_URI=http://localhost:3000/auth/naver/callback

# Kakao OAuth
REACT_APP_KAKAO_REST_API_KEY=your_kakao_rest_api_key
REACT_APP_KAKAO_REDIRECT_URI=http://localhost:3000/auth/kakao/callback

# LINE OAuth
REACT_APP_LINE_CLIENT_ID=your_line_client_id
REACT_APP_LINE_CLIENT_SECRET=your_line_client_secret
REACT_APP_LINE_REDIRECT_URI=http://localhost:3000/auth/line/callback

🔐 지원하는 소셜 서비스

Google

OAuth 2.0 기반 인증
이메일 정보 수집
토큰 검증 및 사용자 정보 조회
스코프: https://www.googleapis.com/auth/userinfo.email

Apple

Sign in with Apple 지원
JWT 토큰 검증
프라이버시 보호 이메일 지원
스코프: name email
프록시 서버: /proxy/apple/token 사용

Naver

네이버 아이디로 로그인 지원
OAuth 2.0 기반 인증
사용자 프로필 정보 수집
프록시 서버: /proxy/naver/token, /proxy/naver/tokeninfo 사용

Kakao

카카오 로그인 지원
JWT 토큰 검증
사용자 정보 및 이메일 수집
스코프: account_email openid

LINE

LINE 로그인 지원
OAuth 2.0 기반 인증
프로필 정보 수집
스코프: profile openid email

🏗️ 아키텍처

프로젝트 구조

src/
├── components/          # UI 컴포넌트
│   ├── Login.tsx       # 로그인 컴포넌트
│   └── Logout.tsx       # 로그아웃 컴포넌트
├── hooks/              # 커스텀 Hook
│   └── useLanguage.ts  # 언어 관리 Hook
├── types/              # TypeScript 타입 정의
│   ├── language.ts     # 언어 타입
│   └── svg.d.ts        # SVG 모듈 타입
├── utilities/          # 유틸리티 함수
│   ├── common.ts       # 공통 유틸리티
│   ├── google.ts       # Google OAuth 유틸리티
│   ├── apple.ts        # Apple OAuth 유틸리티
│   ├── naver.ts        # Naver OAuth 유틸리티
│   ├── kakao.ts        # Kakao OAuth 유틸리티
│   └── line.ts         # LINE OAuth 유틸리티
├── assets/             # 정적 자산
│   ├── icons/          # 아이콘 파일
│   └── animations/     # 애니메이션 파일
└── index.ts            # 메인 진입점

핵심 기능

OAuth 2.0 플로우: 각 소셜 서비스의 OAuth 2.0 인증 플로우 구현
JWT 토큰 검증: Apple, Kakao 등에서 제공하는 JWT 토큰 검증
상태 관리: 로그인/로그아웃 상태 실시간 관리
다국어 지원: 한국어/영어 언어 전환 기능
보안: 암호학적으로 안전한 UUID 생성 및 토큰 검증
프록시 서버: Apple, Naver는 프록시 서버를 통한 API 호출

의존성

abc-waas-core-sdk: 0.3.0 - 핵심 WaaS 기능
jose: 6.0.13 - JWT 토큰 검증
react: 18.0.0+ - UI 프레임워크
typescript: 5.7.3 - 타입 안전성

🛠️ 개발 가이드

빌드 설정

이 프로젝트는 tsup을 사용하여 빌드됩니다:

npm run build

빌드 옵션:

ESM/CJS 양쪽 형식 지원
TypeScript 선언 파일 자동 생성
Tree shaking 최적화
소스맵 생성
SVG 파일 데이터 URL로 변환

개발 환경 설정

의존성 설치:

npm install

환경 변수 설정: .env 파일에 필요한 OAuth 설정 추가
개발 서버 실행:

npm start

코드 스타일

TypeScript 엄격 모드 사용
함수형 컴포넌트 및 Hook 사용
인라인 스타일 사용 (CSS-in-JS)
명확한 타입 정의 및 JSDoc 주석

🔍 문제 해결

자주 발생하는 문제

1. OAuth 리다이렉트 오류

문제: OAuth 인증 후 리다이렉트가 실패합니다.

해결책:

환경 변수의 리다이렉트 URI가 OAuth 앱 설정과 일치하는지 확인
HTTPS 사용 (프로덕션 환경)
도메인 설정 확인

2. CORS 오류

문제: 브라우저에서 CORS 오류가 발생합니다.

해결책:

백엔드 서버에서 CORS 설정 확인
프록시 서버 사용 고려

3. 토큰 검증 실패

문제: JWT 토큰 검증이 실패합니다.

해결책:

클라이언트 ID/시크릿 확인
토큰 만료 시간 확인
서명 검증 설정 확인

4. 언어 설정이 저장되지 않음

문제: 언어 설정이 새로고침 후 초기화됩니다.

해결책:

브라우저의 localStorage 지원 확인
프라이빗 모드에서의 제한 확인

디버깅 팁

브라우저 개발자 도구 활용
네트워크 탭에서 OAuth 요청 확인
콘솔 로그 확인
환경 변수 설정 확인

📄 라이선스

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🤝 기여하기

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📞 지원

이메일: [email protected]
문서: 공식 문서
이슈: GitHub Issues

ABC WaaS Prebuilt UI SDK로 빠르고 안전한 소셜 로그인을 구현해보세요! 🚀

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ABC WaaS Prebuilt UI SDK

✨ 주요 기능

📋 목차

🚀 설치

🏃‍♂️ 빠른 시작

1. Provider 설정

2. 로그인 컴포넌트 사용

3. 로그아웃 컴포넌트 사용

📖 사용법

기본 컴포넌트

Login 컴포넌트

Logout 컴포넌트

커스텀 Hook

useLanguage Hook

🔧 API Reference

컴포넌트

<Login />

<Logout />

Hook

useLanguage()

타입

UseLanguageType

🌍 환경 변수 설정

🔐 지원하는 소셜 서비스

Google

Apple

Naver

Kakao

LINE

🏗️ 아키텍처

프로젝트 구조

핵심 기능

의존성

🛠️ 개발 가이드

빌드 설정

개발 환경 설정

코드 스타일

🔍 문제 해결

자주 발생하는 문제

1. OAuth 리다이렉트 오류

2. CORS 오류

3. 토큰 검증 실패

4. 언어 설정이 저장되지 않음

디버깅 팁

📄 라이선스

🤝 기여하기

📞 지원

`<Login />`

`<Logout />`

`useLanguage()`

`UseLanguageType`