adstage
モバイル SDKアプリ内イベント

Unity

AdStage アプリ内イベント統合ガイド（Unity）

目次

  1. 概要
  2. 基本設定
  3. 型安全なイベント送信
  4. 標準イベントカタログ
  5. トラブルシューティング

概要

AdStage Unity SDK v3.0 は 型安全なイベントシステム を導入し、コンパイル時にエラーを防止するとともに、Android/iOS のネイティブ SDK と完全に互換性があります。

対応プラットフォーム

  • ✅ Android (API 21+)
  • ✅ iOS (12.0+)

基本設定

1. パッケージのインストール

Package Manager によるインストール：

Window → Package Manager → + → Add package from git URL
https://github.com/nbase-io/NBase-SDK-Unity.git?path=/AdStageSDK-Package

または manifest.json を直接編集：

{
  "dependencies": {
    "com.nbase.adstage": "https://github.com/nbase-io/NBase-SDK-Unity.git?path=/AdStageSDK-Package#3.0.0"
  }
}

2. SDK の初期化

using AdStageSDK;
using UnityEngine;
 
public class GameManager : MonoBehaviour
{
    void Start()
    {
        // AdStage の初期化
        AdStage.Initialize(
            apiKey: "your-api-key-here"
        );
        
        Debug.Log("✅ AdStage SDK の初期化完了");
    }
}

3. Android の設定（AndroidManifest.xml）

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- 必須の権限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
</manifest>

4. iOS の設定（Info.plist）

<!-- ネットワーク使用の権限 -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
</dict>

型安全なイベント送信

1. 最もシンプルな方法

using AdStageSDK;
using AdStageSDK.Models;
 
public class GameController : MonoBehaviour
{
    void Start()
    {
        // パラメータなしのイベント
        AdStage.TrackEvent(AdStageEvent.Custom());
        
        // ログインイベント
        AdStage.TrackEvent(
            AdStageEvent.Login(method: "email")
        );
    }
}

2. 購入イベント（検証の例）

// ✅ GOOD: value と currency をあわせて指定
AdStage.TrackEvent(
    AdStageEvent.Purchase(
        value: 29.99,
        currency: "USD",
        transactionId: "TXN_123456"
    )
);
 
// ❌ BAD: value のみ指定するとランタイムエラー！
AdStage.TrackEvent(
    AdStageEvent.Purchase(
        value: 29.99  // ❌ エラー: currency が必須！
    )
);
 
// ✅ GOOD: currency なしで transactionId のみ
AdStage.TrackEvent(
    AdStageEvent.Purchase(
        transactionId: "TXN_123456"
    )
);

3. コールバックの使用

AdStage.TrackEvent(
    AdStageEvent.Purchase(
        value: 9900.0,
        currency: "KRW",
        transactionId: "ORDER_001"
    ),
    onSuccess: (success) => {
        Debug.Log("✅ イベント送信成功");
    },
    onError: (error) => {
        Debug.LogError($"❌ イベント送信失敗: {error}");
    }
);

4. カスタムイベント（event_name の自動昇格）

標準イベント以外のアプリ独自のイベントを送信するときは、AdStageEvent.Custom を使用します。 パラメータに event_name キーを含めると、その値が実際のイベント名に自動的に昇格され、ダッシュボードに保存されます。

// 例: 'promotion_click' というカスタムイベントを送信
var promotionParams = new Dictionary<string, object>
{
    { "event_name", "promotion_click" },
    { "promotion_id", "summer_sale_2025" },
    { "screen", "home_banner" }
};
 
AdStage.TrackEvent(AdStageEvent.Custom(promotionParams));
// ダッシュボードには "promotion_click" イベントとして収集される
 
// event_name なしの一般的なカスタムイベント
var customParams = new Dictionary<string, object>
{
    { "action", "button_click" },
    { "button_id", "promo_banner" },
    { "screen", "home" },
    { "timestamp", DateTimeOffset.UtcNow.ToUnixTimeSeconds() }
};
 
AdStage.TrackEvent(AdStageEvent.Custom(customParams));
// ダッシュボードには "custom" イベントとして収集される
 
// Click、View も自由なパラメータに対応
var clickParams = new Dictionary<string, object>
{
    { "campaign_id", "SUMMER2025" },
    { "ad_group", "electronics" }
};
 
AdStage.TrackEvent(AdStageEvent.Click(clickParams));

標準イベントカタログ

AdStage Unity SDK は 46 個の標準イベントを提供します。

📌 広告トラッキング（4 個）

// 1. 広告クリック
AdStage.TrackEvent(AdStageEvent.Click(
    new Dictionary<string, object> { { "campaign_id", "CAMP_123" } }
));
 
// 2. 広告インプレッション
AdStage.TrackEvent(AdStageEvent.View(
    new Dictionary<string, object> { { "impression_id", "IMP_456" } }
));
 
// 3. アプリのインストール
AdStage.TrackEvent(AdStageEvent.Install());
 
// 4. カスタムイベント（event_name でイベント名を指定）
AdStage.TrackEvent(AdStageEvent.Custom(
    new Dictionary<string, object> { 
        { "event_name", "promotion_click" },
        { "promotion_id", "summer_sale_2025" }
    }
));

