모바일 SDK인앱 이벤트
React Native
AdStage 인앱이벤트 통합 가이드 (React Native)
목차
개요
AdStage 인앱이벤트 SDK for React Native는 다음 기능을 제공합니다:
- 표준 이벤트: 46개의 사전 정의된 이벤트 (구매, 회원가입, 레벨업 등)
- 타입 안전 이벤트: TypeScript 기반의 타입 안전한 이벤트 전송
- 커스텀 이벤트: 자유로운 이벤트명과 파라미터 구성
- 사용자 속성: 사용자 식별 및 속성 관리
- 크로스 플랫폼: Android/iOS 동일 API
설치
npm / yarn 설치
# npm
npm install @adstage/react-native-sdk
# yarn
yarn add @adstage/react-native-sdkiOS 의존성 설치
cd ios && pod install플랫폼별 추가 설정
플랫폼별 상세 설정은 딥링크 가이드를 참조하세요.
SDK 초기화
import { AdStage } from '@adstage/react-native-sdk';
// 앱 시작 시 초기화
const initializeAdStage = async () => {
try {
await AdStage.initialize({
apiKey: 'your-api-key-here',
serverUrl: 'https://api.adstage.io', // 선택사항
});
console.log('✅ AdStage SDK 초기화 완료');
} catch (error) {
console.error('❌ AdStage 초기화 실패:', error);
}
};이벤트 전송
기본 이벤트 전송
import { AdStage } from '@adstage/react-native-sdk';
// 커스텀 이벤트 전송
const result = await AdStage.event.track('button_click', {
button_id: 'purchase_btn',
screen_name: 'product_detail',
});
if (result.success) {
console.log('✅ 이벤트 전송 성공');
} else {
console.error('❌ 이벤트 전송 실패:', result.error);
}TrackEventResult 구조
interface TrackEventResult {
success: boolean;
error?: string;
}표준 이벤트 카탈로그
AdStage SDK는 46개의 표준 이벤트를 제공합니다. 타입 안전한 메서드를 통해 이벤트를 전송할 수 있습니다.
👤 사용자 라이프사이클 (6개)
// 1. 앱 최초 실행
await AdStage.event.trackFirstOpen();
// 2. 회원가입 ⭐
await AdStage.event.trackSignUp({
signUpMethod: 'email',
email: 'user@example.com',
});
// 3. 로그인 ⭐
await AdStage.event.trackLogin({
loginMethod: 'kakao',
userId: 'USER_123',
});
// 4. 로그아웃
await AdStage.event.trackLogout();
// 5. 프로필 완성
await AdStage.event.trackCompleteProfile({
profileCompletion: 85,
});
// 6. 탈퇴
await AdStage.event.trackWithdraw();📱 콘텐츠 조회 (6개)
// 1. 콘텐츠 조회
await AdStage.event.trackContentView({
contentId: 'ARTICLE_123',
contentType: 'article',
contentName: '봄 신상품 소개',
});
// 2. 상품 목록 조회
await AdStage.event.trackProductListView({
listId: 'CATEGORY_WOMEN',
listName: '여성의류',
});
// 3. 상품 상세 조회
await AdStage.event.trackProductDetailsView({
itemId: 'PROD_123',
itemName: 'Wireless Earbuds',
});
// 4. 페이지 조회 (웹뷰)
await AdStage.event.trackPageView({
pageUrl: 'https://example.com/products',
pageTitle: 'Products',
});
// 5. 화면 조회 (앱)
await AdStage.event.trackScreenView({
screenName: 'product_detail',
screenClass: 'ProductDetailScreen',
});
// 6. 콘텐츠 선택
await AdStage.event.trackSelectContent({
contentType: 'banner',
contentId: 'BANNER_001',
});🛒 전자상거래 (8개)
// 1. 장바구니 추가
await AdStage.event.trackAddToCart({
items: [
{
itemId: 'PROD_123',
itemName: 'Wireless Earbuds',
price: 99000,
quantity: 1,
},
],
value: 99000,
currency: 'KRW',
});
// 2. 장바구니 제거
await AdStage.event.trackRemoveFromCart({
items: [{ itemId: 'PROD_123', itemName: 'Wireless Earbuds' }],
value: 99000,
currency: 'KRW',
});
// 3. 위시리스트 추가
await AdStage.event.trackAddToWishlist({
itemId: 'PROD_456',
itemName: 'Smart Watch',
value: 350000,
currency: 'KRW',
});
// 4. 결제 정보 입력
await AdStage.event.trackAddPaymentInfo({
paymentMethod: 'credit_card',
});
// 5. 결제 시작
await AdStage.event.trackBeginCheckout({
items: [{ itemId: 'PROD_123' }],
value: 99000,
currency: 'KRW',
coupon: 'SUMMER10',
});
// 6. 구매 완료 ⭐⭐⭐
await AdStage.event.trackPurchase({
value: 129000,
currency: 'KRW',
transactionId: 'ORDER_20250105_001',
tax: 12900,
shipping: 3000,
coupon: 'SUMMER2025',
paymentMethod: 'credit_card',
items: [
{
itemId: 'PROD_123',
itemName: 'Wireless Earbuds',
itemCategory: 'electronics',
price: 126000,
quantity: 1,
},
],
});
// 7. 환불
await AdStage.event.trackRefund({
transactionId: 'ORDER_20250105_001',
value: 129000,
currency: 'KRW',
});🎮 게임/진행/성취 (8개)
// 1. 튜토리얼 시작
await AdStage.event.trackTutorialBegin({
tutorial_id: 'intro',
});
// 2. 튜토리얼 완료
await AdStage.event.trackTutorialComplete({
duration_seconds: 120,
});
// 3. 레벨업
await AdStage.event.trackLevelUp({
level: 25,
character: 'warrior',
});
// 4. 업적 달성
await AdStage.event.trackUnlockAchievement({
achievementId: 'first_win',
achievementName: '첫 승리',
});
// 5. 스테이지 클리어
await AdStage.event.trackStageClear({
stageName: 'Dragon Lair',
stageNumber: 10,
score: 95000,
duration: 180,
});
// 6. 게임 플레이
await AdStage.event.trackGamePlay({
level: 10,
levelName: "Dragon's Lair",
character: 'mage',
contentType: 'dungeon',
});
// 7. 보너스 획득
await AdStage.event.trackAcquireBonus({
contentType: 'reward',
itemId: 'ITEM_123',
itemName: 'Gold Chest',
quantity: 1,
});
// 8. 게임 서버 선택
await AdStage.event.trackSelectGameServer({
contentId: 'SERVER_01',
contentType: 'pvp',
itemName: 'Asia Server',
});💎 가상화폐 (2개)
// 1. 가상화폐 획득
await AdStage.event.trackEarnVirtualCurrency({
virtualCurrencyName: 'gold',
value: 1000,
});
// 2. 가상화폐 사용
await AdStage.event.trackSpendVirtualCurrency({
virtualCurrencyName: 'gold',
value: 500,
itemName: 'Health Potion',
});💬 상호작용 (5개)
// 1. 검색
await AdStage.event.trackSearch('gaming laptop');
// 2. 공유
await AdStage.event.trackShare({
method: 'kakao',
contentType: 'product',
itemId: 'PROD_789',
});
// 3. 좋아요
await AdStage.event.trackLike({
contentType: 'post',
contentId: 'POST_123',
});
// 4. 앱 평가
await AdStage.event.trackRate({
rating: 5,
maxRating: 5,
});
// 5. 일정 등록
await AdStage.event.trackSchedule({
event_name: 'meeting',
date: '2025-01-15',
});📢 인앱 광고 (2개)
// 1. 광고 노출
await AdStage.event.trackAdImpression({
adPlatform: 'admob',
adSource: 'admob_banner',
adFormat: 'banner',
adUnitName: 'home_banner',
value: 0.01,
currency: 'USD',
});
// 2. 광고 클릭
await AdStage.event.trackAdClick({
adPlatform: 'admob',
adSource: 'admob_interstitial',
adFormat: 'interstitial',
adUnitName: 'game_over_ad',
});📅 구독/체험 (4개)
// 1. 무료 체험 시작
await AdStage.event.trackStartTrial({
value: 9900,
currency: 'KRW',
trialDays: 14,
});
// 2. 구독 시작
await AdStage.event.trackSubscribe({
subscriptionId: 'premium_monthly',
value: 9900,
currency: 'KRW',
period: 'monthly',
});
// 3. 구독 해지
await AdStage.event.trackUnsubscribe('premium_monthly');
// 4. 푸시 알림 클릭
await AdStage.event.trackNotificationClick({
notificationId: 'NOTIF_123',
title: '할인 이벤트',
body: '오늘만 50% 할인!',
});💼 금융 특화 (4개)
// 1. 주식 매수
await AdStage.event.trackBuyStock({
itemId: 'AAPL',
itemName: 'Apple Inc.',
quantity: 10,
price: 185.5,
value: 1855,
currency: 'USD',
});
// 2. 주식 매도
await AdStage.event.trackSellStock({
itemId: 'AAPL',
itemName: 'Apple Inc.',
quantity: 5,
price: 190.0,
value: 950,
currency: 'USD',
});
// 3. 계좌 개설 완료
await AdStage.event.trackCompleteOpenAccount({
contentType: 'savings',
contentId: 'ACCOUNT_001',
method: 'online',
});
// 4. 카드 신청
await AdStage.event.trackApplyCard({
contentType: 'credit_card',
itemName: 'Premium Card',
itemId: 'CARD_001',
});🔧 기타 (1개)
// 패치 완료 (게임)
await AdStage.event.trackCompletePatch({
contentId: 'PATCH_2.1.0',
contentType: 'update',
});커스텀 이벤트
표준 이벤트 외에 자유롭게 이벤트를 정의할 수 있습니다.
기본 커스텀 이벤트
// 커스텀 이벤트 전송
await AdStage.event.track('custom_event_name', {
custom_param1: 'value1',
custom_param2: 123,
custom_param3: true,
});실전 예제: 기능별 이벤트
// 쿠폰 적용
await AdStage.event.track('apply_coupon', {
coupon_code: 'SUMMER25',
discount_amount: 5000,
discount_type: 'percentage',
});
// 친구 초대
await AdStage.event.track('invite_friend', {
invite_method: 'kakao',
invite_code: 'ABC123',
});
// 리뷰 작성
await AdStage.event.track('write_review', {
product_id: 'PROD_123',
rating: 5,
has_photo: true,
});
// 고객센터 문의
await AdStage.event.track('contact_support', {
inquiry_type: 'refund',
channel: 'chat',
});이벤트 명명 규칙
| 규칙 | 예시 | 설명 |
|---|---|---|
| snake_case 사용 | button_click ✅ | 소문자와 밑줄 조합 |
| 동사_명사 형식 | add_to_cart ✅ | 액션 중심 명명 |
| 구체적으로 명명 | purchase_complete ✅ | 명확한 이벤트 의미 |
| camelCase 지양 | buttonClick ❌ | 일관성 유지 |
사용자 속성 설정
사용자 식별 및 속성 설정
import { AdStage } from '@adstage/react-native-sdk';
// 사용자 속성 설정
await AdStage.setUserAttributes({
userId: 'USER_123456',
email: 'user@example.com',
name: '홍길동',
phone: '010-1234-5678',
gender: 'male',
birthYear: 1990,
// 커스텀 속성
membershipLevel: 'gold',
totalPurchaseCount: 15,
isVip: true,
});사용 시나리오
// 로그인 후 사용자 정보 설정
const handleLoginSuccess = async (user: User) => {
// 사용자 속성 설정
await AdStage.setUserAttributes({
userId: user.id,
email: user.email,
name: user.name,
});
// 로그인 이벤트 전송
await AdStage.event.trackLogin({
loginMethod: 'email',
userId: user.id,
});
};
// 로그아웃 시
const handleLogout = async () => {
await AdStage.event.trackLogout();
// 사용자 속성 초기화 (선택)
await AdStage.setUserAttributes({
userId: undefined,
email: undefined,
});
};이커머스 아이템 구조
EcommerceItem 인터페이스
interface EcommerceItem {
itemId?: string; // 상품 ID
itemName?: string; // 상품명
itemCategory?: string; // 카테고리
itemBrand?: string; // 브랜드
itemVariant?: string; // 옵션 (색상, 사이즈 등)
price?: number; // 단가
quantity?: number; // 수량
coupon?: string; // 상품별 쿠폰
index?: number; // 목록 내 순서
locationId?: string; // 위치 ID
}복수 아이템 구매 예제
await AdStage.event.trackPurchase({
value: 250000,
currency: 'KRW',
transactionId: 'ORDER_001',
items: [
{
itemId: 'SKU_001',
itemName: 'Wireless Earbuds',
itemCategory: 'Electronics',
itemBrand: 'TechBrand',
price: 150000,
quantity: 1,
},
{
itemId: 'SKU_002',
itemName: 'Phone Case',
itemCategory: 'Accessories',
price: 50000,
quantity: 2,
},
],
tax: 25000,
shipping: 0,
coupon: 'FREESHIP',
});트러블슈팅
이벤트가 전송되지 않음
-
SDK 초기화 확인
// initialize가 완료된 후 이벤트 전송 await AdStage.initialize({ apiKey: 'your-api-key' }); await AdStage.event.track('test_event'); -
API Key 확인
- 올바른 API Key가 설정되었는지 확인
-
네트워크 연결 확인
- 이벤트는 네트워크를 통해 전송됨
iOS에서 이벤트 전송 실패
-
Info.plist 확인
NSUserTrackingUsageDescription키 필요
-
ATT 권한 상태 확인
// iOS 14.5+ ATT 권한 요청 후 이벤트 전송
Android에서 이벤트 전송 실패
-
Maven 저장소 확인
maven { url "https://maven.adstage.io/repository/public" } -
minSdkVersion 확인
- 최소 24 이상 필요
파라미터가 전달되지 않음
- 파라미터 키는 snake_case 사용
- null/undefined 값은 자동으로 제외됨
디버깅 팁
// 이벤트 결과 확인
const result = await AdStage.event.track('test_event', {
debug: true,
});
console.log('Event result:', result);
// { success: true } 또는 { success: false, error: '에러 메시지' }