React Native API

React Native SDK의 주요 API와 사용법을 설명합니다.

---

AdchainSdk 모듈

SDK 초기화

앱이 시작되면 가장 먼저 initialize()를 호출해야 합니다. 이 메서드는 네이티브 모듈을 활성화하고 애드체인 서버와 연결을 설정합니다.

import { AdchainSdk } from '@1selfworld/adchain-sdk-react-native';

await AdchainSdk.initialize({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  environment: 'PRODUCTION'  // 또는 'STAGING'
});

설정 옵션:

interface AdchainSdkConfig {
  appKey: string;        // 필수: AdChain 대시보드에서 발급
  appSecret: string;     // 필수: AdChain 대시보드에서 발급
  environment?: 'PRODUCTION' | 'STAGING';  // 선택: 기본값 'PRODUCTION'
}

초기화는 앱 시작 시 한 번만 수행합니다. App.tsx의 useEffect에서 호출하거나, 사용자가 특정 화면에 진입할 때 호출할 수 있습니다.

---

사용자 로그인

오퍼월을 사용하려면 먼저 사용자를 로그인시켜야 합니다. 앱의 사용자 ID를 AdChain에 전달하면, 애드체인 서버에서 세션을 생성합니다.

await AdchainSdk.login({
  userId: 'user-12345',
  gender: 'MALE',      // 선택 (권장)
  birthYear: 1990      // 선택 (권장)
});

사용자 정보:

interface AdchainSdkUser {
  userId: string;                        // 필수: 앱의 고유 사용자 ID
  gender?: 'MALE' | 'FEMALE' | 'OTHER' | 'UNKNOWN';  // 선택
  birthYear?: number;                    // 선택 (예: 1990)
}

userId는 필수이고, gender와 birthYear는 선택사항입니다. 다만 성별과 출생연도를 제공하면 광고 타겟팅 정확도가 높아지므로 가급적 포함하는 게 좋습니다.

주의: userId는 빈 문자열이면 안 됩니다. 앱 로그아웃 후 다른 사용자로 전환할 때는 반드시 logout() 후 login()을 호출하세요.

---

로그아웃

await AdchainSdk.logout();

현재 로그인된 사용자의 세션을 종료합니다. 로그아웃 후에는 오퍼월을 사용할 수 없습니다.

---

오퍼월 열기

전체 화면 방식으로 오퍼월을 표시합니다. 새로운 Activity(Android) 또는 ViewController(iOS)가 생성됩니다.

await AdchainSdk.openOfferwall('main_tab');

placementId는 오퍼월이 어디에서 호출되었는지 식별하는 문자열입니다. 애드체인 팀과 사전 협의하여 정의하며, 이 값에 따라 다른 URL이 로드될 수 있습니다.

placementId 예시:

• "main_tab" - 메인 탭

• "profile_section" - 프로필 섹션

• "popup_event" - 팝업 이벤트

• "banner_promo" - 배너 프로모션

---

이벤트 추적

사용자 행동을 추적하여 서버로 전송합니다. 이벤트는 즉시 전송되지 않고 배치로 모아서 보냅니다 (10개 또는 30초마다).

await AdchainSdk.trackEvent('button_click', {
  button_name: 'purchase',
  screen: 'product_detail'
});

즉시 전송하려면 flushEvents()를 호출하세요:

await AdchainSdk.trackEvent('purchase_completed', { amount: 10000 });
await AdchainSdk.flushEvents();  // 큐에 있는 모든 이벤트 즉시 전송

---

상태 확인 메서드

SDK와 사용자의 현재 상태를 확인합니다.

// SDK 초기화 여부
const isReady = await AdchainSdk.isInitialized();
if (!isReady) {
  console.log('SDK가 아직 초기화되지 않았습니다');
}

// 로그인 여부
const loggedIn = await AdchainSdk.isLoggedIn();
if (!loggedIn) {
  console.log('로그인이 필요합니다');
}

// 현재 로그인된 사용자 정보
const user = await AdchainSdk.getCurrentUser();
console.log('사용자:', user);  // null이면 로그아웃 상태

---

기타 메서드

// 커스텀 URL로 오퍼월 열기 (고급)
await AdchainSdk.openOfferwallWithUrl('https://...', 'custom_placement');

// Adjoe 오퍼월 열기 (Adjoe 통합 시)
await AdchainSdk.openAdjoeOfferwall('adjoe_placement');

// 퀴즈 목록 가져오기
const quizzes = await AdchainSdk.getQuizzes();

// 미션 목록 가져오기
const missions = await AdchainSdk.getMissions();

// 커스텀 이벤트 전송 (WebView ↔ Native 통신용)
await AdchainSdk.trackCustomEvent('custom_action', { key: 'value' });

