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: '错误消息' }