본문으로 건너뛰기

초기화 (Initialization)

SDK 사용 전 initialize() 메서드를 호출하여 초기화합니다. 앱 시작 시 한 번만 호출하면 됩니다.

기본 초기화​

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

await appify.initialize({ debug: true });

초기화 옵션 (InitializeOptions)​

옵션타입기본값설명
debugboolean | 'console' | 'alert' | 'both'false디버그 모드 활성화 및 출력 방식
serializedPermissionsbooleanfalse권한 요청 직렬화 (동시 요청 방지)
bouncesbooleantrue(iOS) 웹뷰 바운스 효과
hideScrollbarbooleanfalse스크롤바 숨김
enableRefreshbooleanfalsePull-to-refresh 기능
statusBarobject-상태바 스타일 설정
safeAreaobject-Safe Area 적용 영역

전체 옵션 예시​

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

await appify.initialize({
  debug: 'console',
  serializedPermissions: true,
  bounces: false,
  hideScrollbar: true,
  enableRefresh: false,
  statusBar: {
    barStyle: 'dark-content',
    backgroundColor: '#ffffff'
  },
  safeArea: {
    edge: ['top', 'bottom']
  }
});

초기화 상태 확인​

isInitialized​

SDK 초기화 여부를 동기적으로 확인합니다.

if (appify.isInitialized) {
  // SDK 사용 가능
}

ensureInitialized()​

초기화되지 않은 경우 NotInitializedError를 throw합니다.

import { appify, NotInitializedError } from '@nolraunsoft/appify-sdk';

try {
  appify.ensureInitialized();
  // SDK 사용
} catch (error) {
  if (error instanceof NotInitializedError) {
    console.error('SDK가 초기화되지 않았습니다.');
  }
}

waitForInit()​

초기화 완료를 비동기로 대기합니다.

await appify.waitForInit();
// 초기화 완료 후 실행

자동 초기화 대기​

SDK 메서드 호출 시 초기화가 완료되지 않았다면, 100ms 동안 자동으로 대기합니다.

// 초기화와 동시에 다른 작업 시작 가능
appify.initialize({ debug: true }); // await 없이 호출

// 100ms 이내에 초기화 완료되면 정상 동작
const info = await appify.device.getInfo();

100ms 내에 초기화가 완료되지 않으면 NotInitializedError가 발생합니다.

중복 호출 방지​

initialize()는 내부적으로 중복 호출을 방지합니다. 여러 번 호출해도 최초 1회만 실행됩니다.

await appify.initialize({ debug: true });
await appify.initialize({ debug: false }); // 무시됨, 경고 로그 출력

싱글턴 인스턴스​

SDK는 싱글턴으로 동작합니다:

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

console.log(appify === window.appify); // true

동작 방식​

  1. SDK 로드 시 자동으로 인스턴스 생성
  2. window.appify에 등록
  3. 이후 import 시 동일 인스턴스 반환

따라서 Provider에서 한 번 초기화하면, 모든 페이지에서 바로 사용할 수 있습니다.

SDK 정리 (destroy)​

SDK를 완전히 정리하려면 destroy() 메서드를 사용합니다.

appify.destroy();

destroy() 동작​

  • 모든 이벤트 리스너 제거
  • 진행 중인 요청 취소 (SDKDestroyedError 발생)
  • 대기 중인 큐 정리
  • history 패치 복원
  • 초기화 상태 리셋

주의사항​

destroy() 호출 후에는 SDK를 다시 사용할 수 없습니다. 페이지를 새로고침하면 새 인스턴스가 생성됩니다.

appify.destroy();
await appify.device.getInfo(); // SDKDestroyedError 발생

React 예시​

"use client";

import { ReactNode, useEffect } from "react";
import { appify } from "@nolraunsoft/appify-sdk";

export function AppifyProvider({ children }: { children: ReactNode }) {
  useEffect(() => {
    appify.initialize({ debug: true });

    return () => {
      // 필요시 cleanup (일반적으로 불필요)
      // appify.destroy();
    };
  }, []);
  return <>{children}</>;
}
import { AppifyProvider } from "./providers/AppifyProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <AppifyProvider>{children}</AppifyProvider>
      </body>
    </html>
  );
}

이후 어떤 페이지에서든 import { appify }로 바로 사용:

"use client";
import { appify } from "@nolraunsoft/appify-sdk";

export default function AnyPage() {
  const handleClick = async () => {
    const info = await appify.device.getInfo();
    console.log(info);
  };
  
  return <button onClick={handleClick}>디바이스 정보</button>;
}

SSR 안전성​

SDK는 SSR (Server-Side Rendering) 환경에서 안전하게 동작합니다.

  • typeof window === "undefined" 체크로 서버 환경 감지
  • 서버에서 import해도 에러 없음
  • 브라우저에서만 실제 기능 동작
// Next.js 서버 컴포넌트에서도 import 가능 (동작하지 않을 뿐)
import { appify } from "@nolraunsoft/appify-sdk";

// 단, 실제 사용은 클라이언트 컴포넌트에서
"use client";
import { appify } from "@nolraunsoft/appify-sdk";