iOS SDK Configuration

Initializing the SDK

SDK Initialization

Initialize the SDK as early as possible in your app lifecycle, preferably in AppDelegate.

Basic Initialization

import EmpowerMobileAds
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize the SDK with your app identifier
        let config = EMAConfiguration(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
        EMAManager.shared.initialize(configuration: config)
        return true
    }
}

Initialization with Options

// Initialize with debug logging enabled
let config = EMAConfiguration(
    appAdIdentifier: "YOUR_APP_AD_IDENTIFIER",
    logLevel: .all
)
EMAManager.shared.initialize(configuration: config)

Or using the convenience initializer for minimal setup:

EMAManager.shared.initialize(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")

appAdIdentifier: Your app identifier which will be provided by us.

EMAConfiguration Parameters

Parameter	Type	Default	Description
appAdIdentifier	String	Required	The app identifier provided by Empower
adAppVersion	String	"1"	The ad app version
variant	String	""	A/B test variant string
logLevel	LogLevel	.none	Logging level for SDK debug output
nonPersonalizedAds	Bool	false	When true, requests non-personalized ads only (GDPR)
customUserId	String?	nil	Custom user identifier
customParameters	[String: String]?	nil	Additional custom parameters for ad requests
appLovinSdkKey	String?	nil	AppLovin SDK key (required if using AppLovin mediation)

Factory Methods

// Basic configuration with defaults
let config = EMAConfiguration.basic(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
// Debug configuration with .all log level
let config = EMAConfiguration.debug(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
// GDPR-compliant configuration with non-personalized ads enabled
let config = EMAConfiguration.gdprCompliant(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")

Builder Pattern

You can chain configuration options using the builder pattern:

let config = EMAConfiguration.basic(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
    .with(logLevel: .all)
    .with(variant: "variant_b")
    .with(nonPersonalizedAds: true)
    .with(customUserId: "user_123")
    .with(customParameters: ["category": "news"])
    .with(appLovinSdkKey: "YOUR_APPLOVIN_SDK_KEY")
EMAManager.shared.initialize(configuration: config)

Runtime Settings

You can modify certain settings at runtime via EMASettings.shared:

Setting	Type	Default	Description
logLevel	LogLevel	.none	Log verbosity
isAdsDisabled	Bool	false	Disable all ads (e.g., for premium users)
isAdsNonPersonalized	Bool	false	Request non-personalized ads

Log Levels

Level	Description
.none	Disables all logging
.all	Logs all messages including debug information
.normal	Standard logging level for general information
.error	Logs errors only

Listening for SDK Ready State (Optional)

If you need to know exactly when the SDK is ready (for analytics, UI updates, etc.), you can implement EMASdkReadyDelegate:

import EmpowerMobileAds
@main
class AppDelegate: UIResponder, UIApplicationDelegate, EMASdkReadyDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Register as delegate before initialization
        EMAManager.shared.sdkReadyDelegate = self
        // Initialize the SDK
        let config = EMAConfiguration(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
        EMAManager.shared.initialize(configuration: config)
        return true
    }
    // MARK: - EMASdkReadyDelegate
    func onReady() {
        // SDK is initialized and ready to load ads
        // Use this for analytics or UI updates
        print("Empower SDK is ready")
    }
    func onFailed(error: Error?) {
        // SDK initialization failed
        // Handle the error appropriately
        print("Empower SDK initialization failed: \(error?.localizedDescription ?? "unknown")")
    }
}

Alternatively, you can observe the adsReadyToLoadNotification:

NotificationCenter.default.addObserver(
    forName: EMAManager.adsReadyToLoadNotification,
    object: nil,
    queue: .main
) { _ in
    print("SDK is ready to load ads")
}

Note: This delegate is optional. Since all ad types automatically queue, you don't need to wait for onReady() before loading ads.

---

GDPR Compliance

For users in regions requiring GDPR compliance, enable non-personalized ads:

// Option 1: Use GDPR-compliant configuration
let config = EMAConfiguration.gdprCompliant(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
EMAManager.shared.initialize(configuration: config)
// Option 2: Set via configuration parameter
let config = EMAConfiguration(
    appAdIdentifier: "YOUR_APP_AD_IDENTIFIER",
    nonPersonalizedAds: true
)
EMAManager.shared.initialize(configuration: config)
// Option 3: At runtime based on user consent
EMASettings.shared.isAdsNonPersonalized = !userHasGivenConsent

App Tracking Transparency (iOS 14+)

For iOS 14 and later, you should request App Tracking Transparency permission before initializing the SDK:

import AppTrackingTransparency
import EmpowerMobileAds
func requestTrackingPermissionAndInitSDK() {
    if #available(iOS 14, *) {
        ATTrackingManager.requestTrackingAuthorization { status in
            DispatchQueue.main.async {
                let nonPersonalized: Bool
                switch status {
                case .authorized:
                    // User granted permission - personalized ads enabled
                    nonPersonalized = false
                case .denied, .restricted, .notDetermined:
                    // Use non-personalized ads
                    nonPersonalized = true
                @unknown default:
                    nonPersonalized = true
                }
                // Initialize SDK after permission response
                let config = EMAConfiguration(
                    appAdIdentifier: "YOUR_APP_AD_IDENTIFIER",
                    nonPersonalizedAds: nonPersonalized
                )
                EMAManager.shared.initialize(configuration: config)
            }
        }
    } else {
        // iOS 13 and earlier - no ATT required
        let config = EMAConfiguration(appAdIdentifier: "YOUR_APP_AD_IDENTIFIER")
        EMAManager.shared.initialize(configuration: config)
    }
}

Don't forget to add the NSUserTrackingUsageDescription key to your Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>This app uses your data to provide personalized ads.</string>

---

Lifecycle Management

The SDK automatically manages ad lifecycle based on your app's state.

Background/Foreground Handling

The SDK automatically handles app state transitions. For custom behavior, you can hook into these events:

// In AppDelegate or SceneDelegate
func applicationDidEnterBackground(_ application: UIApplication) {
    // SDK automatically pauses all ad refresh timers
    // No action required
}
func applicationWillEnterForeground(_ application: UIApplication) {
    // SDK automatically resumes ad refresh timers
    // If app was in background for extended period,
    // SDK will refresh ad configuration automatically
}

Disabling Ads for Premium Users

// Disable all ads for premium users
func userPurchasedPremium() {
    EMASettings.shared.isAdsDisabled = true
    // Destroy any currently loaded ads
    // (they will automatically stop showing)
}
// Re-enable ads if subscription expires
func premiumSubscriptionExpired() {
    EMASettings.shared.isAdsDisabled = false
}