NOL Open Platform

NOL Open Platform은 모바일 앱과 웹뷰 간의 통신을 위한 JavaScript SDK입니다. iOS와 Android 네이티브 앱에서 웹뷰로 로드되는 웹 페이지에서 사용할 수 있습니다.

주요 기능

• 인증: 챌린지-응답에 필요한 값과 회원키를 반환
• 로그인 상태 확인: NOL 앱의 로그인 상태를 확인
• 결제: 결제 웹뷰 열기
• 웹뷰 제어: 웹뷰 닫기 기능
• 공유: 카카오톡 공유하기
• 로그: NOL 앱으로 클라이언트 로그 전송

사용 환경

이 SDK는 iOS/Android 네이티브 앱의 웹뷰 환경에서만 동작합니다.

✅ 지원 환경

• iOS 앱 내 웹뷰
• Android 앱 내 웹뷰

❌ 미지원 환경 (웹 브라우저)

웹 브라우저 환경에서 사용 시 다음과 같이 동작합니다:

• 자동으로 isSuccess: false 응답 반환
• 콘솔에 에러 메시지 출력: [NolAppBridge] 웹 환경에서는 사용할 수 없습니다. iOS/Android 앱 환경에서만 사용 가능합니다.

예시:

// 웹 브라우저에서 실행 시
const result = await NolAppBridge.setup();
// 콘솔: ❌ [NolAppBridge] 웹 환경에서는 사용할 수 없습니다. iOS/Android 앱 환경에서만 사용 가능합니다.
// result: { isSuccess: false, value: {} }

설치

npm install @nol-open-platform/open-platform-connector

API 참조

init: 기본 설정

import {NolAppBridge} from '@nol-open-platform/open-platform-connector';

// 앱 프록시 ID로 초기화
NolAppBridge.init('your-app-proxy-id');

setup: 인증 처리

챌린지-응답에 필요한 값과 회원키를 반환한다. 로그인이 되어있지 않다면 NOL 로그인 페이지로 이동합니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
    const result = await NolAppBridge.setup();
    if (result.isSuccess) {
      console.log('인증 성공');
      console.log('회원 ID:', result.value.appMemberProxyId);
      console.log('챌린지 ID:', result.value.challengeId);
      console.log('챌린지 값:', result.value.challengeValue);
      console.log('상태 값:', result.value.status);
    } else {
      if (result.value.status === "CANCEL_LOGIN") {
        console.log('로그인 취소됨');
      } else if (result.value.status === "CHALLENGE_FAILED") {
        console.log('챌린지 검증 실패');
      }
      console.log('인증 실패');
    }
} catch (error) {

  console.error('인증 오류:', error);
}

isLogin: 로그인 상태 확인

NOL 앱의 로그인 상태를 확인합니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
    const result = await NolAppBridge.isLogin();
    if (result.isSuccess) {
        console.log('로그인 상태 확인 성공');
        console.log('로그인 상태:', result.value.isLogin);
    } else {
        console.log('로그인 상태 확인 실패');
    }
} catch (error) {
    console.error('로그인 상태 확인 오류:', error);
}

openPayment: 결제 웹뷰 열기

결제 웹뷰를 엽니다.

파라미터:

• param (OpenPaymentParam): 결제 파라미터
  • orderNo (string): 주문 번호

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

// 결제 파라미터 설정
const paymentParam = {
    orderNo: '1234567890'
};

try {
    const result = await NolAppBridge.openPayment(paymentParam);
    if (result.isSuccess) {
        console.log('결제 웹뷰 열기 성공');
    } else {
        console.log('결제 웹뷰 열기 실패');
    }
} catch (error) {
    console.error('결제 웹뷰 열기 오류:', error);
}

closeWebView: 웹뷰 닫기

웹뷰를 닫을 때 사용하는 함수입니다. 결제 완료 후 또는 사용자가 취소할 때 호출합니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
    const result = await NolAppBridge.closeWebView();
    if (result.isSuccess) {
        console.log('웹뷰 닫기 성공');
    } else {
        console.log('웹뷰 닫기 실패');
    }
} catch (error) {
    console.error('웹뷰 닫기 오류:', error);
}

openInAppBrowser: 브라우저 열기

인앱 브라우저를 열때 사용하는 함수입니다. 관리자에서 등록된 url만 사용할 수 있습니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
  const result = await NolAppBridge.openInAppBrowser({
    url: 'https://www.example.com'
  });
  if (result.isSuccess) {
    console.log('브라우저 열기 성공');
  } else {
    console.log('브라우저 열기 실패');
  }
} catch (error) {
  console.error('브라우저 열기 오류:', error);
}

⚠️ openAccountManagement: 계정 관리 페이지 열기 (Deprecated)

Deprecated: 이 함수는 더 이상 사용하지 않습니다. 대신 openWebView에 type: 'ACCOUNT_MANAGEMENT'를 전달하세요.

// 권장
await NolAppBridge.openWebView({ type: 'ACCOUNT_MANAGEMENT' });

NOL 앱의 계정 관리 페이지 웹뷰를 엽니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
  const result = await NolAppBridge.openAccountManagement();
  if (result.isSuccess) {
    console.log('웹뷰 열기 성공');
  } else {
    console.log('웹뷰 열기 실패');
  }
} catch (error) {
  console.error('웹뷰 열기 오류:', error);
}

openWebView: 놀앱 지면 페이지 열기

