React Native

AdStage In-App Events Integration Guide (React Native)

Overview
Installation
SDK Initialization
Sending Events
Standard Event Catalog
Custom Events
User Attributes
Troubleshooting

Overview

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

Standard Events: 46 predefined events (purchase, sign-up, level-up, etc.)
Type-Safe Events: TypeScript-based type-safe event sending
Custom Events: Flexible event names and parameter configuration
User Attributes: User identification and attribute management
Cross-Platform: Same API for Android/iOS

Installation

npm / yarn Installation

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

iOS Dependency Installation

cd ios && pod install

Platform-Specific Configuration

For detailed platform configuration, refer to the Deep Link Guide.

SDK Initialization

import { AdStage } from '@adstage/react-native-sdk';
 
// Initialize on app start
const initializeAdStage = async () => {
  try {
    await AdStage.initialize({
      apiKey: 'your-api-key-here',
      serverUrl: 'https://api.adstage.io', // Optional
    });
    
    console.log('✅ AdStage SDK initialized');
  } catch (error) {
    console.error('❌ AdStage initialization failed:', error);
  }
};

Sending Events

Basic Event Sending

import { AdStage } from '@adstage/react-native-sdk';
 
// Send custom event
const result = await AdStage.event.track('button_click', {
  button_id: 'purchase_btn',
  screen_name: 'product_detail',
});
 
if (result.success) {
  console.log('✅ Event sent successfully');
} else {
  console.error('❌ Event sending failed:', result.error);
}

TrackEventResult Structure

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

Standard Event Catalog

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

👤 User Lifecycle (6)

// 1. First app open
await AdStage.event.trackFirstOpen();
 
// 2. Sign up ⭐
await AdStage.event.trackSignUp({
  signUpMethod: 'email',
  email: 'user@example.com',
});
 
// 3. Login ⭐
await AdStage.event.trackLogin({
  loginMethod: 'kakao',
  userId: 'USER_123',
});
 
// 4. Logout
await AdStage.event.trackLogout();
 
// 5. Complete profile
await AdStage.event.trackCompleteProfile({
  profileCompletion: 85,
});
 
// 6. Account deletion
await AdStage.event.trackWithdraw();

📱 Content View (6)

// 1. Content view
await AdStage.event.trackContentView({
  contentId: 'ARTICLE_123',
  contentType: 'article',
  contentName: 'Spring New Products',
});
 
// 2. Product list view
await AdStage.event.trackProductListView({
  listId: 'CATEGORY_WOMEN',
  listName: 'Women\'s Clothing',
});
 
// 3. Product details view
await AdStage.event.trackProductDetailsView({
  itemId: 'PROD_123',
  itemName: 'Wireless Earbuds',
});
 
// 4. Page view (WebView)
await AdStage.event.trackPageView({
  pageUrl: 'https://example.com/products',
  pageTitle: 'Products',
});
 
// 5. Screen view (App)
await AdStage.event.trackScreenView({
  screenName: 'product_detail',
  screenClass: 'ProductDetailScreen',
});
 
// 6. Content selection
await AdStage.event.trackSelectContent({
  contentType: 'banner',
  contentId: 'BANNER_001',
});

🛒 E-Commerce (8)

// 1. Add to cart
await AdStage.event.trackAddToCart({
  items: [
    {
      itemId: 'PROD_123',
      itemName: 'Wireless Earbuds',
      price: 99000,
      quantity: 1,
    },
  ],
  value: 99000,
  currency: 'KRW',
});
 
// 2. Remove from cart
await AdStage.event.trackRemoveFromCart({
  items: [{ itemId: 'PROD_123', itemName: 'Wireless Earbuds' }],
  value: 99000,
  currency: 'KRW',
});
 
// 3. Add to wishlist
await AdStage.event.trackAddToWishlist({
  itemId: 'PROD_456',
  itemName: 'Smart Watch',
  value: 350000,
  currency: 'KRW',
});
 
// 4. Add payment info
await AdStage.event.trackAddPaymentInfo({
  paymentMethod: 'credit_card',
});
 
// 5. Begin checkout
await AdStage.event.trackBeginCheckout({
  items: [{ itemId: 'PROD_123' }],
  value: 99000,
  currency: 'KRW',
  coupon: 'SUMMER10',
});
 
