Skip to main content

Placement Events Listener

info

Event-Driven System: The Teads SDK uses a comprehensive event system through TeadsAdPlacementEventsDelegate to manage video playback and user interactions.

Overview​

The Teads SDK provides an event-driven system for managing placement events through the TeadsAdPlacementEventsDelegate. This delegate allows you to:

  • Track video playback states (play, pause, complete)
  • Handle user interactions and engagement
  • Monitor ad performance and viewability

Implementing TeadsAdPlacementEventsDelegate​

Basic Implementation​

import tv.teads.sdk.combinedsdk.adplacement.TeadsAdPlacementMedia
import tv.teads.sdk.combinedsdk.adplacement.config.TeadsAdPlacementMediaConfig
import tv.teads.sdk.combinedsdk.adplacement.interfaces.TeadsAdPlacementEventsDelegate
import tv.teads.sdk.combinedsdk.adplacement.interfaces.core.TeadsAdPlacement
import tv.teads.sdk.combinedsdk.TeadsAdPlacementEventName
import android.net.Uri

class YourActivity : AppCompatActivity(), TeadsAdPlacementEventsDelegate {

    private var mediaPlacement: TeadsAdPlacementMedia? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        setupMediaPlacement()
    }

    private fun setupMediaPlacement() {
        val config = TeadsAdPlacementMediaConfig(
            pid = 84242,  // Your unique Placement ID
            articleUrl = Uri.parse("https://example.com/article")
        )

        mediaPlacement = TeadsAdPlacementMedia(
            this, // Context
            config, // Placement config
            this // Event delegate
        )

        val mediaAdView = mediaPlacement?.loadAd()

        // Add mediaAdView to your view hierarchy
    }

    // MARK: - TeadsAdPlacementEventsDelegate

    override fun onPlacementEvent(
        placement: TeadsAdPlacement<*, *>,
        event: TeadsAdPlacementEventName,
        data: Map<String, Any>?
    ) {
        when (event) {
            TeadsAdPlacementEventName.READY -> {
                handleAdReady()
            }

            TeadsAdPlacementEventName.RENDERED -> {
                handleAdRendered()
            }

            TeadsAdPlacementEventName.PLAY -> {
                handleVideoPlay()
            }

            TeadsAdPlacementEventName.PAUSE -> {
                handleVideoPause()
            }

            TeadsAdPlacementEventName.COMPLETE -> {
                handleVideoComplete()
            }

            TeadsAdPlacementEventName.START_PLAY_AUDIO -> {
                handleAudioStart()
            }

            TeadsAdPlacementEventName.STOP_PLAY_AUDIO -> {
                handleAudioStop()
            }

            TeadsAdPlacementEventName.CLICKED -> {
                handleAdClick()
            }

            TeadsAdPlacementEventName.VIEWED -> {
                handleAdViewed()
            }

            TeadsAdPlacementEventName.FAILED -> {
                handleAdFailed(data)
            }

            TeadsAdPlacementEventName.HEIGHT_UPDATED -> {
                handleAdHeightUpdate(data)
            }

            else -> {
                Log.d("TeadsSDK", "Other event: $event")
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        mediaPlacement?.clean()
    }
}

User Interaction Events​

Click Event​

TeadsAdPlacementEventName.CLICKED -> {
    Log.d("TeadsSDK", "Ad clicked")
}
Do not open the URL manually

The SDK automatically handles opening the click URL. Do not implement URL navigation in this event handler — doing so will result in the browser opening twice. Use this event only for tracking/analytics purposes.

There is also a CLICKED_ORGANIC event, emitted when a user clicks on organic (non-paid) content in placements that support it, such as Feed or Recommendations.

Viewed Event​

TeadsAdPlacementEventName.VIEWED -> {
    Log.d("TeadsSDK", "Ad viewability threshold reached")
}

Error Handling​

Failed Event​

TeadsAdPlacementEventName.FAILED -> {
    Log.e("TeadsSDK", "Ad failed to load, data: $data")
}