NOL 앱의 특정 지면 페이지 웹뷰를 엽니다.

파라미터:

• param (OpenWebViewParam): 웹뷰 파라미터
  • type (WebViewUrlType): 열고자 하는 지면 타입 ('ACCOUNT_MANAGEMENT' | 'PROMOTION')

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
  const result = await NolAppBridge.openWebView({
    type: 'PROMOTION'
  });
  if (result.isSuccess) {
    console.log('웹뷰 열기 성공');
  } else {
    console.log('웹뷰 열기 실패');
  }
} catch (error) {
  console.error('웹뷰 열기 오류:', error);
}

shareToKakao: 카카오톡 공유하기

카카오톡으로 콘텐츠를 공유합니다.

공유를 요청하기 전에 다음을 검증하며, 조건을 만족하지 않으면 isSuccess: false 와 함께 해당 status 를 반환합니다.

• 필수 파라미터(title · description · imageUrl · linkUrl · buttonText) 중 누락된 값이 있으면 → MISSING_PARAMETER
• linkUrl 이 nol-app 으로 시작하지 않으면 → INVALID_PARAMETER
• shareToKakao 를 지원하지 않는 구버전 앱이면 → UNSUPPORTED_VERSION
  • nolAppInfo 응답 여부로 지원 여부를 판별합니다. (미응답 시 미지원으로 간주)

파라미터:

• param (ShareToKaKaoParam): 공유 파라미터
  • title (string): 공유 제목
  • description (string): 공유 설명
  • imageUrl (string): 공유 이미지 URL
  • linkUrl (string): 공유 딥링크 (nol-app 으로 시작해야 함)
  • buttonText (string): 버튼 텍스트

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
  const result = await NolAppBridge.shareToKakao({
    title: '공유 제목',
    description: '공유 설명',
    imageUrl: 'https://www.example.com/image.png',
    linkUrl: 'nol-app://...',
    buttonText: '자세히 보기'
  });
  if (result.isSuccess) {
    console.log('카카오톡 공유 성공');
  } else {
    switch (result.value.status) {
      case 'MISSING_PARAMETER':
        console.log('필수 파라미터 누락');
        break;
      case 'INVALID_PARAMETER':
        console.log('잘못된 파라미터 (linkUrl 형식 오류)');
        break;
      case 'UNSUPPORTED_VERSION':
        console.log('지원하지 않는 앱 버전');
        break;
      default:
        console.log('카카오톡 공유 실패');
    }
  }
} catch (error) {
  console.error('카카오톡 공유 오류:', error);
}

sendClientLog: 클라이언트 로그 전송

NOL 앱으로 클라이언트 로그를 전송합니다.

전송을 요청하기 전에 다음을 검증하며, 조건을 만족하지 않으면 앱으로 전송하지 않고 isSuccess: false 와 함께 해당 status 를 반환합니다.

• 등록되지 않은 clientEventId 이면 → INVALID_PARAMETER
• nolTrackEvent 를 지원하지 않는 구버전 앱이면 → UNSUPPORTED_VERSION
  • nolAppInfo 응답 여부로 지원 여부를 판별합니다. (미응답 시 미지원으로 간주)

파라미터:

• clientEventId (number): 로그 이벤트 ID
• payload (Record<string, unknown>): 로그 데이터. 전달할 값이 없으면 {} 를 전달합니다.

반환값: Promise<OpenPlatformBridgeCallbackResult>

예시:

try {
  const result = await NolAppBridge.sendClientLog(clientEventId, payload);
  if (!result.isSuccess) {
    switch (result.value.status) {
      case 'INVALID_PARAMETER':
        console.log('등록되지 않은 clientEventId');
        break;
      case 'UNSUPPORTED_VERSION':
        console.log('지원하지 않는 앱 버전');
        break;
      default:
        console.log('로그 전송 실패');
    }
  }
} catch (error) {
  console.error('로그 전송 오류:', error);
}

타입 정의

interface SetupResponseSuccess {
  status: "OK";
  appMemberProxyId: string;
  challengeId: string;
  challengeValue: string;
}

interface SetupResponseCancel {
  status: "CANCEL_LOGIN";
}

interface SetupResponseChallengeFailed {
  status: "CHALLENGE_FAILED";
}

type SetupResponse = SetupResponseSuccess | SetupResponseCancel | SetupResponseChallengeFailed;

interface OpenPaymentParam {
  orderNo: string;
}

type WebViewUrlType = "ACCOUNT_MANAGEMENT" | "PROMOTION";

interface OpenWebViewParam {
  type: WebViewUrlType;
}

interface IsLoginResponse {
  isLogin: boolean;
}

interface ShareToKaKaoParam {
  title: string;
  description: string;
  imageUrl: string;
  linkUrl: string;
  buttonText: string;
}

type ShareToKaKaoResponse = {
  status: "SUCCESS" | "UNSUPPORTED_VERSION" | "INVALID_PARAMETER" | "MISSING_PARAMETER";
};

type SendClientLogResponse = {
  status: "SUCCESS" | "UNSUPPORTED_VERSION" | "INVALID_PARAMETER";
};

type ClientEventId = number;

type ClientLogPayload = Record<string, unknown>;

interface OpenPlatformBridgeCallbackResult<T> {
  isSuccess: boolean;
  value: T;
}

type OpenPlatformBridgeCallbackFunction<T> = (result: OpenPlatformBridgeCallbackResult<T>) => void;

버전

현재 버전: 1.4.0