아키텍처

TurboModule 아키텍처

@boostbrothers/react-native-coucon-sdk는 React Native의 TurboModule 시스템을 기반으로 구현되어 있습니다. TurboModule은 기존 NativeModule 대비 다음과 같은 장점을 제공합니다.

항목	기존 NativeModule	TurboModule
로딩 방식	앱 시작 시 전체 로딩	필요 시 지연 로딩
타입 안전성	JavaScript 동적 타입	TypeScript Spec 정적 타입
브릿지 오버헤드	JSON 직렬화 필요	JSI 직접 호출
New Architecture	미지원	완전 지원

레이어 구조

┌─────────────────────────────────────────┐
│          앱 코드 (TypeScript)              │
│  initialize() / reset() / run()         │
│  addOnSASRunCompletedListener()         │
├─────────────────────────────────────────┤
│       JS 래퍼 레이어 (index.tsx)           │
│  - NativeEventEmitter 초기화             │
│  - addListener 래핑                      │
│  - 기본값 처리 (debugMode = false)         │
├─────────────────────────────────────────┤
│   NativeCouconSdk (TurboModule Spec)    │
│  TurboModuleRegistry.getEnforcing(      │
│    'CouconSdk'                          │
│  )                                      │
├──────────────────┬──────────────────────┤
│   iOS            │   Android            │
│ (Swift/ObjC)     │  (Kotlin/Java)       │
│ CouconSdk native │  CouconSdk native    │
│ SAS 엔진          │  SAS 엔진             │
└──────────────────┴──────────────────────┘

이벤트 기반 통신 패턴

SAS 엔진은 비동기적으로 동작합니다. run()으로 작업을 시작하면 네이티브 레이어에서 처리 후 NativeEventEmitter를 통해 결과를 전달합니다.

NativeEventEmitter 초기화

JS 레이어에서 NativeEventEmitter는 모듈 로드 시 한 번 생성됩니다.

// src/index.tsx 내부
import { NativeEventEmitter } from 'react-native';
import CouconSdk from './NativeCouconSdk';

// 모듈 수준에서 단일 인스턴스 생성
const eventEmitter = new NativeEventEmitter(CouconSdk);

export function addOnSASRunCompletedListener(
  callback: (event: SASRunCompletedEvent) => void
) {
  return eventEmitter.addListener('onSASRunCompleted', callback);
}

NativeEventEmitter에 CouconSdk 모듈을 전달하는 이유는 TurboModule의 addListener/removeListeners 메서드를 통해 네이티브 레이어에서 리스너 수를 추적하기 위함입니다. 이를 통해 리스너가 없을 때 네이티브 레이어가 불필요한 이벤트를 방출하지 않도록 최적화합니다.

TurboModule 등록 방식

// src/NativeCouconSdk.ts
import { TurboModuleRegistry } from 'react-native';

export default TurboModuleRegistry.getEnforcing<Spec>('CouconSdk');

getEnforcing은 모듈 이름 'CouconSdk'로 네이티브 모듈을 찾습니다. 모듈을 찾지 못하면 즉시 오류를 발생시킵니다 (vs get()은 null 반환). 이는 SDK가 네이티브 빌드 없이 동작하지 않음을 명시적으로 강제합니다.

멀티 인덱스 패턴

SAS 엔진은 여러 작업을 동시에 처리할 수 있습니다. index 파라미터를 통해 어떤 run() 호출의 결과인지 구분합니다.

// 여러 SAS 작업 동시 실행
const subscription = addOnSASRunCompletedListener((event) => {
  switch (event.index) {
    case 1:
      handleAuthResult(event.outString);
      break;
    case 2:
      handleVerificationResult(event.outString);
      break;
    case 3:
      handleTokenResult(event.outString);
      break;
  }
});

// 병렬 실행
await Promise.all([
  run(1, 'auth-input'),
  run(2, 'verify-input'),
  run(3, 'token-input'),
]);

