Placement Events Listener

info

Event-Driven System: The Teads SDK uses a comprehensive event system through TeadsAdPlacementEventsDelegate to manage video playback, audio sessions, 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)
• Manage audio sessions during ad playback
• Handle user interactions and engagement
• Monitor ad performance and viewability

Implementing TeadsAdPlacementEventsDelegate

Basic Implementation

Swift

import UIKit
import TeadsSDK

class YourViewController: UIViewController, TeadsAdPlacementEventsDelegate {

    var mediaPlacement: TeadsAdPlacementMedia?
    var adView: UIView?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupMediaPlacement()
    }

    private func setupMediaPlacement() {
        mediaPlacement = TeadsAdPlacementMedia(
            pid: 84242,
            articleUrl: URL(string: "https://example.com/article"),
            delegate: self
        )

        do {
            adView = try mediaPlacement?.loadAd()

            // Add adView to your view hierarchy
        } catch {
            print("Failed to load ad: \(error)")
        }
    }

    // MARK: - TeadsAdPlacementEventsDelegate

    func adPlacement(_ placement: TeadsAdPlacementIdentifiable?,
                    didEmitEvent event: TeadsAdPlacementEventName,
                    data: [String : Any]?) {

        switch event {
        case .ready:
            handleAdReady()

        case .rendered:
            handleAdRendered()

        case .play:
            handleVideoPlay()

        case .pause:
            handleVideoPause()

        case .complete:
            handleVideoComplete()

        case .startPlayAudio:
            handleAudioStart()

        case .stopPlayAudio:
            handleAudioStop()

        case .clicked:
            handleAdClick()

        case .viewed:
            handleAdViewed()

        case .failed:
            handleAdFailed(data)

        case .heightUpdated:
            handleAdHeightUpdate(data)

        default:
            print("Other event: \(event)")
        }
    }
}

Objective-C

#import <UIKit/UIKit.h>
#import <TeadsSDK/TeadsSDK-Swift.h>

@interface YourViewController : UIViewController <TeadsAdPlacementEventsDelegate>

@property (nonatomic, strong) TeadsAdPlacementMedia *mediaPlacement;
@property (nonatomic, strong) UIView *adView;

@end

@implementation YourViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [self setupMediaPlacement];
}

- (void)setupMediaPlacement {
    self.mediaPlacement = [[TeadsAdPlacementMedia alloc] initWithPid:84242
                                                            articleUrl:[NSURL URLWithString:@"https://example.com/article"]
                                                              delegate:self];

    NSError *error = nil;
    self.adView = [self.mediaPlacement loadAdAndReturnError:&error];
    if (error) {
        NSLog(@"Failed to load ad: %@", error);
        return;
    }

    // Add self.adView to your view hierarchy
}

#pragma mark - TeadsAdPlacementEventsDelegate

- (void)adPlacement:(id<TeadsAdPlacementIdentifiable>)placement
       didEmitEvent:(TeadsAdPlacementEventName)event
               data:(NSDictionary<NSString *, id> *)data {

    switch (event) {
        case TeadsAdPlacementEventNameReady:
            [self handleAdReady];
            break;

        case TeadsAdPlacementEventNameRendered:
            [self handleAdRendered];
            break;

        case TeadsAdPlacementEventNamePlay:
            [self handleVideoPlay];
            break;

        case TeadsAdPlacementEventNamePause:
            [self handleVideoPause];
            break;

        case TeadsAdPlacementEventNameComplete:
            [self handleVideoComplete];
            break;

        case TeadsAdPlacementEventNameStartPlayAudio:
            [self handleAudioStart];
            break;

        case TeadsAdPlacementEventNameStopPlayAudio:
            [self handleAudioStop];
            break;

        case TeadsAdPlacementEventNameClicked:
            [self handleAdClick];
            break;

        case TeadsAdPlacementEventNameViewed:
            [self handleAdViewed];
            break;

        case TeadsAdPlacementEventNameFailed:
            [self handleAdFailed:data];
            break;

        case TeadsAdPlacementEventNameHeightUpdated:
            [self handleAdHeightUpdate:data];
            break;

        default:
            NSLog(@"Other event: %ld", (long)event);
            break;
    }
}

@end

User Interaction Events

Click Event

case .clicked:
    print("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 .clickedOrganic case, emitted when a user clicks on organic (non-paid) content in placements that support it, such as Feed or Recommendations.

Viewed Event

case .viewed:
    print("Ad viewability threshold reached")

Error Handling

Failed Event

case .failed:
    print("Ad failed to load, data: \(data)")

Related Documentation

• Integration Guide - Complete integration steps including event handling
• Settings Configuration - Advanced configuration options
• Privacy Guide - Privacy and data handling information
• Troubleshooting Guide - Common issues and solutions