Skip to main content

인증 및 API 키 관리

Klever One SDK를 사용하기 위해서는 유효한 API 키가 필요합니다. 이 가이드에서는 API 키 설정부터 보안 모범 사례까지 모든 것을 다룹니다.

API 키 발급​

1단계: Klever One Studio 접속​

  1. Klever One에 로그인
  2. 스튜디오로 이동
  3. 페르소나 생성

2단계: API 키 생성​

  1. 생성한 페르소나의 배포하기 아이콘 버튼 클릭
  2. 임베딩 허용
  3. 배포하기 버튼 클릭
# 생성된 키 예시
nlp_YourKeyHere
중요

생성된 API 키는 반드시 안전한 곳에 저장하세요!

SDK에서 API 키 사용​

HTML/JavaScript 방법​

index.html
<script src="https://unpkg.com/@klever-one/web-sdk@0.1.0-beta.19/dist/core/klever-one-core-v0.1.0-beta.19.umd.js"></script>
<script>
  const { KleverOneClient } = KleverOneSdk;

  // 클라이언트 생성 및 인증
  const client = new KleverOneClient({
    apiKey: "your_api_key", // 실제 API 키
    container: document.getElementById("avatar-container"),
    callbacks: {
      onReady: () => console.log("인증 성공 및 준비 완료"),
      onError: (error) => console.error("인증 실패:", error),
    },
  });

  // 연결 시작
  client.connect();
</script>

TypeScript 방법​

src/main.ts
import { KleverOneClient } from "@klever-one/web-sdk/core";
import type { KleverOneClientConfig } from "@klever-one/web-sdk/core";

// 설정 객체 생성
const config: KleverOneClientConfig = {
  // 환경 변수에서 API 키 가져오기 (권장)
  apiKey: process.env.VITE_KLEVER_API_KEY || "your-api-key-here",
  container: document.getElementById("avatar-container")!,
  callbacks: {
    onReady: () => {
      console.log("인증 완료 - SDK 준비됨");
    },
    onError: (error: Error) => {
      console.error("인증 오류:", error);

      // API 키 관련 오류 처리
      if (error.message.includes("API key") || error.message.includes("401")) {
        alert("API 키가 올바르지 않습니다. 설정을 확인해주세요.");
      }
    },
  },
};

// 클라이언트 생성
const client = new KleverOneClient(config);

// 연결 시작
async function initialize() {
  try {
    await client.connect();
    console.log("초기화 완료");
  } catch (error) {
    console.error("초기화 실패:", error);
  }
}

initialize();

React 방법​

src/components/AuthenticatedDigitalHuman.tsx
"use cleint"

import { useEffect, useRef, useState } from "react";
import { useKleverOneClient } from "@klever-one/web-sdk/react"; // useKleverOneClient 임포트

interface Props {
  apiKey: string;
}

export function AuthenticatedDigitalHuman({ apiKey }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [error, setError] = useState<string>("");

  const client = useKleverOneClient({
    apiKey,
    container: containerRef.current,
    callbacks: {
      onReady: () => {
        console.log("인증 및 초기화 완료");
      },
      onError: (error: Error) => {
        console.error("인증 오류:", error);
      },
    },
  });

  useEffect(() => {
    if (containerRef.current) {
      client.connect();
    }
    return () => client.disconnect();
  }, [client]);

  const renderContent = () => {
    if (client.state.connection === "connected" && client.isReady()) {
      return (
        <div className="text-center p-10 max-w-md">
          <p className="text-green-500 text-lg font-semibold">인증 성공 - 디지털 휴먼 준비 완료</p>
        </div>
      );
    } else if (
      client.state.connection === "connecting" ||
      client.state.connection === "allocating"
    ) {
      return (
        <div className="text-center p-10 max-w-md">
          <div className="spinner w-10 h-10 border-4 border-gray-300 border-t-4 border-t-yellow-500 rounded-full animate-spin mx-auto mb-5"></div>
          <p className="text-yellow-500 text-lg font-semibold">방 생성 중...</p>
        </div>
      );
    }
    return null;
  };

  return (
    <div className="relative">
      <div
        ref={containerRef}
        className="w-full h-[600px] bg-black rounded-xl"
      />

      {!(client.state.connection === "connected" && client.isReady()) && (
        <div className="absolute inset-0 bg-black bg-opacity-90 text-white flex items-center justify-center rounded-xl">
          {renderContent()}
        </div>
      )}
    </div>
  );
}
    </div>
  );
}

보안 모범 사례​

1. 환경 변수 사용 (권장)​

Vite/React 프로젝트​

.env.local
# 개발 환경용
VITE_KLEVER_API_KEY=your_api_key

# 프로덕션 환경용
VITE_KLEVER_API_KEY_PROD=your_api_key
src/config.ts
// 환경별 API 키 관리
export const config = {
  apiKey: import.meta.env.VITE_KLEVER_API_KEY,
  isDevelopment: import.meta.env.DEV,
  isProduction: import.meta.env.PROD,
};

// 유효성 검사
if (!config.apiKey) {
  throw new Error("VITE_KLEVER_API_KEY 환경 변수가 설정되지 않았습니다.");
}

Next.js 프로젝트​

.env.local
NEXT_PUBLIC_KLEVER_API_KEY = your_api_key;
src/lib/klever-config.ts
export const kleverConfig = {
  apiKey: process.env.NEXT_PUBLIC_KLEVER_API_KEY!,
};

if (!kleverConfig.apiKey) {
  console.error("NEXT_PUBLIC_KLEVER_API_KEY가 설정되지 않았습니다.");
}

보안 체크리스트​

프로덕션 배포 전에 다음 사항들을 확인하세요:

필수 보안 사항​

  • API 키가 환경 변수로 설정됨
  • 소스 코드에 하드코딩된 API 키 없음
  • .env 파일이 .gitignore에 추가됨
  • 개발/프로덕션 키가 분리됨

권장 보안 사항​

  • 백엔드 프록시를 통한 인증 (고급)
  • 오류 로깅 시스템 구축

웹 보안 사항​

  • HTTPS 강제 설정
  • CSP(Content Security Policy) 헤더 설정
  • CORS 정책 올바르게 구성
  • XSS 방지 조치 적용

추가 보안 가이드