📦 nachocode Client SDK

🔔 최신화 일자: 2025-07-09

개요

nachocode Client SDK는 웹 개발자들이 네이티브 앱의 고유 기능을 손쉽게 활용할 수 있도록 돕는 SDK입니다.

이 문서는 SDK의 설치, 초기화, 주요 기능 및 사용 방법 등을 안내합니다.

공식 문서 바로가기

설치

npm install nachocode-client-sdk

또는

yarn add nachocode-client-sdk

사용법

nachocode Client SDK는 세 가지 방법으로 사용할 수 있습니다.

1️⃣ `NachoProvider`, `useNachocodeContext` (React Context 방식)

애플리케이션 전체에서 Nachocode를 사용할 수 있도록 Provider 패턴을 제공합니다.
useNachocodeContext 훅을 사용하여 Nachocode 객체에 접근할 수 있습니다.

import { NachoProvider, useNachocodeContext } from 'nachocode-client-sdk';

function MyComponent() {
  const { Nachocode, isLoading, isError, error } = useNachocodeContext();

  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>Error: {error.message}</p>;

  return <p>Nachocode SDK 사용 가능!</p>;
}

export default function App() {
  return (
    <NachoProvider apiKey="your-api-key-here">
      <MyComponent />
    </NachoProvider>
  );
}

2️⃣ `useNachocode` (React Hook 방식)

특정 Component에서만 Nachocode를 사용하고 싶다면 useNachocode 훅을 사용하여 Nachocode 객체에 접근할 수 있습니다.

import { useNachocode } from 'nachocode-client-sdk';

export default function MyComponent2() {
  const { Nachocode, isLoading, isError, error } = useNachocode('test-key');

  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>Error: {error.message}</p>;

  return <p>Nachocode SDK 사용 가능!</p>;
}

`useNachocode()` 반환값

반환값	설명
`Nachocode`	Nachocode SDK 객체
`isLoading`	SDK 로딩 상태 (`true` 또는 `false`)
`isError`	SDK 에러 여부 (`true` 또는 `false`)
`error`	SDK 로드 중 발생한 에러 (`Error` 또는 `null`)

3️⃣ `loadNachocode` 직접 사용

React 외부에서도 loadNachocode 함수를 직접 호출하여 사용 가능합니다.

import { loadNachocode } from 'nachocode-client-sdk';

async function initSDK() {
  try {
    const Nachocode = await loadNachocode('your-api-key-here');
    console.log('Nachocode SDK 로드 완료:', Nachocode);
  } catch (error) {
    console.error('Nachocode SDK 로드 실패:', error);
  }
}

initSDK();

SDK 초기화 옵션 (`InitializeOptions`)

nachocode Client SDK는 초기화 시 선택적으로 옵션을 설정할 수 있습니다.

초기화 옵션은 NachoProvider, loadNachocode 두 방식에서 모두 사용할 수 있습니다.

NachoProvider 방식에서 options 사용

NachoProvider에 apiKey와 함께 options를 전달할 수 있습니다:

<NachoProvider
  apiKey="your-api-key"
  options={{ sandbox: true, logger: true }}
>
  <YourComponent />
</NachoProvider>

loadNachocode 직접 호출 시 options 사용
- 비 React 환경 또는 수동으로 초기화하고 싶을 때 사용합니다:
```
loadNachocode('your-api-key', {
  sandbox: true,
  logger: true,
});
```

옵션 이름	타입	설명
`sandbox`	boolean	✅ 샌드박스 환경에서 테스트 시 `true`로 설정
`logger`	boolean	✅ 콘솔 로그를 통해 SDK 내부 동작을 디버깅하고 싶을 때 `true`로 설정

logger는 기본적으로 true로 설정되어 있으며, 개발 중 디버깅에 유용합니다.
sandbox는 실제 운영 API가 아닌 테스트 서버를 사용하는 경우 유용합니다.

SDK 버전 관리

최신 버전 로드 (기본)

최신 버전의 SDK를 항상 유지하려면 아래 코드를 사용하세요
현재 최신 버전 v.1.6.2

loadNachocode('your-api-key'); // 최신 버전이 자동으로 로드됨

특정 버전 지정

특정 버전으로 고정하려면 다음과 같이 사용합니다

loadNachocode('your-api-key', options, '1.6.2');