// 6. Purchase ⭐⭐⭐
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. Refund
await AdStage.event.trackRefund({
  transactionId: 'ORDER_20250105_001',
  value: 129000,
  currency: 'KRW',
});

🎮 Game/Progress/Achievement (8)

// 1. Tutorial begin
await AdStage.event.trackTutorialBegin({
  tutorial_id: 'intro',
});
 
// 2. Tutorial complete
await AdStage.event.trackTutorialComplete({
  duration_seconds: 120,
});
 
// 3. Level up
await AdStage.event.trackLevelUp({
  level: 25,
  character: 'warrior',
});
 
// 4. Unlock achievement
await AdStage.event.trackUnlockAchievement({
  achievementId: 'first_win',
  achievementName: 'First Victory',
});
 
// 5. Stage clear
await AdStage.event.trackStageClear({
  stageName: 'Dragon Lair',
  stageNumber: 10,
  score: 95000,
  duration: 180,
});
 
// 6. Game play
await AdStage.event.trackGamePlay({
  level: 10,
  levelName: "Dragon's Lair",
  character: 'mage',
  contentType: 'dungeon',
});
 
// 7. Acquire bonus
await AdStage.event.trackAcquireBonus({
  contentType: 'reward',
  itemId: 'ITEM_123',
  itemName: 'Gold Chest',
  quantity: 1,
});
 
// 8. Select game server
await AdStage.event.trackSelectGameServer({
  contentId: 'SERVER_01',
  contentType: 'pvp',
  itemName: 'Asia Server',
});

💎 Virtual Currency (2)

// 1. Earn virtual currency
await AdStage.event.trackEarnVirtualCurrency({
  virtualCurrencyName: 'gold',
  value: 1000,
});
 
// 2. Spend virtual currency
await AdStage.event.trackSpendVirtualCurrency({
  virtualCurrencyName: 'gold',
  value: 500,
  itemName: 'Health Potion',
});

💬 Interaction (5)

// 1. Search
await AdStage.event.trackSearch('gaming laptop');
 
// 2. Share
await AdStage.event.trackShare({
  method: 'kakao',
  contentType: 'product',
  itemId: 'PROD_789',
});
 
// 3. Like
await AdStage.event.trackLike({
  contentType: 'post',
  contentId: 'POST_123',
});
 
// 4. Rate app
await AdStage.event.trackRate({
  rating: 5,
  maxRating: 5,
});
 
// 5. Schedule
await AdStage.event.trackSchedule({
  event_name: 'meeting',
  date: '2025-01-15',
});

📢 In-App Ads (2)

// 1. Ad impression
await AdStage.event.trackAdImpression({
  adPlatform: 'admob',
  adSource: 'admob_banner',
  adFormat: 'banner',
  adUnitName: 'home_banner',
  value: 0.01,
  currency: 'USD',
});
 
// 2. Ad click
await AdStage.event.trackAdClick({
  adPlatform: 'admob',
  adSource: 'admob_interstitial',
  adFormat: 'interstitial',
  adUnitName: 'game_over_ad',
});

📅 Subscription/Trial (4)

// 1. Start trial
await AdStage.event.trackStartTrial({
  value: 9900,
  currency: 'KRW',
  trialDays: 14,
});
 
// 2. Subscribe
await AdStage.event.trackSubscribe({
  subscriptionId: 'premium_monthly',
  value: 9900,
  currency: 'KRW',
  period: 'monthly',
});
 
// 3. Unsubscribe
await AdStage.event.trackUnsubscribe('premium_monthly');
 
// 4. Push notification click
await AdStage.event.trackNotificationClick({
  notificationId: 'NOTIF_123',
  title: 'Sale Event',
  body: '50% off today only!',
});

💼 Finance-Specific (4)

// 1. Buy stock
await AdStage.event.trackBuyStock({
  itemId: 'AAPL',
  itemName: 'Apple Inc.',
  quantity: 10,
  price: 185.5,
  value: 1855,
  currency: 'USD',
});
 
// 2. Sell stock
await AdStage.event.trackSellStock({
  itemId: 'AAPL',
  itemName: 'Apple Inc.',
  quantity: 5,
  price: 190.0,
  value: 950,
  currency: 'USD',
});
 
