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

🛒 EC（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();
};

EC アイテムの構造

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 キーを確認
- 正しい API キーが設定されているか確認
ネットワーク接続を確認
- イベントはネットワーク経由で送信されます

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: 'エラーメッセージ' }

React Native

目次