Android

AdStage 應用程式內事件串接指南（Android）

概述

AdStage 應用程式內事件透過追蹤使用者行為與應用程式事件，為行銷分析與最佳化提供支援。

主要功能

靈活的事件傳送：從簡單呼叫到詳細的上下文
自動收集上下文：自動包含裝置資訊、使用者屬性
工作階段管理：自動追蹤與管理工作階段
Builder 模式：支援可讀性高的 DSL 風格
非同步處理：基於 Coroutine 的 suspend 函式
離線支援：網路重新連線時自動重新傳送

基本設定

1. 新增 Gradle 相依套件

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://repo.nbase.io/repository/nbase-releases") }
    }
}

build.gradle.kts (Module: app)

dependencies {
    implementation("io.nbase:nbase-adapter-adstage:3.0.9")
    
    // 必要相依套件
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    implementation("com.squareup.okhttp3:okhttp:4.11.0")
}

2. 初始化 SDK

import io.nbase.adapter.adstage.AdStage
 
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // 初始化 AdStage
        AdStage.initialize(
            context = this,
            apiKey = "your-api-key-here",
            serverUrl = "https://api.adstage.app" // 選用，可使用預設值
        )
        
        Log.d("AdStage", "✅ SDK 초기화 완료")
    }
}

3. 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" />
    
    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">
        
        <!-- ... -->
        
    </application>
</manifest>

類型安全的事件傳送

1. 最簡單的方式

trackEvent 同時提供 suspend 函式與回呼多載。 suspend 函式需在協程作用域內呼叫，在協程之外則使用回呼版本。

import io.nbase.adapter.adstage.AdStage
import io.nbase.adapter.adstage.models.AdStageEvent
import io.nbase.adapter.adstage.models.SignUpMethod
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
 
CoroutineScope(Dispatchers.IO).launch {
    // 無參數的事件（suspend）
    AdStage.trackEvent(AdStageEvent.FirstOpen())
 
    // 登入事件（method 為字串，使用 SignUpMethod enum 的 value）
    AdStage.trackEvent(
        AdStageEvent.Login(method = SignUpMethod.EMAIL.value)
    )
}
 
// 回呼版本（不使用協程呼叫）
AdStage.trackEvent(AdStageEvent.Login(method = SignUpMethod.EMAIL.value)) { result ->
    when (result) {
        is TrackEventResult.Success -> Log.d("AdStage", "전송 성공")
        is TrackEventResult.Failure -> Log.e("AdStage", "전송 실패: ${result.error}")
    }
}

2. 購買事件（驗證範例）

存在 value 時 currency 為必填。缺少時會在事件物件建立時點拋出 IllegalArgumentException（執行階段驗證）。

// ✅ GOOD: value 與 currency 一起提供
AdStage.trackEvent(
    AdStageEvent.Purchase(
        value = 29.99,
        currency = "USD",
        transactionId = "TXN_123456"
    )
)
 
// ❌ BAD: 僅提供 value 時會拋出執行階段例外（IllegalArgumentException）
AdStage.trackEvent(
    AdStageEvent.Purchase(
        value = 29.99  // ❌ 例外：有 value 時 currency 必填！
    )
)
 
// ✅ GOOD: 不帶 currency，只提供 transactionId
AdStage.trackEvent(
    AdStageEvent.Purchase(
        transactionId = "TXN_123456"
    )
)

3. 商品瀏覽

// 帶參數
AdStage.trackEvent(
    AdStageEvent.ProductDetailsView(
        itemId = "PROD_123",
        itemName = "Wireless Earbuds"
    )
)
 
// 不帶參數
AdStage.trackEvent(AdStageEvent.ProductListView())

4. 自訂事件（event_name 自動提升）

除標準事件外，傳送應用程式特有的事件時請使用 AdStageEvent.Custom。若在參數中包含 event_name 鍵，該值會自動提升為實際的事件名稱並儲存到儀表板。

