React Native

AdStage 應用程式內事件整合指南（React Native）

概述

AdStage 應用程式內事件 SDK for React Native 提供以下功能：

標準事件：49 個預先定義的事件（購買、註冊、升級等）
型別安全事件：以 TypeScript 為基礎的型別安全事件傳送
自訂事件：自由組成事件名稱與參數
使用者屬性：使用者識別與屬性管理
跨平台：Android/iOS 相同 API

安裝

npm / yarn 安裝

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

安裝 iOS 相依套件

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.app', // 選填（預設值：https://api.adstage.app）
    });
    
    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;
  eventId?: string;
  error?: string;
}

標準事件目錄

AdStage SDK 提供 49 個標準事件。可以透過型別安全的方法傳送事件。

👤 使用者生命週期

// 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();

📱 內容瀏覽

// 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. 瀏覽頁面（WebView）
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',
});

🛒 電子商務（7 個）

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

🎮 遊戲/進度/成就（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({
  gender: 'male',     // 'male' | 'female' | 'other'
  country: 'KR',      // 國家代碼
  city: 'Seoul',      // 城市
  age: '28',          // 年齡（字串）
  language: 'ko-KR',  // 語言
});
 
// 查詢已設定的使用者屬性
const attributes = await AdStage.getUserAttributes();

UserAttributes 介面

interface UserAttributes {
  gender?: string;    // male, female, other
  country?: string;   // 國家代碼: KR、US、JP 等
  city?: string;      // 城市
  age?: string;       // 年齡
  language?: string;  // 語言: ko-KR、en-US 等
}

使用情境

// 登入後設定使用者資訊
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();
};

電商商品結構

EcommerceItem 介面

interface EcommerceItem {
  itemId: string;           // 商品 ID（必填）
  itemName: string;         // 商品名稱（必填）
  price?: number;           // 單價
  quantity?: number;        // 數量
  itemCategory?: string;    // 類別
  itemBrand?: string;       // 品牌
}

多商品購買範例

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, eventId: '...' } 或 { success: false, error: '錯誤訊息' }