👤 ユーザーライフサイクル（5 個）

// 1. 会員登録完了
AdStage.TrackEvent(AdStageEvent.SignUp(method: "google"));
 
// 2. 会員登録開始
AdStage.TrackEvent(AdStageEvent.SignUpStart());
 
// 3. ログイン
AdStage.TrackEvent(AdStageEvent.Login(method: "email"));
 
// 4. ログアウト
AdStage.TrackEvent(AdStageEvent.Logout());
 
// 5. アプリの初回起動
AdStage.TrackEvent(AdStageEvent.FirstOpen());

📄 コンテンツ閲覧（6 個）

// 1. ホーム画面
AdStage.TrackEvent(AdStageEvent.HomeView());
 
// 2. 商品一覧
AdStage.TrackEvent(AdStageEvent.ProductListView(itemCategory: "electronics"));
 
// 3. 検索結果
AdStage.TrackEvent(AdStageEvent.SearchResultView(searchTerm: "wireless headphones"));
 
// 4. 商品詳細
AdStage.TrackEvent(AdStageEvent.ProductDetailsView(
    itemId: "PROD_123",
    itemName: "Wireless Earbuds"
));
 
// 5. ページ閲覧（Web）
AdStage.TrackEvent(AdStageEvent.PageView(
    pageUrl: "https://example.com/products",
    pageTitle: "Products"
));
 
// 6. 画面閲覧（Unity Scene）
AdStage.TrackEvent(AdStageEvent.ScreenView(
    screenName: "MainMenu",
    screenClass: "MainMenuScene"
));

🛒 E コマース（8 個）

// 1. カートに追加
var cartItem = new EcommerceItem(
    itemId : "PROD_123",
    itemName : "Wireless Earbuds",
    price : 99000.0,
    quantity : 1
);
 
AdStage.TrackEvent(AdStageEvent.AddToCart(
    value: 99000.0,
    currency: "KRW",
    items: new List<EcommerceItem> { cartItem }
));
 
// 2. カートから削除
AdStage.TrackEvent(AdStageEvent.RemoveFromCart(
    value: 50000.0,
    currency: "KRW"
));
 
// 3. ウィッシュリストに追加
AdStage.TrackEvent(AdStageEvent.AddToWishlist(
    itemId: "PROD_456",
    itemName: "Smart Watch"
));
 
// 4. 支払い情報の入力
AdStage.TrackEvent(AdStageEvent.AddPaymentInfo(paymentType: "credit_card"));
 
// 5. 決済開始
AdStage.TrackEvent(AdStageEvent.BeginCheckout(
    value: 150000.0,
    currency: "KRW"
));
 
// 6. 購入完了 ⭐⭐⭐
var purchaseItems = new List<EcommerceItem>
{
    new EcommerceItem(
        itemId: "PROD_123",
        itemName: "Wireless Earbuds",
        price: 126000.0,
        quantity: 1
    )
};
 
AdStage.TrackEvent(AdStageEvent.Purchase(
    value: 129000.0,
    currency: "KRW",
    transactionId: "ORDER_20250105_001",
    tax: 12900.0,
    shipping: 3000.0,
    coupon: "SUMMER2025",
    items: purchaseItems
));
 
// 7. 返金
AdStage.TrackEvent(AdStageEvent.Refund(
    transactionId: "ORDER_20250105_001",
    value: 129000.0,
    currency: "KRW"
));

🎮 進行 / 達成（4 個）

// 1. チュートリアル開始
AdStage.TrackEvent(AdStageEvent.TutorialBegin(
    new Dictionary<string, object> { { "tutorial_id", "intro" } }
));
 
// 2. チュートリアル完了
AdStage.TrackEvent(AdStageEvent.TutorialComplete(
    new Dictionary<string, object> { { "duration_seconds", 120 } }
));
 
// 3. レベルアップ
AdStage.TrackEvent(AdStageEvent.LevelUp(
    level: 25,
    character: "warrior"
));
 
// 4. 実績の達成
AdStage.TrackEvent(AdStageEvent.Achievement(achievementId: "first_win"));

💬 インタラクション（3 個）

// 1. 検索
AdStage.TrackEvent(AdStageEvent.Search(searchTerm: "gaming laptop"));
 
// 2. 共有
AdStage.TrackEvent(AdStageEvent.Share(
    contentType: "product",
    method: "kakao"
));
 
// 3. 広告クリック
AdStage.TrackEvent(AdStageEvent.AdClick(adPlatform: "unity", adSource:"unity_source", adFormat:"unity_format", adUnitName: "AD_12345"));

🎮 ゲーム特化（4 個）

// 1. ゲームプレイ
AdStage.TrackEvent(AdStageEvent.GamePlay(
    level: 10,
    levelName: "Dragon's Lair",
    character: "mage",
    contentType: "dungeon"
));
 
// 2. ボーナス獲得
AdStage.TrackEvent(AdStageEvent.AcquireBonus(
    contentType: "reward",
    itemId: "ITEM_123",
    itemName: "Gold Chest",
    quantity: 1
));
 
