StageUp
Mobile SDKPromotion

iOS Promotion

This guide explains how to open a promotion or fetch a promotion list using AdStagePromotionsHandler in an iOS app.

1. Base parameter class: PromotionListParams

@objc public class PromotionListParams: NSObject {
    @objc public var bannerType: String?          // NATIVE, INTERSTITIAL, REWARDED_VIDEO, POPUP
    @objc public var targetAudience: String?      // Target user filter
    @objc public var deviceType: String?          // LOW_END, MID_END, HIGH_END
    @objc public var region: String?              // KR, JP, US, SEA, EU, GLOBAL
    @objc public var limit: NSNumber?             // Max number of promotions to fetch
    @objc public var status: String?              // ACTIVE, PENDING, PAUSED, ENDED
    @objc public var partner: String?             // Partner (advertiser) filter
 
    @objc public var primaryInterest: String?     // GAMES, SHOPPING, ENTERTAINMENT, etc.
    @objc public var primaryAgeGroup: String?     // 13-17, 18-24, 25-34, 35-44, 45+
    @objc public var gameGenrePreference: String? // RPG, STRATEGY, CASUAL, ACTION, PUZZLE
    @objc public var playerSpendingTier: String?  // F2P, DOLPHIN, WHALE
    @objc public var playTimePattern: String?     // MORNING, AFTERNOON, EVENING, NIGHT
}

2. Open a promotion (openPromotion)

Fetch promotions that match the conditions and immediately render/handle them with UI.

let params = AdStagePromotionsHandler.PromotionListParams()
params.bannerType = "REWARDED_VIDEO"
params.targetAudience = "new_user"
params.deviceType = "HIGH_END"
params.region = "KR"
params.limit = 3
params.status = "ACTIVE"
params.partner = "SuperAds"
params.primaryInterest = "GAMES"
params.primaryAgeGroup = "25-34"
params.gameGenrePreference = "RPG"
params.playerSpendingTier = "DOLPHIN"
params.playTimePattern = "EVENING"
 
AdStagePromotionsHandler.shared.openPromotion(
    params: params,
    showTodayButton: true
) { url, error in
    if let error = error {
        print("Failed to handle promotion: \(error)")
    } else {
        print("Promotion handled: \(url ?? "")")
    }
}

3. Get promotion list (getPromotionList)

Fetch only the promotions list that matches the conditions (render the UI yourself).

let params = AdStagePromotionsHandler.PromotionListParams()
params.bannerType = "REWARDED_VIDEO"
params.targetAudience = "new_user"
params.deviceType = "HIGH_END"
params.region = "KR"
params.limit = 3
params.status = "ACTIVE"
params.partner = "SuperAds"
params.primaryInterest = "GAMES"
params.primaryAgeGroup = "25-34"
params.gameGenrePreference = "RPG"
params.playerSpendingTier = "DOLPHIN"
params.playTimePattern = "EVENING"
 
AdStagePromotionsHandler.shared.getPromotionList(params: params) { result in
    if let result = result {
        print("Total promotions: \(result.totalItems)")
        print("Promotions: \(result.promotions)")
    } else {
        print("Failed to fetch promotions")
    }
}

4. Notes

  • All parameters are optional; when nil, the query is unfiltered for that field.
  • openPromotion automatically renders with UI, while getPromotionList returns data only.
  • limit must be an NSNumber. Example: params.limit = 5

Table of Contents