@1selfworld/adchain-sdk-react-native

React Native 및 Expo를 위한 AdChain SDK입니다.

🚨 중요 공지

Expo Go 미지원

이 SDK는 네이티브 코드를 포함하고 있어 Expo Go에서 작동하지 않습니다.

반드시 다음 방법을 사용하세요:

• ✅ Development Build: npx expo run:android 또는 npx expo run:ios
• ✅ EAS Build: eas build --profile development

🔐 보안 주의사항

app.json에 저장된 API 키는 앱 번들에 포함됩니다.

권장사항:

• ✅ 개발/테스트: app.json 사용 가능
• ⚠️ 프로덕션: 환경별 키 분리 권장
  • Android: buildConfigField 사용
  • iOS: xcconfig 파일 사용
• ❌ 절대 금지: Private API 키, 결제/인증 비밀키 노출

대안:

// 런타임에 서버에서 토큰 발급
const token = await fetchTokenFromServer();
await AdchainSDK.initializeWithToken(token);

설치

npx expo install @1selfworld/adchain-sdk-react-native expo-constants

참고: expo-constants는 peerDependency입니다. 별도로 설치해야 합니다.

설정

app.json에 다음을 추가하세요:

{
  "expo": {
    "plugins": [
      [
        "@1selfworld/adchain-sdk-react-native",
        {
          "appKey": "YOUR_APP_KEY",
          "appSecret": "YOUR_APP_SECRET",
          "environment": "PRODUCTION"
        }
      ]
    ]
  }
}

사용법

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

export default function App() {
  useEffect(() => {
    // app.json 설정을 사용한 자동 초기화
    AdchainSDK.autoInitialize()
      .then(() => console.log('SDK 준비 완료'))
      .catch(console.error);
  }, []);

  const handleLogin = async () => {
    await AdchainSDK.login({ userId: 'user123' });
  };

  const handleOfferwall = async () => {
    await AdchainSDK.openOfferwall('placement-id');
  };
}

API 레퍼런스

핵심 메서드

• autoInitialize() - app.json 설정을 사용한 자동 초기화
• initialize(config) - 수동 초기화
• login(user) - 사용자 로그인
• logout() - 사용자 로그아웃
• isLoggedIn() - 로그인 상태 확인
• getCurrentUser() - 현재 사용자 정보 조회

오퍼월

• openOfferwall(placementId?) - 오퍼월 열기
• openAdjoeOfferwall(placementId?) - ADJOE 오퍼월 열기
• openOfferwallNestAds(placementId) - NestAds 오퍼월 열기

임베디드 오퍼월 컴포넌트

AdchainOfferwallView는 탭이나 화면에 직접 임베드할 수 있는 React Native 컴포넌트입니다.

주요 특징:

• ✅ placementId만으로 서버에서 오퍼월 URL을 자동으로 가져옴
• ✅ openOfferwallNestAds와 동일한 URL 로딩 방식 사용
• ✅ 각 placement마다 다른 오퍼월 페이지 로드 가능

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

<AdchainOfferwallView
  placementId="tab_embedded_offerwall"  // 서버에서 URL 자동 조회
  style={{ flex: 1 }}
  onOfferwallOpened={() => console.log('Opened')}
  onOfferwallClosed={() => console.log('Closed')}
  onBackPressOnFirstPage={() => {
    // Android: WebView가 첫 페이지일 때 백버튼 처리
    // 앱 종료, 다른 탭 이동 등의 로직 구현
  }}
  onBackNavigated={() => {
    // Android: WebView 내부에서 뒤로가기 성공
  }}
/>

동작 방식:

1. placementId를 입력하면 SDK가 자동으로 서버 API 호출 (GET /v1/api/sdk/placement-url)
2. 서버에서 해당 placement에 매핑된 오퍼월 URL 반환
3. 반환된 URL로 WebView 로드

백버튼 이벤트 (Android, v1.0.15+):

• onBackPressOnFirstPage: WebView 스택에 페이지가 1개만 있을 때 (더 이상 뒤로갈 수 없음)
• onBackNavigated: WebView 스택에서 성공적으로 뒤로 이동했을 때

앱 개발자는 이 이벤트를 받아서 앱 종료, 탭 전환 등의 동작을 직접 구현할 수 있습니다.

퀴즈 & 미션

• loadQuizList(unitId) - 퀴즈 목록 로드
• clickQuiz(unitId, quizId) - 퀴즈 클릭
• loadMissionList(unitId) - 미션 목록 로드
• clickMission(unitId, missionId) - 미션 클릭
• claimReward(unitId) - 보상 수령

