StageUp
Mobile SDKDeep Link

React Native

AdStage In-App Event Integration Guide (React Native)

Table of Contents

  1. Overview
  2. Installation
  3. SDK Initialization
  4. Sending Events
  5. Standard Event Catalog
  6. Custom Events
  7. Setting User Attributes
  8. Troubleshooting

Overview

The AdStage In-App Event SDK for React Native provides the following features:

  • Standard events: 49 predefined events (purchase, sign-up, level up, etc.)
  • Type-safe events: Type-safe event delivery based on TypeScript
  • Custom events: Freely configurable event names and parameters
  • User attributes: User identification and attribute management
  • Cross-platform: Identical API for Android/iOS

Installation

Installing via npm / yarn

# npm
npm install @adstage/react-native-sdk
 
# yarn
yarn add @adstage/react-native-sdk

Installing iOS dependencies

cd ios && pod install

Additional platform-specific setup

For detailed platform-specific setup, refer to the Deep Link Guide.

SDK Initialization

import { AdStage } from '@adstage/react-native-sdk';
 
// 앱 시작 시 초기화
const initializeAdStage = async () => {
  try {
    await AdStage.initialize({
      apiKey: 'your-api-key-here',
      serverUrl: 'https://api.adstage.app', // 선택사항 (기본값: https://api.adstage.app)
    });
    
    console.log('✅ AdStage SDK 초기화 완료');
  } catch (error) {
    console.error('❌ AdStage 초기화 실패:', error);
  }
};

Sending Events

Sending a basic event

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 structure

interface TrackEventResult {
  success: boolean;
  eventId?: string;
  error?: string;
}

Standard Event Catalog

The AdStage SDK provides 49 standard events. You can send events through type-safe methods.

👤 User Lifecycle

// 1. 앱 최초 실행
await AdStage.event.trackFirstOpen();
 
// 2. 회원가입 시작
await AdStage.event.trackSignUpStart();
 
// 3. 회원가입 완료 ⭐
//    method 인자에는 가입 방법(email, google, apple, kakao, naver 등)을 전달
await AdStage.event.trackSignUp('email');
 
// 4. 로그인 ⭐
//    method 인자에는 로그인 방법(email, google, apple, kakao, naver 등)을 전달
await AdStage.event.trackLogin('kakao');
 
// 5. 로그아웃
await AdStage.event.trackLogout();

📱 Content Viewing

// 1. 홈 화면 조회
await AdStage.event.trackHomeView();
 
// 2. 상품 목록 조회 (인자는 상품 카테고리)
await AdStage.event.trackProductListView('여성의류');
 
// 3. 검색 결과 조회 (인자는 검색어)
await AdStage.event.trackSearchResultView('무선 이어폰');
 
// 4. 상품 상세 조회
await AdStage.event.trackProductDetailsView({
  itemId: 'PROD_123',
  itemName: 'Wireless Earbuds',
});
 
// 5. 페이지 조회 (웹뷰)
await AdStage.event.trackPageView({
  pageUrl: 'https://example.com/products',
  pageTitle: 'Products',
});
 
// 6. 화면 조회 (앱)
await AdStage.event.trackScreenView({
  screenName: 'product_detail',
  screenClass: 'ProductDetailScreen',
});
 
// 7. 콘텐츠 선택
await AdStage.event.trackSelectContent({
  contentType: 'banner',
  contentId: 'BANNER_001',
});

🛒 E-commerce (7 events)

// 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', itemName: 'Wireless Earbuds' }],
  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',
});

🎮 Game / Progress / Achievement (8 events)

// 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',
});

💎 Virtual Currency (2 events)

// 1. 가상화폐 획득
await AdStage.event.trackEarnVirtualCurrency({
  virtualCurrencyName: 'gold',
  value: 1000,
});
 
// 2. 가상화폐 사용
await AdStage.event.trackSpendVirtualCurrency({
  virtualCurrencyName: 'gold',
  value: 500,
  itemName: 'Health Potion',
});

💬 Interaction (5 events)

// 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',
});

📢 In-App Ads (2 events)

// 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',
});

📅 Subscription / Trial (4 events)

// 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% 할인!',
});

💼 Finance-Specific (4 events)

// 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',
});

🔧 Miscellaneous (1 event)

// 패치 완료 (게임)
await AdStage.event.trackCompletePatch({
  contentId: 'PATCH_2.1.0',
  contentType: 'update',
});

Custom Events

In addition to standard events, you can freely define your own events.

Basic custom event

