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에서 자동완성과 타입 체크가 지원됩니다.
다음 단계
Last updated