// 範例：傳送名為 'promotion_click' 的自訂事件
AdStage.trackEvent(
    AdStageEvent.Custom(
        params = mapOf(
            "event_name" to "promotion_click",
            "promotion_id" to "summer_sale_2025",
            "screen" to "home_banner"
        )
    )
)
// 在儀表板中會作為 "promotion_click" 事件收集
 
// 不帶 event_name 的一般自訂事件
AdStage.trackEvent(
    AdStageEvent.Custom(
        params = mapOf(
            "action" to "button_click",
            "button_id" to "promo_banner",
            "screen" to "home",
            "timestamp" to System.currentTimeMillis()
        )
    )
)
// 在儀表板中會作為 "custom" 事件收集
 
// Click、View 同樣支援自由參數
AdStage.trackEvent(
    AdStageEvent.Click(
        params = mapOf(
            "campaign_id" to "SUMMER2025",
            "ad_group" to "electronics"
        )
    )
)

標準事件目錄

AdStage SDK 提供 46 個標準事件。

📌 廣告追蹤（4 個）

// 1. 廣告點擊
AdStage.trackEvent(
    AdStageEvent.Click(
        params = mapOf("campaign_id" to "CAMP_123")
    )
)
 
// 2. 廣告曝光
AdStage.trackEvent(
    AdStageEvent.View(
        params = mapOf("impression_id" to "IMP_456")
    )
)
 
// 3. 應用程式安裝
AdStage.trackEvent(AdStageEvent.Install())
 
// 4. 自訂事件（以 event_name 指定事件名稱）
AdStage.trackEvent(
    AdStageEvent.Custom(
        params = mapOf(
            "event_name" to "promotion_click",
            "promotion_id" to "summer_sale_2025"
        )
    )
)

👤 使用者生命週期（5 個）

SignUp 與 Login 的 method 是字串（String?）參數。可以直接傳入字串，也可以使用 SDK 提供的 SignUpMethod enum 的 .value。

// SDK 提供的 SignUpMethod enum（供參考）
enum class SignUpMethod(val value: String) {
    EMAIL("email"),
    GOOGLE("google"),
    APPLE("apple"),
    FACEBOOK("facebook"),
    KAKAO("kakao"),
    NAVER("naver")
}
 
// 1. 註冊完成
AdStage.trackEvent(
    AdStageEvent.SignUp(method = SignUpMethod.GOOGLE.value)
)
 
// 2. 開始註冊
AdStage.trackEvent(AdStageEvent.SignUpStart())
 
// 3. 登入（也可直接使用字串：method = "email"）
AdStage.trackEvent(
    AdStageEvent.Login(method = SignUpMethod.EMAIL.value)
)
 
// 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. 畫面瀏覽（App）
AdStage.trackEvent(
    AdStageEvent.ScreenView(
        screenName = "product_detail",
        screenClass = "ProductDetailActivity"
    )
)

🛒 電子商務（7 個）

EcommerceItem 只有 itemId、itemName、price、quantity 這 4 個欄位。

// 1. 加入購物車
AdStage.trackEvent(
    AdStageEvent.AddToCart(
        value = 99000.0,
        currency = "KRW",
        items = listOf(
            EcommerceItem(
                itemId = "PROD_123",
                itemName = "Wireless Earbuds",
                price = 99000.0,
                quantity = 1
            )
        )
    )
)
 
// 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. 購買完成 ⭐⭐⭐
AdStage.trackEvent(
    AdStageEvent.Purchase(
        value = 129000.0,
        currency = "KRW",
        transactionId = "ORDER_20250105_001",
        tax = 12900.0,
        shipping = 3000.0,
        coupon = "SUMMER2025",
        items = listOf(
            EcommerceItem(
                itemId = "PROD_123",
                itemName = "Wireless Earbuds",
                price = 126000.0,
                quantity = 1
            )
        )
    )
)
 