// 3. Complete account opening
await AdStage.event.trackCompleteOpenAccount({
  contentType: 'savings',
  contentId: 'ACCOUNT_001',
  method: 'online',
});
 
// 4. Apply for card
await AdStage.event.trackApplyCard({
  contentType: 'credit_card',
  itemName: 'Premium Card',
  itemId: 'CARD_001',
});

🔧 Other (1)

// Complete patch (Game)
await AdStage.event.trackCompletePatch({
  contentId: 'PATCH_2.1.0',
  contentType: 'update',
});

Custom Events

You can freely define events beyond standard events.

Basic Custom Event

// Send custom event
await AdStage.event.track('custom_event_name', {
  custom_param1: 'value1',
  custom_param2: 123,
  custom_param3: true,
});

Practical Examples: Feature-Specific Events

// Apply coupon
await AdStage.event.track('apply_coupon', {
  coupon_code: 'SUMMER25',
  discount_amount: 5000,
  discount_type: 'percentage',
});
 
// Invite friend
await AdStage.event.track('invite_friend', {
  invite_method: 'kakao',
  invite_code: 'ABC123',
});
 
// Write review
await AdStage.event.track('write_review', {
  product_id: 'PROD_123',
  rating: 5,
  has_photo: true,
});
 
// Contact support
await AdStage.event.track('contact_support', {
  inquiry_type: 'refund',
  channel: 'chat',
});

Event Naming Conventions

Rule	Example	Description
Use snake_case	`button_click` ✅	Lowercase with underscores
verb_noun format	`add_to_cart` ✅	Action-oriented naming
Be specific	`purchase_complete` ✅	Clear event meaning
Avoid camelCase	`buttonClick` ❌	Maintain consistency

User Attributes

User Identification and Attributes

import { AdStage } from '@adstage/react-native-sdk';
 
// Set user attributes
await AdStage.setUserAttributes({
  userId: 'USER_123456',
  email: 'user@example.com',
  name: 'John Doe',
  phone: '010-1234-5678',
  gender: 'male',
  birthYear: 1990,
  
  // Custom attributes
  membershipLevel: 'gold',
  totalPurchaseCount: 15,
  isVip: true,
});

Usage Scenarios

// Set user info after login
const handleLoginSuccess = async (user: User) => {
  // Set user attributes
  await AdStage.setUserAttributes({
    userId: user.id,
    email: user.email,
    name: user.name,
  });
  
  // Send login event
  await AdStage.event.trackLogin({
    loginMethod: 'email',
    userId: user.id,
  });
};
 
// On logout
const handleLogout = async () => {
  await AdStage.event.trackLogout();
  
  // Clear user attributes (optional)
  await AdStage.setUserAttributes({
    userId: undefined,
    email: undefined,
  });
};

E-Commerce Item Structure

EcommerceItem Interface

interface EcommerceItem {
  itemId?: string;          // Product ID
  itemName?: string;        // Product name
  itemCategory?: string;    // Category
  itemBrand?: string;       // Brand
  itemVariant?: string;     // Variant (color, size, etc.)
  price?: number;           // Unit price
  quantity?: number;        // Quantity
  coupon?: string;          // Item-specific coupon
  index?: number;           // Position in list
  locationId?: string;      // Location ID
}

Multiple Items 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 Not Being Sent

Verify SDK Initialization
// Send events after initialize completes await AdStage.initialize({ apiKey: 'your-api-key' }); await AdStage.event.track('test_event');
Verify API Key
- Ensure correct API Key is configured
Check Network Connection
- Events are sent over the network

Event Sending Fails on iOS

Check Info.plist
- NSUserTrackingUsageDescription key required
Check ATT Permission Status
// Send events after ATT permission request on iOS 14.5+

Event Sending Fails on Android

Check Maven Repository
maven { url "https://maven.adstage.io/repository/public" }
Check minSdkVersion
- Minimum 24 required

Parameters Not Being Passed

Use snake_case for parameter keys
null/undefined values are automatically excluded

Debugging Tips

// Check event result
const result = await AdStage.event.track('test_event', {
  debug: true,
});
 
console.log('Event result:', result);
// { success: true } or { success: false, error: 'error message' }