nachocode 클라이언트 SDK 시작하기

sdk

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

nachocode Client SDK를 프로젝트에 통합하고 기본적으로 사용할 수 있도록 설정하는 방법을 안내합니다.

nachocode Client SDK는 웹 클라이언트에서 네이티브 앱의 기능을 손쉽게 활용할 수 있도록 지원합니다.
이 가이드는 SDK 설치부터 초기화, 주요 기능 사용까지 단계별로 설명합니다.

1. SDK 설치

nachocode Client SDK는 CDN을 통해 간편하게 설치할 수 있습니다.
웹 페이지의 <body> 태그 안에 다음과 같은 스크립트 태그를 추가합니다. 이 스크립트는 nachocode Client SDK를 웹 페이지에 로드합니다.

최신 버전 불러오기
- 현재 최신 버전 v1.6.2
- 최신 버전의 SDK를 항상 유지하려면 아래 코드를 사용하세요
```
<script src="https://cdn.nachocode.io/nachocode/client-sdk/@latest/client-sdk.min.js"></script>
```
특정 버전 사용
- 특정 버전으로 고정하려면 다음과 같이 사용합니다
```
<script src="https://cdn.nachocode.io/nachocode/client-sdk/@1.6.2/client-sdk.min.js"></script>
```

정보

최신 버전을 사용하는 것이 권장되며, 특정 버전 고정은 호환성 유지가 필요한 경우에 사용하세요.

리액트 프로젝트에 설치하고 사용하는 방법

➡️ React 가이드 바로가기

2. SDK 초기화

개요

웹 페이지 로딩이 완료되면, nachocode Client SDK를 반드시 초기화해야 합니다.
초기화는 API 키를 사용하며, 필요에 따라 디버깅 로깅 기능을 활성화할 수 있습니다.
nachocode Client SDK 초기화는 비동기로 이루어지므로, 로딩 중 상태 처리와 오류 처리를 구현하는 것이 좋습니다.

정보

API Key는 안전하고 원활한 API 통신을 위해 필요한 정보로
nachocode 대시보드 [앱 설정] > [개발자 설정] 탭에서 발급 가능합니다.

➡️ 개발자 설정 유저가이드 바로가기

초기화 옵션 설명 (`InitializeOptions`)

옵션	타입	설명
`sandbox`	`boolean`	샌드박스 서버 사용 여부를 지정합니다.
`logger`	`boolean`	`true`로 설정하면 개발 중 디버깅을 위한 로그 출력이 활성화됩니다.

SDK를 통합한 앱을 개발/테스트할 때는 logger 옵션을 활성화하여 내부 로그를 확인하는 것이 도움이 됩니다.
Nachocode.init 옵션에서 logger: true로 설정하면, SDK 로드 과정과 네이티브 호출 내역 등이 브라우저 콘솔에 출력됩니다. 이를 통해 SDK가 정상적으로 초기화되었는지, 함수 호출 시 어떤 동작을 했는지 추적할 수 있습니다.
sandbox: true 옵션을 사용하면 nachocode의 테스트 서버를 향해 API를 호출하게 되므로, 개발 환경에서 안전하게 실험해볼 수 있습니다. 개발 중에는 Sandbox 옵션을 활용하고, 프로덕션 빌드에서는 sandbox를 false로 두는 것을 권장합니다.

초기화 함수 정의 및 예제

nachocode Client SDK 초기화는 두 가지 방식으로 가능합니다.

🔸 비동기 초기화 (`initAsync`) - 권장 ✅

SDK가 준비될 때까지 await 구문을 통해 기다릴 수 있어 더 안전하고 직관적입니다.

<script>
  (async () => {
    if (window.Nachocode) {
      try {
        await Nachocode.initAsync('your_api_key_here', { logger: true });

        if (Nachocode.env.isApp()) {
          // 앱 환경에서만 동작할 로직을 작성합니다.
        }
      } catch (error) {
        console.error('nachocode Client SDK 초기화 실패:', error);
      }
    } else {
      console.error('nachocode Client SDK가 로드되지 않았습니다.');
    }
  })();
</script>

🔸 기존 초기화 방식 (`init`)

SDK 초기화 완료 이벤트를 통해 SDK 준비 상태를 감지할 수 있습니다.

<script>
  if (window.Nachocode) {
    Nachocode.event.on('init', () => {
      if (Nachocode.env.isApp()) {
        // 앱 환경에서만 동작할 로직을 작성합니다.
      }
    });

    Nachocode.init('your_api_key_here', { logger: true });
  } else {
    console.error('nachocode Client SDK가 로드되지 않았습니다.');
  }
</script>

옵션 없이 간단한 초기화도 가능합니다.

<script>
  if (window.Nachocode) {
    Nachocode.init('your_api_key_here');
  }
</script>

3. 주요 기능 사용

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

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

앱 정보 가져오기

const appVersion = Nachocode.app.getCurrentAppVersion();
console.log(`현재 앱 버전: ${appVersion}`); // ex. "1.0.0"

디바이스 정보 확인

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

인앱 브라우저에서 열기

// 내부 브라우저에서 URL 열기
Nachocode.browser.openLink('https://nachocode.io', 'internal');

// 링크 공유 - 공유할 URL을 지정하여 네이티브 공유 UI를 엽니다.
Nachocode.share.openSharing({
  url: 'https://developer.nachocode.io/docs/releases/v1/sdk/intro',
});

현재 대부분의 기능은 웹 실행환경에선 무시되고, 앱 실행환경에서 정상 작동합니다.
일부 기능은 앱 뿐아니라 웹 실행환경도 지원하며, 점차 지원을 계속 확대할 예정입니다.

1. SDK 설치​

최신 버전 불러오기​

특정 버전 사용​

2. SDK 초기화​

개요​

초기화 옵션 설명 (InitializeOptions)​

초기화 함수 정의 및 예제​

🔸 비동기 초기화 (initAsync) - 권장 ✅​

🔸 기존 초기화 방식 (init)​

3. 주요 기능 사용​