// 7. 退款
AdStage.trackEvent(
    AdStageEvent.Refund(
        transactionId = "ORDER_20250105_001",
        value = 129000.0,
        currency = "KRW"
    )
)

🎮 進度與成就（4 個）

// 1. 開始新手教學
AdStage.trackEvent(
    AdStageEvent.TutorialBegin(
        params = mapOf("tutorial_id" to "intro")
    )
)
 
// 2. 完成新手教學
AdStage.trackEvent(
    AdStageEvent.TutorialComplete(
        params = mapOf("duration_seconds" to 120)
    )
)
 
// 3. 升等
AdStage.trackEvent(
    AdStageEvent.LevelUp(
        level = 25,
        character = "warrior"
    )
)
 
// 4. 達成成就
AdStage.trackEvent(
    AdStageEvent.Achievement(achievementId = "first_win")
)

💬 互動（7 個）

// 1. 搜尋
AdStage.trackEvent(
    AdStageEvent.Search(searchTerm = "gaming laptop")
)
 
// 2. 選擇內容
AdStage.trackEvent(
    AdStageEvent.SelectContent(
        contentType = "product",
        contentId = "PROD_789"
    )
)
 
// 3. 分享
AdStage.trackEvent(
    AdStageEvent.Share(
        contentType = "product",
        method = "kakao"
    )
)
 
// 4. 按讚
AdStage.trackEvent(
    AdStageEvent.Like(
        contentType = "product",
        contentId = "PROD_789"
    )
)
 
// 5. 評分
AdStage.trackEvent(
    AdStageEvent.Rate(
        contentType = "product",
        contentId = "PROD_789",
        score = 4.5
    )
)
 
// 6. 登錄行程
AdStage.trackEvent(
    AdStageEvent.Schedule(
        params = mapOf("event_type" to "appointment")
    )
)
 
// 7. 使用點數
AdStage.trackEvent(
    AdStageEvent.SpendCredits(
        value = 10.0,
        itemName = "premium_feature"
    )
)

📢 應用程式內廣告（2 個）

// 1. 應用程式內廣告曝光
AdStage.trackEvent(
    AdStageEvent.AdImpression(
        adPlatform = "admob",
        adFormat = "rewarded_video",
        adUnitName = "main_reward"
    )
)
 
// 2. 應用程式內廣告點擊
AdStage.trackEvent(
    AdStageEvent.AdClick(
        adPlatform = "admob",
        adFormat = "banner",
        adUnitName = "home_bottom"
    )
)

🎮 遊戲專用（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")
)

💰 金融專用（4 個）

// 1. 買進股票
AdStage.trackEvent(
    AdStageEvent.BuyStock(
        itemId = "005930",
        itemName = "삼성전자",
        quantity = 10,
        price = 70000.0,
        value = 700000.0,
        currency = "KRW"
    )
)
 
// 2. 賣出股票
AdStage.trackEvent(
    AdStageEvent.SellStock(
        itemId = "005930",
        itemName = "삼성전자",
        quantity = 5,
        price = 72000.0,
        value = 360000.0,
        currency = "KRW"
    )
)
 
// 3. 開戶完成
AdStage.trackEvent(
    AdStageEvent.CompleteOpenAccount(
        contentType = "증권계좌",
        contentId = "ACC_123",
        method = "mobile"
    )
)
 
// 4. 申辦信用卡
AdStage.trackEvent(
    AdStageEvent.ApplyCard(
        contentType = "신용카드",
        itemName = "프리미엄 카드",
        itemId = "CARD_001"
    )
)

依事件類型的範例

1. 應用程式生命週期

class MyApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        // 初始化 SDK
        AdStage.initialize(this, apiKey, serverUrl)
        
        // 首次啟動事件由 SDK 自動傳送
        Log.d("App", "✅ 앱 시작")
    }
}

2. 使用者驗證

class AuthManager {
    