// 3. ゲームサーバーの選択
AdStage.TrackEvent(AdStageEvent.SelectGameServer(
    contentId: "SERVER_01",
    contentType: "pvp",
    itemName: "Asia Server"
));
 
// 4. パッチ完了
AdStage.TrackEvent(AdStageEvent.CompletePatch(
    contentId: "PATCH_2.1.0",
    contentType: "update"
));

📅 サブスクリプション / 体験（3 個）

// 1. 無料体験の開始
AdStage.TrackEvent(AdStageEvent.StartTrial(
    value: 9900.0,
    currency: "KRW",
    trialDays: 14
));
 
// 2. サブスクリプション開始
AdStage.TrackEvent(AdStageEvent.Subscribe(
    value: 9900.0,
    currency: "KRW",
    subscriptionId: "premium_monthly"
));
 
// 3. サブスクリプション解約
AdStage.TrackEvent(AdStageEvent.Unsubscribe(subscriptionId: "premium_monthly"));

トラブルシューティング

1. Unity Editor でイベントが送信されない

正常な動作です！ Editor ではログが出力されるだけで、実際には送信されません。

確認方法：

#if UNITY_EDITOR
Debug.Log("📊 [Editor Mode] イベントは実機でのみ送信されます");
#endif

2. Android ビルド後にイベントが送信されない

チェックリスト：

  1. Logcat の確認：adb logcat | grep -i adstage
  2. インターネット権限：AndroidManifest.xml に INTERNET 権限があるか確認
  3. Minify の無効化（テスト時）：ProGuard/R8 の設定を確認
// デバッグビルドでテスト
BuildOptions options = BuildOptions.Development | BuildOptions.AllowDebugging;

3. iOS ビルド後にイベントが送信されない

チェックリスト：

  1. Xcode Console の確認：エラーメッセージを確認
  2. Framework のリンク：AdapterAdStage.framework が埋め込まれているか確認
  3. Bitcode の設定：Build Settings で Bitcode を無効化

4. IL2CPP のビルドエラー

解決方法：

// link.xml ファイルを作成
<linker>
    <assembly fullname="AdStageSDK" preserve="all"/>
    <assembly fullname="AdStageSDK.Models" preserve="all"/>
</linker>

5. JSON シリアライズのエラー

問題：

System.ArgumentException: Invalid JSON

解決方法：

// Dictionary の値が null でないか確認
var parameters = new Dictionary<string, object>
{
    { "key1", value ?? "default" },
    { "key2", string.IsNullOrEmpty(value2) ? "unknown" : value2 }
};

6. 通貨コードの検証エラー

// ❌ 2 桁のコード
AdStageEvent.Purchase(value: 100.0, currency: "KR")
// ValidationException: "Currency must be 3-letter ISO 4217 code"
 
// ✅ 3 桁の ISO 4217 コード
AdStageEvent.Purchase(value: 100.0, currency: "KRW")  // 韓国ウォン
AdStageEvent.Purchase(value: 100.0, currency: "USD")  // 米ドル
AdStageEvent.Purchase(value: 100.0, currency: "JPY")  // 日本円

参考資料

標準の参照先

FAQ

Q: Unity Editor でテストできますか？
A: Editor ではログが出力されるだけです。実際のテストは実機で行う必要があります。

Q: Android と iOS で同じように動作しますか？
A: はい、46 個のイベントすべてが同じように動作します。

Q: Unity IAP と併用できますか？
A: はい、ProcessPurchase コールバックで AdStage のイベントを呼び出せば使用できます。

Q: オフラインでも動作しますか？
A: はい、ネイティブ SDK が自動的にイベントをキューに保存し、ネットワークの復旧時に送信します。

Q: カスタムイベントはどのように送信しますか？
A: AdStageEvent.Custom(new Dictionary<string, object> {...}) を使用します。

サポート

連絡先：

© 2025 NBase. All rights reserved.

前のページ

React Native

次のページ

Web SDK の概要とインストール

目次

AdStage アプリ内イベント統合ガイド（Unity）目次概要対応プラットフォーム基本設定1. パッケージのインストール2. SDK の初期化3. Android の設定（AndroidManifest.xml）4. iOS の設定（Info.plist）型安全なイベント送信1. 最もシンプルな方法2. 購入イベント（検証の例）3. コールバックの使用4. カスタムイベント（event_name の自動昇格）標準イベントカタログ📌 広告トラッキング（4 個）👤 ユーザーライフサイクル（5 個）📄 コンテンツ閲覧（6 個）🛒 E コマース（8 個）🎮 進行 / 達成（4 個）💬 インタラクション（3 個）🎮 ゲーム特化（4 個）📅 サブスクリプション / 体験（3 個）トラブルシューティング1. Unity Editor でイベントが送信されない2. Android ビルド後にイベントが送信されない3. iOS ビルド後にイベントが送信されない4. IL2CPP のビルドエラー5. JSON シリアライズのエラー6. 通貨コードの検証エラー参考資料標準の参照先FAQサポート