Video Ad Tracking - Permutive

The AdTracker API allows you to track video advertisement events. Use this to measure ad views, engagement, clicks, and completions within video content.

Android is the only Permutive SDK with a native ad tracker. iOS / tvOS and Web CTV publishers emit ad events manually via track(...). The typed AdTracker lifecycle below is unique to Android — use it instead of generic track() calls so the emitted events match the canonical schema automatically.

Creating AdTracker

Ad Methods

Use Cases

Interactions

Overview

AdTracker provides comprehensive video ad tracking:

Automatic lifecycle tracking - Tracks VideoAdView and VideoAdCompletion events
Engagement metrics - Measures time spent watching ads
Click tracking - Tracks ad interactions
Custom events - Track custom ad-related events
Shared context - Can share View ID with parent MediaTracker

Creating an AdTracker

AdTracker can be created in two ways:

1. From MediaTracker (Recommended)

Use this when the ad is related to video content currently being viewed. The AdTracker will share the same View ID with the MediaTracker:

val videoTracker = permutive.trackVideoView(...)

val adTracker = videoTracker.trackAdView(
    durationMs = 15000,  // 15 second ad
    adProperties = AdTracker.AdProperties(
        title = "Product Advertisement",
        durationInSeconds = 15,
        isMuted = false,
        campaignId = "camp_123",
        creativeId = "creative_456"
    )
)

2. Standalone AdTracker

Use this for standalone video ads not associated with specific video content:

val adTracker = permutive.trackVideoAdView(
    durationMs = 30000,  // 30 second ad
    adProperties = AdTracker.AdProperties(
        title = "Standalone Ad",
        durationInSeconds = 30,
        isMuted = false,
        campaignId = "camp_789",
        creativeId = "creative_012"
    )
)

Ad Events

AdTracker automatically generates these events:

1. VideoAdView Event

Tracked when AdTracker is created:

Event: VideoAdView
Properties:
  - [ad properties]
  - [custom properties]

2. VideoAdCompletion Event

Tracked when completion() is called:

Event: VideoAdCompletion
Properties:
  - engaged_time: Time spent watching ad (seconds)
  - completion: Percentage of ad viewed (0.0 - 1.0)
  - [ad properties]
  - [custom properties]

3. VideoAdClicked Event

Tracked when clicked() is called:

Event: VideoAdClicked
Properties:
  - [ad properties]
  - [custom properties]

AdTracker Methods

play()

Call when the ad starts playing. AdTracker initializes in a paused state, so call this immediately if the ad auto-plays:

adTracker.play()

play(positionMs)

Call when playback position changes (e.g., seeking):

adTracker.play(positionMs = 5000)  // Resume at 5 seconds

pause()

Call when the ad is paused or buffering:

adTracker.pause()

clicked()

Call when the user clicks on the ad. This tracks a VideoAdClicked event:

adTracker.clicked()

completion()

Call when the ad is no longer being shown. This tracks a VideoAdCompletion event with engagement properties:

adTracker.completion()

⚠️ Important Once completion() is called, the AdTracker is closed and subsequent method calls will have no effect.

Custom Events

Track custom ad-related events:

// Track without additional properties
adTracker.trackWithAdProperties("AdMuted")

// Track with additional properties
adTracker.trackWithAdProperties(
    "AdQualityChanged",
    EventProperties.from(
        "from_quality" to "480p",
        "to_quality" to "720p"
    )
)

Ad Properties

Standard Ad Properties

AdTracker.AdProperties(
    title = "Ad Title",
    durationInSeconds = 30,
    isMuted = false,
    campaignId = "campaign_abc123",
    creativeId = "creative_xyz789"
)

Property Reference

Property	Type	Description
title	String	Ad title or name
durationInSeconds	Int	Ad duration in seconds
isMuted	Boolean	Whether ad started muted
campaignId	String	Ad campaign identifier
creativeId	String	Ad creative identifier

All properties are passed to every event tracked through the AdTracker.

Complete Example

Kotlin - Pre-Roll Ad

import com.permutive.android.MediaTracker
import com.permutive.android.AdTracker
import com.permutive.android.EventProperties

class VideoFragment : Fragment() {
    
    private val permutive by lazy {
        (requireActivity().application as MyApplication).permutive
    }
    