    // 註冊（method 為字串參數）
    fun onSignUpComplete(method: String) {
        AdStage.trackEvent(
            AdStageEvent.SignUp(method = method)
        )
        
        Log.d("Auth", "✅ 회원가입 완료: $method")
    }
    
    // 登入
    fun onLoginSuccess(userId: String, method: String) {
        AdStage.trackEvent(
            AdStageEvent.Login(method = method)
        )
        
        Log.d("Auth", "✅ 로그인: $userId")
    }
    
    // 登出
    fun onLogout() {
        AdStage.trackEvent(AdStageEvent.Logout())
        Log.d("Auth", "🚪 로그아웃")
    }
}

3. 畫面追蹤（BaseActivity 模式）

abstract class BaseActivity : AppCompatActivity() {
    
    override fun onResume() {
        super.onResume()
        trackScreenView()
    }
    
    abstract fun getScreenName(): String
    
    private fun trackScreenView() {
        AdStage.trackEvent(
            AdStageEvent.ScreenView(
                screenName = getScreenName(),
                screenClass = this::class.java.simpleName
            )
        )
        
        Log.d("Screen", "📺 ${getScreenName()}")
    }
}
 
// 使用範例
class HomeActivity : BaseActivity() {
    override fun getScreenName() = "home"
}
 
class ProductDetailActivity : BaseActivity() {
    override fun getScreenName() = "product_detail"
    
    private fun loadProduct(productId: String) {
        // 載入商品資料...
        
        // 商品詳情瀏覽事件
        AdStage.trackEvent(
            AdStageEvent.ProductDetailsView(
                itemId = productId,
                itemName = product.name
            )
        )
    }
}

4. 電子商務完整流程

class EcommerceManager {
    
    // 1. 瀏覽商品清單
    fun trackProductList(category: String) {
        AdStage.trackEvent(
            AdStageEvent.ProductListView(itemCategory = category)
        )
    }
    
    // 2. 搜尋
    fun trackSearch(query: String) {
        AdStage.trackEvent(
            AdStageEvent.Search(searchTerm = query)
        )
    }
    
    // 3. 瀏覽搜尋結果
    fun trackSearchResults(query: String) {
        AdStage.trackEvent(
            AdStageEvent.SearchResultView(searchTerm = query)
        )
    }
    
    // 4. 瀏覽商品詳情
    fun trackProductView(product: Product) {
        AdStage.trackEvent(
            AdStageEvent.ProductDetailsView(
                itemId = product.id,
                itemName = product.name
            )
        )
    }
    
    // 5. 加入購物車
    fun trackAddToCart(product: Product, quantity: Int) {
        val item = EcommerceItem(
            itemId = product.id,
            itemName = product.name,
            price = product.price,
            quantity = quantity
        )
        
        AdStage.trackEvent(
            AdStageEvent.AddToCart(
                value = product.price * quantity,
                currency = "KRW",
                items = listOf(item)
            )
        )
    }
    
    // 6. 加入願望清單
    fun trackAddToWishlist(product: Product) {
        AdStage.trackEvent(
            AdStageEvent.AddToWishlist(
                itemId = product.id,
                itemName = product.name
            )
        )
    }
    
    // 7. 開始結帳
    fun trackBeginCheckout(cart: Cart) {
        val items = cart.items.map { cartItem ->
            EcommerceItem(
                itemId = cartItem.product.id,
                itemName = cartItem.product.name,
                price = cartItem.product.price,
                quantity = cartItem.quantity
            )
        }
        
        AdStage.trackEvent(
            AdStageEvent.BeginCheckout(
                value = cart.totalAmount,
                currency = "KRW",
                items = items
            )
        )
    }
    
    // 8. 輸入付款資訊
    fun trackAddPaymentInfo(paymentMethod: String) {
        AdStage.trackEvent(
            AdStageEvent.AddPaymentInfo(paymentType = paymentMethod)
        )
    }
    
