1.0.1 • Published 5h ago

@1selfworld/adchain-sdk-core-react-native

Licence

MIT

Version

1.0.1

Deps

Size

156 kB

Vulns

Weekly

Summary Dependency Versions

@1selfworld/adchain-sdk-core-react-native

Adjoe-free Core build. Forked from adchain-sdk-react-native@1.0.26 (commit 372cb93 기준) — Adjoe 관련 API/의존성 제거판. 미래 수동 sync 기준점.

React Native 및 Expo를 위한 AdChain Core 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-core-react-native expo-constants

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

설정

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

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

사용법

import { useEffect } from 'react';
import AdchainSDK from '@1selfworld/adchain-sdk-core-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?) - 오퍼월 열기
openOfferwallNestAds(placementId) - NestAds 오퍼월 열기

임베디드 오퍼월 컴포넌트

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

주요 특징:

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

import { AdchainOfferwallView } from '@1selfworld/adchain-sdk-core-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 내부에서 뒤로가기 성공
  }}
/>

동작 방식:

placementId를 입력하면 SDK가 자동으로 서버 API 호출 (GET /v1/api/sdk/placement-url)
서버에서 해당 placement에 매핑된 오퍼월 URL 반환
반환된 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.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

Keywords

react-native expo adchain ads offerwall ios android