    private lateinit var videoTracker: MediaTracker
    private lateinit var adTracker: AdTracker
    private lateinit var exoPlayer: ExoPlayer
    
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        // Create video tracker
        videoTracker = permutive.trackVideoView(
            durationMilliseconds = 180000,  // 3 minute video
            videoProperties = MediaTracker.VideoProperties(
                title = "Main Video Content"
            )
        )
        
        // Create ad tracker for pre-roll ad
        adTracker = videoTracker.trackAdView(
            durationMs = 15000,  // 15 second ad
            adProperties = AdTracker.AdProperties(
                title = "Pre-Roll Advertisement",
                durationInSeconds = 15,
                isMuted = false,
                campaignId = "preroll_camp_123",
                creativeId = "creative_456"
            )
        )
        
        setupAdPlayer()
        
        return inflater.inflate(R.layout.fragment_video, container, false)
    }
    
    private fun setupAdPlayer() {
        exoPlayer = ExoPlayer.Builder(requireContext()).build()
        
        // Load ad content
        val adUri = Uri.parse("https://example.com/ad.mp4")
        val adMediaItem = MediaItem.fromUri(adUri)
        exoPlayer.setMediaItem(adMediaItem)
        exoPlayer.prepare()
        
        // Track ad playback
        exoPlayer.addListener(object : Player.Listener {
            override fun onIsPlayingChanged(isPlaying: Boolean) {
                if (isPlaying) {
                    adTracker.play()
                } else {
                    adTracker.pause()
                }
            }
            
            override fun onPlaybackStateChanged(state: Int) {
                when (state) {
                    Player.STATE_ENDED -> {
                        // Ad finished
                        adTracker.completion()
                        // Now load main video content
                        loadMainVideoContent()
                    }
                    Player.STATE_BUFFERING -> {
                        adTracker.pause()
                    }
                }
            }
        })
        
        // Track ad clicks
        playerView.setOnClickListener {
            adTracker.clicked()
            openAdLandingPage()
        }
        
        // Start ad playback
        exoPlayer.play()
    }
    
    private fun loadMainVideoContent() {
        // Load main video
        val videoUri = Uri.parse("https://example.com/video.mp4")
        val videoMediaItem = MediaItem.fromUri(videoUri)
        exoPlayer.setMediaItem(videoMediaItem)
        exoPlayer.prepare()
        exoPlayer.play()
        
        // Now track main video with videoTracker
        videoTracker.play()
    }
    
    private fun openAdLandingPage() {
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse("https://advertiser.com/landing"))
        startActivity(intent)
    }
    
    override fun onDestroy() {
        super.onDestroy()
        videoTracker.stop()
        exoPlayer.release()
    }
}

Java - Pre-Roll Ad

import com.permutive.android.MediaTracker;
import com.permutive.android.AdTracker;

public class VideoFragment extends Fragment {
    
    private MediaTracker videoTracker;
    private AdTracker adTracker;
    private ExoPlayer exoPlayer;
    
    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
        Permutive permutive = ((MyApplication) requireActivity().getApplication()).getPermutive();
        
        // Create video tracker
        MediaTracker.VideoProperties videoProps = new MediaTracker.VideoProperties.Builder()
            .title("Main Video Content")
            .build();
        
        videoTracker = permutive.trackVideoView(
            180000,  // 3 minutes
            videoProps,
            null,
            null
        );
        
        // Create ad tracker
        AdTracker.AdProperties adProps = new AdTracker.AdProperties(
            "Pre-Roll Advertisement",
            15,     // 15 seconds
            false,  // not muted
            "preroll_camp_123",
            "creative_456"
        );
        
        adTracker = videoTracker.trackAdView(15000, adProps);
        
        setupAdPlayer();
        