    // 9. 購買完成 ⭐⭐⭐
    fun trackPurchase(order: Order) {
        val items = order.items.map { orderItem ->
            EcommerceItem(
                itemId = orderItem.product.id,
                itemName = orderItem.product.name,
                price = orderItem.product.price,
                quantity = orderItem.quantity
            )
        }
        
        AdStage.trackEvent(
            AdStageEvent.Purchase(
                value = order.totalAmount,
                currency = "KRW",
                transactionId = order.id,
                tax = order.tax,
                shipping = order.shippingFee,
                coupon = order.couponCode,
                items = items
            )
        )
        
        Log.d("Ecommerce", "✅ 구매 완료: ${order.id}, ${order.totalAmount}원")
    }
    
    // 10. 退款
    fun trackRefund(order: Order) {
        AdStage.trackEvent(
            AdStageEvent.Refund(
                transactionId = order.id,
                value = order.totalAmount,
                currency = "KRW"
            )
        )
    }
    
    // 11. 分享
    fun trackShare(product: Product, method: String) {
        AdStage.trackEvent(
            AdStageEvent.Share(
                contentType = "product",
                method = method
            )
        )
    }
}

5. 遊戲事件

class GameEventManager {
    
    // 新手教學
    fun trackTutorialBegin(tutorialId: String) {
        AdStage.trackEvent(
            AdStageEvent.TutorialBegin(
                params = mapOf("tutorial_id" to tutorialId)
            )
        )
    }
    
    fun trackTutorialComplete(tutorialId: String, duration: Long) {
        AdStage.trackEvent(
            AdStageEvent.TutorialComplete(
                params = mapOf(
                    "tutorial_id" to tutorialId,
                    "duration_seconds" to duration / 1000
                )
            )
        )
    }
    
    // 等級
    fun trackLevelUp(level: Int, character: String) {
        AdStage.trackEvent(
            AdStageEvent.LevelUp(
                level = level,
                character = character
            )
        )
    }
    
    // 成就
    fun trackAchievement(achievementId: String) {
        AdStage.trackEvent(
            AdStageEvent.Achievement(achievementId = achievementId)
        )
    }
    
    // 遊戲進行
    fun trackGameStart(level: Int, levelName: String, character: String) {
        AdStage.trackEvent(
            AdStageEvent.GamePlay(
                level = level,
                levelName = levelName,
                character = character,
                contentType = "pvp"
            )
        )
    }
    
    // 獲得獎勵
    fun trackBonusAcquired(itemId: String, itemName: String, quantity: Int) {
        AdStage.trackEvent(
            AdStageEvent.AcquireBonus(
                contentType = "reward",
                itemId = itemId,
                itemName = itemName,
                quantity = quantity
            )
        )
    }
    
    // 使用點數（遊戲貨幣）
    fun trackSpendCredits(amount: Double, itemName: String) {
        AdStage.trackEvent(
            AdStageEvent.SpendCredits(
                value = amount,
                itemName = itemName
            )
        )
    }
}

最佳實務

1. 活用 Extension 函式

// ActivityExtensions.kt
fun Activity.trackScreen() {
    val screenName = this::class.java.simpleName
        .removeSuffix("Activity")
        .lowercase()
    
    AdStage.trackEvent(
        AdStageEvent.ScreenView(
            screenName = screenName,
            screenClass = this::class.java.simpleName
        )
    )
}
 
// 使用
class ProfileActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        trackScreen()  // ✅ 簡單！
    }
}

2. 在 ViewModel 中追蹤事件

class ProductViewModel : ViewModel() {
    
    private val _productState = MutableLiveData<Product>()
    val productState: LiveData<Product> = _productState
    
    fun loadProduct(productId: String) {
        viewModelScope.launch {
            try {
                val product = repository.getProduct(productId)
                _productState.value = product
                
                // 商品瀏覽事件
                AdStage.trackEvent(
                    AdStageEvent.ProductDetailsView(
                        itemId = product.id,
                        itemName = product.name
                    )
                )
                
            } catch (e: Exception) {
                Log.e("ProductVM", "Failed to load product", e)
            }
        }
    }
    