---

AdchainOfferwallView 컴포넌트

앱 화면 내부에 임베디드 방식으로 오퍼월을 표시합니다. 탭, 섹션, 프래그먼트 등에 통합할 수 있습니다.

기본 사용법

import { AdchainOfferwallView } from '@1selfworld/adchain-sdk-react-native';

<AdchainOfferwallView
  style={{ flex: 1 }}
  placementId="benefits_tab"
  onLoad={() => console.log('오퍼월 로드 완료')}
  onError={(error) => console.error('오류:', error)}
/>

Props

interface AdchainOfferwallViewProps {
  style?: ViewStyle;              // 레이아웃 스타일
  placementId?: string;           // 오퍼월 식별자 (애드체인 팀과 협의)
  onLoad?: () => void;            // WebView 로드 완료 시
  onError?: (error: Error) => void;  // 로딩 실패 시
  onCustomEvent?: (eventType: string, payload: any) => void;  // WebView → Native 이벤트
  onDataRequest?: (requestType: string, params: any) => any;  // WebView → Native 데이터 요청
}

WebView ↔ Native 통신

onCustomEvent와 onDataRequest를 사용하면 WebView와 Native 간 양방향 통신이 가능합니다.

onCustomEvent - WebView에서 발생한 이벤트를 Native로 전달:

<AdchainOfferwallView
  placementId="main_tab"
  onCustomEvent={(eventType, payload) => {
    console.log('WebView 이벤트:', eventType, payload);

    // 실제 이벤트는 애드체인 팀과 사전 협의하여 정의
    if (eventType === 'navigate') {
      navigation.navigate(payload.screen, payload.params);
    }
  }}
/>

onDataRequest - WebView가 Native에 데이터를 요청:

<AdchainOfferwallView
  placementId="main_tab"
  onDataRequest={(requestType, params) => {
    if (requestType === 'user_points') {
      return { points: 12345, currency: 'KRW' };
    }
    else if (requestType === 'user_profile') {
      return { userId: 'user-123', nickname: 'Player1', level: 42 };
    }
    return null;
  }}
/>

실전 팁: 이벤트와 데이터 요청 타입은 애드체인 팀과 사전 협의하여 정의합니다. 위 예시는 참고용입니다.

---

Android 백버튼 처리

Android에서는 하드웨어 백버튼을 직접 처리해야 합니다. 그렇지 않으면 WebView 내부 네비게이션을 무시하고 앱이 종료됩니다.

import { BackHandler, findNodeHandle, UIManager } from 'react-native';

const offerwallViewRef = useRef(null);

useEffect(() => {
  const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
    if (offerwallViewRef.current) {
      const viewId = findNodeHandle(offerwallViewRef.current);
      if (viewId) {
        UIManager.dispatchViewManagerCommand(viewId, 'handleBackPress', []);
        return true;  // 앱 종료 방지
      }
    }
    return false;
  });

  return () => backHandler.remove();
}, []);

<AdchainOfferwallView
  ref={offerwallViewRef}
  placementId="main_tab"
  style={{ flex: 1 }}
/>

더 자세한 Android 백버튼 처리 방법은 각 고객사 통합 가이드를 참고하세요.

---

타입 정의

AdchainQuiz

interface AdchainQuiz {
  id: string;
  title: string;
  description: string;
  reward: number;
  imageUrl: string;
  difficulty: string;
  category: string;
  status: string;
}

AdchainMission

interface AdchainMission {
  id: string;
  title: string;
  description: string;
  type: 'daily' | 'weekly' | 'special';
  goal: number;
  progress: number;
  reward: number;
  status: 'active' | 'completed' | 'expired';
  expiresAt: string;
}

---

에러 처리

SDK 메서드는 실패 시 예외를 던집니다. try-catch로 처리하세요.

try {
  await AdchainSdk.initialize(config);
  console.log('초기화 성공');
} catch (error) {
  if (error instanceof Error) {
    console.error('초기화 실패:', error.message);
    Alert.alert('오류', '네트워크 연결을 확인하거나 설정을 점검하세요');
  }
}

에러 케이스:

• SDK_NOT_INITIALIZED - 초기화 전에 다른 메서드 호출

• INVALID_CREDENTIALS - appKey 또는 appSecret이 잘못됨

• NETWORK_ERROR - 서버 연결 실패

• NOT_LOGGED_IN - 로그인 전에 오퍼월 호출

---

TypeScript 지원

SDK는 TypeScript 타입 정의를 포함하고 있어서 별도 @types 패키지가 필요 없습니다. IDE에서 자동완성과 타입 체크가 지원됩니다.

---

다음 단계

• Android API 레퍼런스

• iOS API 레퍼런스

• React Native 시작하기

• 문제 해결