        return inflater.inflate(R.layout.fragment_video, container, null);
    }
    
    private void setupAdPlayer() {
        exoPlayer = new ExoPlayer.Builder(requireContext()).build();
        
        // Load ad
        Uri adUri = Uri.parse("https://example.com/ad.mp4");
        MediaItem adMediaItem = MediaItem.fromUri(adUri);
        exoPlayer.setMediaItem(adMediaItem);
        exoPlayer.prepare();
        
        // Track ad playback
        exoPlayer.addListener(new Player.Listener() {
            @Override
            public void onIsPlayingChanged(boolean isPlaying) {
                if (isPlaying) {
                    adTracker.play();
                } else {
                    adTracker.pause();
                }
            }
            
            @Override
            public void onPlaybackStateChanged(int state) {
                if (state == Player.STATE_ENDED) {
                    adTracker.completion();
                    loadMainVideoContent();
                } else if (state == Player.STATE_BUFFERING) {
                    adTracker.pause();
                }
            }
        });
        
        // Track clicks
        playerView.setOnClickListener(v -> {
            adTracker.clicked();
            openAdLandingPage();
        });
        
        exoPlayer.play();
    }
    
    private void loadMainVideoContent() {
        Uri videoUri = Uri.parse("https://example.com/video.mp4");
        MediaItem videoMediaItem = MediaItem.fromUri(videoUri);
        exoPlayer.setMediaItem(videoMediaItem);
        exoPlayer.prepare();
        exoPlayer.play();
        
        videoTracker.play();
    }
    
    private void openAdLandingPage() {
        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse("https://advertiser.com/landing"));
        startActivity(intent);
    }
    
    @Override
    public void onDestroy() {
        super.onDestroy();
        videoTracker.stop();
        exoPlayer.release();
    }
}

Use Cases

Pre-Roll Ad
Mid-Roll Ad
Standalone Ad
Ad Pod

Ad shown before video content starts:

// Create video tracker first
val videoTracker = permutive.trackVideoView(...)

// Create ad tracker from video tracker
val preRollAd = videoTracker.trackAdView(
    durationMs = 15000,
    adProperties = AdTracker.AdProperties(
        title = "Pre-Roll Ad",
        durationInSeconds = 15,
        campaignId = "preroll_123"
    )
)

// Play ad
preRollAd.play()
// ... ad plays ...
preRollAd.completion()

// Then play main video
videoTracker.play()

Ad shown during video content:

// Main video playing
videoTracker.pause()

// Create mid-roll ad
val midRollAd = videoTracker.trackAdView(
    durationMs = 30000,
    adProperties = AdTracker.AdProperties(
        title = "Mid-Roll Ad",
        durationInSeconds = 30,
        campaignId = "midroll_456"
    )
)

midRollAd.play()
// ... ad plays ...
midRollAd.completion()

// Resume main video
videoTracker.play()

Ad not associated with video content:

// Ad not associated with video content
val standaloneAd = permutive.trackVideoAdView(
    durationMs = 30000,
    adProperties = AdTracker.AdProperties(
        title = "Standalone Video Ad",
        durationInSeconds = 30,
        campaignId = "standalone_789"
    )
)

standaloneAd.play()
// ... ad plays ...
standaloneAd.completion()

Multiple ads played in sequence:

val ads = listOf(
    AdInfo("Ad 1", 15000, "camp_1", "creative_1"),
    AdInfo("Ad 2", 15000, "camp_2", "creative_2"),
    AdInfo("Ad 3", 30000, "camp_3", "creative_3")
)

ads.forEach { adInfo ->
    val adTracker = videoTracker.trackAdView(
        durationMs = adInfo.duration,
        adProperties = AdTracker.AdProperties(
            title = adInfo.title,
            durationInSeconds = adInfo.duration / 1000,
            campaignId = adInfo.campaignId,
            creativeId = adInfo.creativeId
        )
    )

    // Play ad
    adTracker.play()
    // ... wait for completion ...
    adTracker.completion()
}

Tracking Ad Interactions

Click Tracking

// User clicks ad
adClickArea.setOnClickListener {
    adTracker.clicked()  // Tracks VideoAdClicked event
    openAdvertiserUrl()
}

Skip Tracking

The canonical schema defines VideoAdView, VideoAdEngagement, VideoAdCompletion, and VideoAdClicked — there is no standard “skipped” event. If you want to capture skips, emit a custom event via trackWithAdProperties(...) and add the event name to your workspace schema:

// User skips ad (custom event — register the name in your workspace schema)
skipButton.setOnClickListener {
    adTracker.trackWithAdProperties(
        "VideoAdSkipped",
        EventProperties.from(
            "time_watched_seconds" to getWatchedTime()
        )
    )
    adTracker.completion()
    loadMainContent()
}

Error Tracking

Errors are likewise not in the standard schema — emit a custom event if you need to capture ad-load failures:

// Ad fails to load (custom event — register the name in your workspace schema)
adPlayer.setErrorListener { error ->
    adTracker.trackWithAdProperties(
        "VideoAdError",
        EventProperties.from(
            "error_code" to error.code,
            "error_message" to error.message
        )
    )
    adTracker.completion()
}

Troubleshooting

VideoAdCompletion Not Tracked

Problem: VideoAdCompletion events not appearing.Cause: completion() not called.Solution: Always call completion() when ad finishes:

// When ad ends
adTracker.completion()

Ad and Video Using Same ID

Problem: Ad events have same View ID as video.Cause: This is expected when creating AdTracker from MediaTracker.This is correct behavior - it links ad to video content. For independent tracking, use standalone AdTracker:

// Standalone (separate View ID)
val adTracker = permutive.trackVideoAdView(...)

Engagement Time Incorrect

Problem: Engaged time is wrong.Causes:

Not calling play() when ad starts
Not calling pause() for buffering

Solution: Track all state changes:

player.addListener(object : Player.Listener {
    override fun onIsPlayingChanged(isPlaying: Boolean) {
        if (isPlaying) adTracker.play() else adTracker.pause()
    }
})

Multiple Completion Events

Problem: Multiple VideoAdCompletion events tracked.Cause: Calling completion() multiple times.Solution: Call completion() only once. After calling it, AdTracker is closed.See Common Errors for more troubleshooting.

Best Practices

Do
Don't

Always call completion() when ad finishes
Track play/pause accurately
Use clicked() for click tracking
Create from MediaTracker for in-content ads
Provide campaign and creative IDs
Call play() immediately if ad auto-plays

Forget to call completion()
Call methods after completion()
Skip play/pause lifecycle events
Use standalone tracker for in-content ads

Video Tracking

Track video content

Event Properties

Custom properties

Page Tracking

Track pages

Issues

Solve common issues

API Reference

For complete API documentation, see the Javadocs.

AdTracker Interface

play() - Start/resume ad playback
play(positionMs: Long) - Start at specific position
pause() - Pause ad playback
clicked() - Track ad click (sends VideoAdClicked event)
completion() - Complete ad tracking (sends VideoAdCompletion event)
trackWithAdProperties(eventName: String) - Track custom event with ad properties
trackWithAdProperties(eventName: String, customProperties: EventProperties) - Track custom event with ad and custom properties

Creating AdTracker

MediaTracker.trackAdView(durationMs: Long, adProperties: AdTracker.AdProperties?) - Create from MediaTracker (shares View ID)
Permutive.trackVideoAdView(durationMs: Long, adProperties: AdTracker.AdProperties?, pageProperties: MediaTracker.PageProperties?, customEventProperties: EventProperties? = null) - Create standalone AdTracker

AdProperties

AdTracker.AdProperties(title, durationInSeconds, isMuted, campaignId, creativeId) - Ad property container

Creating AdTracker

Ad Methods

Use Cases

Interactions

​Overview

​Creating an AdTracker

​1. From MediaTracker (Recommended)

​2. Standalone AdTracker

​Ad Events

​1. VideoAdView Event

​2. VideoAdCompletion Event

​3. VideoAdClicked Event

​AdTracker Methods

​play()

​play(positionMs)

​pause()

​clicked()

​completion()

​Custom Events

​Ad Properties

​Standard Ad Properties

​Property Reference

​Complete Example

​Kotlin - Pre-Roll Ad

​Java - Pre-Roll Ad

​Use Cases

​Tracking Ad Interactions

​Click Tracking

​Skip Tracking

​Error Tracking

​Troubleshooting

​Best Practices

​Related Documentation

Video Tracking

Event Properties

Page Tracking

Issues

​API Reference

​AdTracker Interface

​Creating AdTracker

​AdProperties

Overview

Creating an AdTracker

1. From MediaTracker (Recommended)

2. Standalone AdTracker

Ad Events

1. VideoAdView Event

2. VideoAdCompletion Event

3. VideoAdClicked Event

AdTracker Methods

play()

play(positionMs)

pause()

clicked()

completion()

Custom Events

Ad Properties

Standard Ad Properties

Property Reference

Complete Example

Kotlin - Pre-Roll Ad

Java - Pre-Roll Ad

Use Cases

Tracking Ad Interactions

Click Tracking

Skip Tracking

Error Tracking

Troubleshooting

Best Practices

Related Documentation

API Reference

AdTracker Interface

Creating AdTracker

AdProperties