    fun addToCart(product: Product, quantity: Int) {
        viewModelScope.launch {
            try {
                repository.addToCart(product, quantity)
                
                val item = EcommerceItem(
                    itemId = product.id,
                    itemName = product.name,
                    price = product.price,
                    quantity = quantity
                )
                
                AdStage.trackEvent(
                    AdStageEvent.AddToCart(
                        value = product.price * quantity,
                        currency = "KRW",
                        items = listOf(item)
                    )
                )
                
            } catch (e: Exception) {
                Log.e("ProductVM", "Failed to add to cart", e)
            }
        }
    }
}

3. 在 Compose UI 中使用

@Composable
fun ProductDetailScreen(
    productId: String,
    viewModel: ProductViewModel = hiltViewModel()
) {
    val product by viewModel.productState.collectAsState()
    
    // 進入畫面時的事件
    LaunchedEffect(productId) {
        viewModel.loadProduct(productId)
        
        AdStage.trackEvent(
            AdStageEvent.ScreenView(
                screenName = "product_detail",
                screenClass = "ProductDetailScreen"
            )
        )
    }
    
    Column {
        // UI...
        
        Button(
            onClick = {
                viewModel.addToCart(product, 1)
                
                AdStage.trackEvent(
                    AdStageEvent.Custom(
                        params = mapOf(
                            "action" to "add_to_cart_button",
                            "product_id" to product.id
                        )
                    )
                )
            }
        ) {
            Text("장바구니에 추가")
        }
    }
}

4. 事件包裝類別

object AnalyticsManager {
    
    private const val TAG = "Analytics"
    
    fun trackScreen(screenName: String, screenClass: String? = null) {
        AdStage.trackEvent(
            AdStageEvent.ScreenView(
                screenName = screenName,
                screenClass = screenClass
            )
        )
        Log.d(TAG, "📺 Screen: $screenName")
    }
    
    fun trackPurchase(order: Order) {
        val items = order.items.map {
            EcommerceItem(
                itemId = it.product.id,
                itemName = it.product.name,
                price = it.product.price,
                quantity = it.quantity
            )
        }
        
        AdStage.trackEvent(
            AdStageEvent.Purchase(
                value = order.totalAmount,
                currency = "KRW",
                transactionId = order.id,
                items = items
            )
        )
        
        Log.d(TAG, "💰 Purchase: ${order.id}")
    }
    
    fun trackError(error: Throwable, context: String) {
        AdStage.trackEvent(
            AdStageEvent.Custom(
                params = mapOf(
                    "event_type" to "error",
                    "error_message" to (error.message ?: "unknown"),
                    "context" to context
                )
            )
        )
        Log.e(TAG, "❌ Error: $context", error)
    }
}

5. 效能最佳化：Throttling

class ThrottledEventTracker {
    private val lastTrackTimes = mutableMapOf<String, Long>()
    private val throttleInterval = 2000L  // 2 秒
    
    fun trackEvent(event: AdStageEvent) {
        val eventKey = event.eventName
        val now = System.currentTimeMillis()
        val lastTime = lastTrackTimes[eventKey] ?: 0L
        
        if (now - lastTime >= throttleInterval) {
            AdStage.trackEvent(event)
            lastTrackTimes[eventKey] = now
        } else {
            Log.d("AdStage", "⏱️ Throttled: $eventKey")
        }
    }
}
 
// 使用（捲動事件等）
val throttledTracker = ThrottledEventTracker()
 
recyclerView.addOnScrollListener(object : RecyclerView.OnScrollListener() {
    override fun onScrolled(recyclerView: RecyclerView, dx: Int, dy: Int) {
        throttledTracker.trackEvent(
            AdStageEvent.Custom(
                params = mapOf(
                    "action" to "scroll",
                    "delta_y" to dy
                )
            )
        )
    }
})

