NativeAdSlot

Displays a contextually targeted native ad inline within your Compose UI. The slot auto-sizes to the creative height and collapses to zero when no ad is available.

Basic Usage

import ad.simula.ad.sdk.nativead.NativeAdSlot

@Composable
fun CharacterFeed(characters: List<Character>) {
    LazyColumn {
        itemsIndexed(characters) { index, character ->
            CharacterCard(character)
            if (index % 10 == 9) {
                NativeAdSlot(
                    adUnitId = "SIM-NAT-XXXXXXXX",
                    onImpression = { data ->
                        Log.d("SimulaAd", "Impression: ${data.impressionId}")
                    }
                )
            }
        }
    }
}

Parameters

Parameter	Type	Default	Description
adUnitId	String?	null	Ad unit ID from the publisher dashboard. Used for measurement and improved targeting
width	Any?	fills parent	Width: Int/Float for dp, String with % or px suffix (e.g. "80%", "320px"). Min 300 dp
theme	String?	null	"dark", "light", or "system". null uses the SDK default
modifier	Modifier	Modifier	Standard Compose modifier for margins, padding, etc.
preloadedAdId	String?	null	ID from SimulaAds.preloadNativeAd() to render a cached ad instantly
metadata	Map<String, String>	emptyMap()	Up to 10 key/value labels for reporting. See Metadata
onImpression	(NativeAdData) -> Unit	{}	Fires when the ad is >=50% visible for >=1 second
onClick	() -> Unit	{}	Fires when the user taps the ad CTA
onPaid	(AdValue) -> Unit	{}	Estimated per-impression revenue, co-timed with onImpression. See AdValue
onError	(NativeAdError) -> Unit	{}	Fires on load or render failure

Metadata

Attach up to 10 key/value labels to segment your reporting:

NativeAdSlot(
    adUnitId = "SIM-NAT-XXXXXXXX",
    metadata = mapOf("screen" to "search", "tab" to "for_you"),
)

Keys: ≤64 chars, no $ prefix, no .. Values: ≤256 chars. Extra or invalid entries are dropped.

Preloading

Preload ads before they scroll into view for instant rendering:

// Preload
val preloadedId = SimulaAds.preloadNativeAd(
    adUnitId = "SIM-NAT-XXXXXXXX",
    theme = "system"
)

// Use in composable
NativeAdSlot(
    adUnitId = "SIM-NAT-XXXXXXXX",
    preloadedAdId = preloadedId
)

// Clean up if the ad was never displayed
SimulaAds.destroyPreloadedAd(preloadedId)

Set metadata on the NativeAdSlot, not the preload call. See Metadata.

Invalidation

Force-refresh a specific slot or clear all cached native ads:

// Refresh one slot
SimulaAds.invalidateNativeAd(adUnitId = "SIM-NAT-XXXXXXXX")

// Clear all cached native ads
SimulaAds.invalidateNativeAds()