디버그

• getUserId() - 현재 사용자 ID 조회
• getIFA() - 광고 ID 조회
• isInitialized() - SDK 초기화 상태 확인

🔧 기술 노트

Swift 5.5 사용 (5.9 아님)

이 SDK는 Swift 5.5를 사용합니다. Swift 5.9에서 발견된 React Native 브리지의 선택적 매개변수 전달 문제를 피하기 위함입니다.

배경: 프로덕션 환경에서 Swift 5.9의 선택적 매개변수가 React Native로 제대로 전달되지 않아 조용히 실패하는 버그를 경험했습니다.

테스트 완료 환경:

• Xcode 14.x - 15.x
• Swift 5.5
• iOS 14.0+

Kotlin 표준 라이브러리

SDK는 네이티브 AdChain SDK에서 요구하는 kotlin-stdlib:1.9.21을 포함합니다. 버전 충돌이 발생하면 Gradle이 자동으로 호스트 앱의 버전으로 해결합니다.

React Native 의존성

SDK는 AAR의 중복 클래스를 피하기 위해 react-android에 대해 compileOnly를 사용합니다. 의존성은 호스트 애플리케이션에서 제공됩니다.

빌드 & 실행

# Prebuild (네이티브 코드 생성)
npx expo prebuild

# 플러그인 적용 확인
cat android/settings.gradle | grep jitpack
cat ios/Podfile | grep AdChainSDK

# Android 실행
npx expo run:android

# iOS 실행
npx expo run:ios

요구사항

• Expo SDK 50+
• React Native 0.74+
• iOS 14.0+
• Android API 24+
• Development Build (Expo Go 미지원)

문제 해결

"SDK not initialized" 오류

• app.json에 플러그인을 추가했는지 확인
• appKey와 appSecret이 올바른지 확인
• 다른 메서드 호출 전에 autoInitialize() 호출 확인

"Expo config not found" 오류

• Expo Go를 사용 중일 가능성이 높습니다 (미지원)
• 사용: npx expo run:android 또는 npx expo run:ios

"expo-constants not found" 오류

• peer dependency 설치: npx expo install expo-constants

Prebuild 실패

• devDependencies에 @expo/config-plugins가 있는지 확인
• 시도: rm -rf node_modules && npm install

JitPack not found (Android)

• settings.gradle에 maven { url "https://jitpack.io" }가 있는지 확인
• 인터넷 연결 확인
• 시도: cd android && ./gradlew clean

Pod install 실패 (iOS)

• Git URL이 올바른지 확인
• 태그 v1.0.45가 존재하는지 확인
• 시도: cd ios && rm -rf Pods Podfile.lock && pod install

버전 호환성

| 패키지 버전 | Android SDK | iOS SDK | Swift | Expo SDK | 주요 변경사항 | |------------|-------------|---------|-------|----------|--------------| | 1.0.21 | v1.0.32 | v1.0.47 | 5.5 | 50-53 | Android SDK v1.0.32 업데이트 (JitPack 빌드 안정화) | | 1.0.20 | v1.0.31 | v1.0.47 | 5.5 | 50-53 | AdchainOfferwallView placementId 단순화 (네이티브 SDK에서 URL 처리) | | 1.0.19 | v1.0.30 | v1.0.46 | 5.5 | 50-53 | iOS 타입 오류 수정 (AdchainSdkConfig, AdchainSdkUser) | | 1.0.18 | v1.0.30 | v1.0.46 | 5.5 | 50-53 | 네이티브 SDK 버전 업데이트 | | 1.0.15 | v1.0.29 | v1.0.45 | 5.5 | 50-53 | 백버튼 이벤트, NestAds 지원 | | 1.0.13 | v1.0.28 | v1.0.45 | 5.5 | 50-53 | NestAds 오퍼월 추가 | | 1.0.0 | v1.0.28 | v1.0.45 | 5.5 | 50-53 | 초기 릴리즈 |

알려진 제한사항

v1.0.0

• OTA 업데이트 (expo-updates) 아직 미지원 - Development Build 사용
• Swift 5.9 선택적 매개변수 버그 - 5.5 유지
• CocoaPods Trunk: AdChainSDK는 Git Pod 사용 (아직 Trunk 미등록)

v1.1.0 계획

• expo-updates 폴백 지원
• 조건부 iOS 플러그인 (Trunk vs Git)
• 서버 사이드 토큰 초기화
• 향상된 오류 메시지

라이선스

Proprietary

지원

이메일: [email protected]