인덱스 번호의 의미(어떤 SAS 작업인지)는 Coucon SAS 엔진 명세를 참고하세요. 인덱스는 SAS 엔진 내부에서 처리할 작업 유형을 결정합니다.

아키텍처

TurboModule 아키텍처

항목	기존 NativeModule	TurboModule
로딩 방식	앱 시작 시 전체 로딩	필요 시 지연 로딩
타입 안전성	JavaScript 동적 타입	TypeScript Spec 정적 타입
브릿지 오버헤드	JSON 직렬화 필요	JSI 직접 호출
New Architecture	미지원	완전 지원

레이어 구조

┌─────────────────────────────────────────┐
│          앱 코드 (TypeScript)              │
│  initialize() / reset() / run()         │
│  addOnSASRunCompletedListener()         │
├─────────────────────────────────────────┤
│       JS 래퍼 레이어 (index.tsx)           │
│  - NativeEventEmitter 초기화             │
│  - addListener 래핑                      │
│  - 기본값 처리 (debugMode = false)         │
├─────────────────────────────────────────┤
│   NativeCouconSdk (TurboModule Spec)    │
│  TurboModuleRegistry.getEnforcing(      │
│    'CouconSdk'                          │
│  )                                      │
├──────────────────┬──────────────────────┤
│   iOS            │   Android            │
│ (Swift/ObjC)     │  (Kotlin/Java)       │
│ CouconSdk native │  CouconSdk native    │
│ SAS 엔진          │  SAS 엔진             │
└──────────────────┴──────────────────────┘

이벤트 기반 통신 패턴

SAS 엔진은 비동기적으로 동작합니다. run()으로 작업을 시작하면 네이티브 레이어에서 처리 후 NativeEventEmitter를 통해 결과를 전달합니다.

NativeEventEmitter 초기화

JS 레이어에서 NativeEventEmitter는 모듈 로드 시 한 번 생성됩니다.

// src/index.tsx 내부
import { NativeEventEmitter } from 'react-native';
import CouconSdk from './NativeCouconSdk';

// 모듈 수준에서 단일 인스턴스 생성
const eventEmitter = new NativeEventEmitter(CouconSdk);

export function addOnSASRunCompletedListener(
  callback: (event: SASRunCompletedEvent) => void
) {
  return eventEmitter.addListener('onSASRunCompleted', callback);
}

TurboModule 등록 방식

// src/NativeCouconSdk.ts
import { TurboModuleRegistry } from 'react-native';

export default TurboModuleRegistry.getEnforcing<Spec>('CouconSdk');

멀티 인덱스 패턴

SAS 엔진은 여러 작업을 동시에 처리할 수 있습니다. index 파라미터를 통해 어떤 run() 호출의 결과인지 구분합니다.

// 여러 SAS 작업 동시 실행
const subscription = addOnSASRunCompletedListener((event) => {
  switch (event.index) {
    case 1:
      handleAuthResult(event.outString);
      break;
    case 2:
      handleVerificationResult(event.outString);
      break;
    case 3:
      handleTokenResult(event.outString);
      break;
  }
});

// 병렬 실행
await Promise.all([
  run(1, 'auth-input'),
  run(2, 'verify-input'),
  run(3, 'token-input'),
]);

인덱스 번호의 의미(어떤 SAS 작업인지)는 Coucon SAS 엔진 명세를 참고하세요. 인덱스는 SAS 엔진 내부에서 처리할 작업 유형을 결정합니다.

아키텍처

아키텍처

TurboModule 아키텍처

레이어 구조

이벤트 기반 통신 패턴

NativeEventEmitter 초기화

TurboModule 등록 방식

멀티 인덱스 패턴

목차

아키텍처

아키텍처

TurboModule 아키텍처

레이어 구조

이벤트 기반 통신 패턴

NativeEventEmitter 초기화

TurboModule 등록 방식

멀티 인덱스 패턴

목차