📢 최신 버전 사용이 권장되며, 특정 버전 고정은 호환성이 중요한 경우에만 사용하세요.

SDK 기능 사용

nachocode Client SDK가 초기화가 완료되면, Nachocode 네임스페이스 아래에 정의된 다양한 네이티브 기능을 사용할 수 있습니다.

아래 예시는 SDK의 일부 기능을 사용하는 방법을 보여줍니다.

앱 정보 가져오기

const appName = Nachocode.app.getAppName();
console.log(`앱 이름: ${appName}`); // ex. "Nachocode Developer"

디바이스 정보 확인

Nachocode.device.getDeviceModel(model => {
  console.log(`디바이스 모델: ${model}`);
});

대부분의 기능은 웹 실행환경에선 무시되고, 앱 실행환경에서 정상 작동합니다.

네임스페이스 소개

nachocode Client SDK는 각 기능별로 네임스페이스(namespace) 로 구분되어 있습니다.

아래는 주요 네임스페이스의 목록과 설명입니다. 각 네임스페이스에 대한 상세한 문서는 문서 링크에서 확인하세요.

네임스페이스	설명	문서 링크
`app`	앱 이름, 버전, 패키지 이름 등의 정보를 제공합니다.	앱 문서
`apple`	Apple 계정을 통한 소셜 로그인 기능 등을 제공합니다.	Apple 문서
`authentication`	생체 인증(Fingerprint/Face ID) 등의 기능을 제공합니다.	인증 문서
`backkey`	Android 디바이스의 네이티브 백 키 이벤트를 제어할 수 있습니다.	백 키 문서
`browser`	외부 또는 내부 브라우저로 URL을 열 수 있습니다.	브라우저 문서
`clipboard`	텍스트를 클립보드에 복사하거나 읽을 수 있습니다.	클립보드 문서
`device`	디바이스 모델, OS 버전, 배터리 및 네트워크 상태 등을 확인합니다.	디바이스 문서
`env`	SDK 초기화 상태, 실행 환경(웹/앱) 등을 확인할 수 있습니다.	환경 문서
`event`	초기화, 포그라운드/백그라운드 전환, 네트워크 상태 변경 등의 이벤트를 처리합니다.	이벤트 문서
`facebook`	Facebook 소셜 로그인 기능을 제공합니다.	Facebook 문서
`google`	Google 소셜 로그인 기능을 제공합니다.	Google 문서
`iap`	Google Play 및 Apple App Store 인앱 결제 기능을 제공합니다.	인앱 결제 문서
`kakao`	Kakao 소셜 로그인 및 공유 기능을 제공합니다.	Kakao 문서
`location`	현재 디바이스 위치의 경도, 위도를 확인할 수 있습니다.	Location 네임스페이스
`permission`	카메라, 위치, 푸시 알림 등 디바이스 권한을 요청하고 상태를 확인할 수 있습니다.	권한 문서
`preference`	애플리케이션 내부 저장소를 통해 데이터를 저장 및 관리합니다.	내부 저장소 문서
`push`	푸시 알림 토큰을 관리하고 Nachocode 서버에 등록할 수 있습니다.	푸시 문서
`scanner`	QR 코드 스캔 및 기타 스캔 기능을 제공합니다.	스캐너 문서
`setting`	Pull to Refresh와 같은 설정 기능을 제공합니다.	설정 문서
`share`	네이티브 공유 UI를 통해 URL을 공유할 수 있습니다.	공유 문서
`store`	Apple App Store, Google Play Store 상호작용 관련 기능을 제공합니다.	스토어 문서
`tabbar`	앱 내부 탭바의 표시 여부 및 이동을 제어할 수 있습니다.	탭 바 문서
`vibration`	디바이스 진동 및 햅틱 피드백을 제어합니다.	진동 문서

더 많은 네임스페이스와 사용법은 공식 문서를 확인하세요.

기여자

_{Taekyu Park}

_{John An}

_{Ratel Kim}

기여하기

nachocode Client SDK를 사용해주셔서 감사합니다! 🚀

궁금한 점이나 개선 사항이 있다면 Issues 또는 Pull Requests를 통해 남겨주시거나,

언제든지 support@nachocode.io로 문의를 보내주세요. 🙌

라이선스

이 프로젝트는 MIT 라이선스 하에 제공됩니다.