Unity

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

概述

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"
));

🛒 電子商務（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 建置後事件未傳送

檢查清單：

確認 Logcat：adb logcat | grep -i adstage
網際網路權限：確認 AndroidManifest.xml 中是否有 INTERNET 權限
停用 Minify（測試用）：確認 ProGuard/R8 設定

// 以偵錯版本進行測試
BuildOptions options = BuildOptions.Development | BuildOptions.AllowDebugging;

3. iOS 建置後事件未傳送

檢查清單：

確認 Xcode Console：查看錯誤訊息
Framework 連結：確認是否已嵌入 AdapterAdStage.framework
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> {...})

支援

聯絡方式：

電子郵件：support@nbase.io