shouldDiscardAdItem

Callback that decides whether an ad item is discarded or kept for a later opportunity to play it once an attempt to play it ended.

AdItemDiscardContext.outcome tells how the attempt ended, and AdItemDiscardContext.discardPolicyDecision tells what the player does by default, based on the AdItem.discardPolicy of the ad item.

Use this callback to decide based on AdItemDiscardContext.outcome, for example to discard an ad item only once it failed. To always discard or always keep a single ad item, set its AdItem.discardPolicy instead.

Default behavior

The default callback returns AdItemDiscardContext.discardPolicyDecision, which is:

• AdItemDiscardDecision.Discard for every outcome of an ad item with AdItemDiscardPolicy.DiscardAfterAttempt, the default AdItem.discardPolicy

• AdItemDiscardDecision.Keep for every outcome of an ad item with AdItemDiscardPolicy.KeepAfterAttempt

Kept ad items

An ad item kept with AdItemDiscardDecision.Keep stays eligible for later opportunities in the current playback session. Its ad tag is requested again before it is played next.

Limitations

• Only pause ads are supported

Example Usage

To keep a pause ad for later opportunities, set its AdItem.discardPolicy without a callback:

AdItem(arrayOf(adSource), position = "pause", discardPolicy = AdItemDiscardPolicy.KeepAfterAttempt)

To still discard such an ad item once it failed, and apply its default decision otherwise:

AdvertisingConfig(
    shouldDiscardAdItem = ShouldDiscardAdItemCallback { _, context ->
        when (context.outcome) {
            is AdItemAttemptOutcome.Error -> AdItemDiscardDecision.Discard
            else -> context.discardPolicyDecision
        }
    },
)

See also