// 커스텀 이벤트 전송
await AdStage.event.track('custom_event_name', {
  custom_param1: 'value1',
  custom_param2: 123,
  custom_param3: true,
});

Practical example: feature-specific events

// 쿠폰 적용
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',
});

Event naming conventions

ConventionExampleDescription
Use snake_casebutton_click ✅Combination of lowercase letters and underscores
verb_noun formatadd_to_cart ✅Action-centered naming
Name specificallypurchase_complete ✅Clear event meaning
Avoid camelCasebuttonClick ❌Maintain consistency

Setting User Attributes

User identification and attribute setting

User attributes you set are automatically included in all events sent afterward.

import { AdStage } from '@adstage/react-native-sdk';
 
// 사용자 속성 설정
await AdStage.setUserAttributes({
  gender: 'male',     // 'male' | 'female' | 'other'
  country: 'KR',      // 국가 코드
  city: 'Seoul',      // 도시
  age: '28',          // 나이 (문자열)
  language: 'ko-KR',  // 언어
});
 
// 설정된 사용자 속성 조회
const attributes = await AdStage.getUserAttributes();

UserAttributes interface

interface UserAttributes {
  gender?: string;    // male, female, other
  country?: string;   // 국가 코드: KR, US, JP 등
  city?: string;      // 도시
  age?: string;       // 나이
  language?: string;  // 언어: ko-KR, en-US 등
}

Usage scenarios

// 로그인 후 사용자 정보 설정
const handleLoginSuccess = async (user: User) => {
  // 사용자 속성 설정
  await AdStage.setUserAttributes({
    country: user.country,
    city: user.city,
    language: user.language,
  });
  
  // 로그인 이벤트 전송 (method 인자는 로그인 방법)
  await AdStage.event.trackLogin('email');
};
 
// 로그아웃 시
const handleLogout = async () => {
  await AdStage.event.trackLogout();
  
  // 사용자 속성 초기화 (선택)
  await AdStage.clearUserAttributes();
};

E-commerce Item Structure

EcommerceItem interface

interface EcommerceItem {
  itemId: string;           // 상품 ID (필수)
  itemName: string;         // 상품명 (필수)
  price?: number;           // 단가
  quantity?: number;        // 수량
  itemCategory?: string;    // 카테고리
  itemBrand?: string;       // 브랜드
}

Multiple-item purchase example

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',
});

Troubleshooting

Events are not being sent

  1. Check SDK initialization

    // initialize가 완료된 후 이벤트 전송
await AdStage.initialize({ apiKey: 'your-api-key' });
await AdStage.event.track('test_event');

  2. Check the API Key

    • Verify that the correct API Key is set

  3. Check the network connection

    • Events are sent over the network

Event sending fails on iOS

  1. Check Info.plist

    • The NSUserTrackingUsageDescription key is required

  2. Check ATT permission status

    // iOS 14.5+ ATT 권한 요청 후 이벤트 전송

Event sending fails on Android

  1. Check the Maven repository

    maven { url "https://maven.adstage.io/repository/public" }

  2. Check minSdkVersion

    • Requires a minimum of 24 or higher

Parameters are not being passed

  • Parameter keys must use snake_case
  • null/undefined values are automatically excluded

Debugging tips

// 이벤트 결과 확인
const result = await AdStage.event.track('test_event', {
  debug: true,
});
 
console.log('Event result:', result);
// { success: true, eventId: '...' } 또는 { success: false, error: '에러 메시지' }

Previous page

iOS

Next page

Unity

Table of Contents

AdStage In-App Event Integration Guide (React Native)Table of ContentsOverviewInstallationInstalling via npm / yarnInstalling iOS dependenciesAdditional platform-specific setupSDK InitializationSending EventsSending a basic eventTrackEventResult structureStandard Event Catalog👤 User Lifecycle📱 Content Viewing🛒 E-commerce (7 events)🎮 Game / Progress / Achievement (8 events)💎 Virtual Currency (2 events)💬 Interaction (5 events)📢 In-App Ads (2 events)📅 Subscription / Trial (4 events)💼 Finance-Specific (4 events)🔧 Miscellaneous (1 event)Custom EventsBasic custom eventPractical example: feature-specific eventsEvent naming conventionsSetting User AttributesUser identification and attribute settingUserAttributes interfaceUsage scenariosE-commerce Item StructureEcommerceItem interfaceMultiple-item purchase exampleTroubleshootingEvents are not being sentEvent sending fails on iOSEvent sending fails on AndroidParameters are not being passedDebugging tips