轉換範例（基於字串 → 類型安全 API）

目前 SDK 僅支援 AdStageEvent 類型安全事件。以下是將基於字串的事件名稱轉換為類型安全事件的範例（箭頭右側為實際使用形式）。

// 1. 基本事件
"first_open"
→ AdStage.trackEvent(AdStageEvent.FirstOpen())
 
// 2. 登入（method 為字串參數）
"login", method = "email"
→ AdStage.trackEvent(AdStageEvent.Login(method = "email"))
 
// 3. 畫面瀏覽
"screen_view", screen_name = "home"
→ AdStage.trackEvent(AdStageEvent.ScreenView(screenName = "home"))
 
// 4. 自訂
"custom", action = "click"
→ AdStage.trackEvent(AdStageEvent.Custom(params = mapOf("action" to "click")))

疑難排解

1. 執行階段例外：「存在 value 時 currency 為必填」

問題：

// ❌ IllegalArgumentException（事件物件建立時點）
AdStage.trackEvent(
    AdStageEvent.Purchase(value = 9900.0)
)

解決：

// ✅ 新增 currency（ISO 4217，3 碼）
AdStage.trackEvent(
    AdStageEvent.Purchase(
        value = 9900.0,
        currency = "KRW"
    )
)

2. IDE 自動完成無法運作

解決：

Gradle Sync: File → Sync Project with Gradle Files
Invalidate Caches: File → Invalidate Caches / Restart...
確認 Import：

import io.nbase.adapter.adstage.models.AdStageEvent.*
 
// 現在自動完成即可運作
AdStage.trackEvent(Purchase(...))

3. ProGuard/R8 混淆問題

# proguard-rules.pro

# 保留 AdStage 事件模型
-keep class io.nbase.adapter.adstage.models.** { *; }
-keepclassmembers class io.nbase.adapter.adstage.models.** { *; }

# AdStageEvent sealed class
-keep class io.nbase.adapter.adstage.models.AdStageEvent { *; }
-keep class io.nbase.adapter.adstage.models.AdStageEvent$* { *; }

# Kotlin Metadata
-keep class kotlin.Metadata { *; }

4. 貨幣代碼驗證錯誤

// ❌ 2 碼代碼
AdStageEvent.Purchase(value = 100.0, currency = "KR")
// IllegalArgumentException: "currency 必須是 ISO 4217 的 3 碼代碼（例如：USD、KRW）"
 
// ✅ 3 碼 ISO 4217 代碼
AdStageEvent.Purchase(value = 100.0, currency = "KRW")  // 韓圓
AdStageEvent.Purchase(value = 100.0, currency = "USD")  // 美元
AdStageEvent.Purchase(value = 100.0, currency = "JPY")  // 日圓

主要貨幣代碼：

國家	貨幣	代碼
韓國	韓圓	`KRW`
美國	美元	`USD`
日本	日圓	`JPY`
歐盟	歐元	`EUR`
英國	英鎊	`GBP`

5. 查看偵錯記錄

SDK 會以 AdStage / AdapterAdStage 標籤輸出記錄。使用下列篩選條件，可在 Logcat 中確認事件傳送流程。

Logcat 篩選條件：

# Android Studio
tag:AdStage OR tag:AdapterAdStage
 
# adb
adb logcat | grep -i adstage

參考資料

標準參考

FAQ

Q: 自訂事件該如何傳送？
A: 使用 AdStageEvent.Custom(params = mapOf(...))

Q: 可以不帶 value 只使用 currency 嗎？
A: 不可以，使用 value 時 currency 為必填。

Q: 離線狀態下也能運作嗎？
A: 可以，SDK 會自動將事件存入佇列，網路恢復時再傳送。

支援

聯絡方式：

電子郵件：support@nbase.io