# @1selfworld/adchain-sdk-react-native > AdChain SDK for React Native with Expo support Latest version **1.0.28** (published 2026-09-08) · MIT license · 80 weekly downloads ## Install ```sh npm install @1selfworld/adchain-sdk-react-native pnpm add @1selfworld/adchain-sdk-react-native yarn add @1selfworld/adchain-sdk-react-native bun add @1selfworld/adchain-sdk-react-native ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 1.0.28 | | Published | 2026-09-08 | | First published | 2025-10-22 | | Weekly downloads | 80 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 160.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | 1SelfWorld Labs | | Maintainers | fly33499, chocosprite | | Keywords | react-native, expo, adchain, ads, offerwall, ios, android | ## Links - npm: https://www.npmjs.com/package/@1selfworld/adchain-sdk-react-native - Repository: https://github.com/1selfworld-labs/adchain-sdk-react-native - Homepage: https://github.com/1selfworld-labs/adchain-sdk-react-native#readme - Issues: https://github.com/1selfworld-labs/adchain-sdk-react-native/issues - npm.io page: https://npm.io/package/@1selfworld/adchain-sdk-react-native ## Alternatives - [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads - [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads - [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads - [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads - [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads ## Recent versions - 1.0.28 (latest) — 2026-09-08 - 1.0.27-rc.2 (rc) — 2026-06-30 - 1.0.23-beta.1 (beta) — 2025-11-13 - 1.0.27 — 2026-07-02 - 1.0.26 — 2026-04-07 - 1.0.25 — 2026-02-12 - 1.0.24 — 2026-01-21 - 1.0.23 — 2025-11-13 - 1.0.22 — 2025-10-31 - 1.0.21 — 2025-10-29 - 1.0.20 — 2025-10-29 - 1.0.19 — 2025-10-29 - 1.0.18 — 2025-10-29 - 1.0.17 — 2025-10-29 - 1.0.16 — 2025-10-29 - … 14 more at https://npm.io/package/@1selfworld/adchain-sdk-react-native/versions ## README # @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 키, 결제/인증 비밀키 노출 **대안:** ```typescript // 런타임에 서버에서 토큰 발급 const token = await fetchTokenFromServer(); await AdchainSDK.initializeWithToken(token); ``` ## 설치 ```bash npx expo install @1selfworld/adchain-sdk-react-native expo-constants ``` **참고:** `expo-constants`는 peerDependency입니다. 별도로 설치해야 합니다. ## 설정 `app.json`에 다음을 추가하세요: ```json { "expo": { "plugins": [ [ "@1selfworld/adchain-sdk-react-native", { "appKey": "YOUR_APP_KEY", "appSecret": "YOUR_APP_SECRET", "environment": "PRODUCTION" } ] ] } } ``` ## 사용법 ```typescript 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마다 다른 오퍼월 페이지 로드 가능 ```typescript import { AdchainOfferwallView } from '@1selfworld/adchain-sdk-react-native'; 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`를 사용합니다. 의존성은 호스트 애플리케이션에서 제공됩니다. ## 빌드 & 실행 ```bash # 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.25 | v1.0.34 | v1.0.49 | 5.5 | 50-53 | Android SDK v1.0.34 + iOS SDK v1.0.49 업데이트 | | 1.0.24 | v1.0.33 | v1.0.48 | 5.5 | 50-53 | iOS SDK v1.0.48 업데이트 | | 1.0.23 | v1.0.33 | v1.0.47 | 5.5 | 50-53 | Android SDK v1.0.33 업데이트 | | 1.0.22 | v1.0.32 | v1.0.47 | 5.5 | 50-53 | iOS SDK 버전 v1.0.47 수정 | | 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 미등록) ## 라이선스 Proprietary ## 지원 이메일: contacts@1self.world --- _Source: https://npm.io/package/@1selfworld/adchain-sdk-react-native · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._