CTV Video Tracking

Event Schema

Implementation

Best Practices

Overview

Consistent video event tracking across CTV platforms enables unified audience analytics and cross-platform cohort building. This guide covers the standard video event schema and implementation patterns for all supported platforms.

Video Event Schema

Permutive uses a consistent video event schema across all CTV platforms:

Core Events

Event	Description	Trigger
Videoview	User initiated video playback	When video starts or user selects content
VideoCompletion	User finished watching	When video ends or user exits
VideoAdView	Video ad started playing	When ad playback begins
VideoAdCompletion	Video ad finished	When ad playback ends
VideoAdClicked	User clicked video ad	When user interacts with ad

Standard Video Properties

Use these properties consistently across events for unified analytics:

Property Naming: The schema uses snake_case property names. Native SDKs (tvOS, Android TV) use camelCase in their APIs (e.g., seasonNumber), which is automatically mapped to the snake_case schema.

Property	Type	Description
`title`	string	Video title
`genre`	string[]	List of genres (e.g., [“Drama”, “Thriller”])
`content_type`	string[]	Content types (e.g., [“Series”, “Episode”])
`age_rating`	string	Age rating (e.g., “PG-13”, “TV-MA”)
`runtime`	number	Runtime in seconds
`country`	string	Origin country
`original_language`	string	Original language code
`audio_language`	string	Audio language being watched
`subtitles.enabled`	boolean	Whether subtitles are enabled
`subtitles.language`	string	Subtitle language
`season_number`	number	Season number (for series)
`episode_number`	number	Episode number (for series)
`consecutive_episodes`	number	Consecutive episodes watched
`iab_categories`	string[]	IAB content taxonomy categories

Completion Event Properties

Additional properties for VideoCompletion:

Property	Type	Description
`completion`	number	Percentage watched (0.0 - 1.0)
`engaged_time`	number	Time spent watching in seconds

Ad Event Properties

Properties for video ad events:

Property	Type	Description
`ad_id`	string	Advertisement identifier
`ad_position`	string	Position: “preroll”, “midroll”, “postroll”
`ad_duration`	number	Ad duration in seconds
`campaign_id`	string	Campaign identifier
`creative_id`	string	Creative identifier

Platform Implementation

Web CTV
tvOS
Android TV
Roku

Platforms: Samsung Tizen, LG WebOS, HbbTVUse the CTV addon for automatic event tracking:

// Initialize with video properties
permutive.addon("ctv", {
  duration: 3600000, // milliseconds
  videoProperties: {
    title: "Show Title - S1E1",
    genre: ["Drama", "Thriller"],
    season_number: 1,
    episode_number: 1,
    runtime: 3600
  }
})

// Sync with player events
videoElement.addEventListener("play", () => {
  permutive.addons.ctv.play(videoElement.currentTime * 1000)
})

videoElement.addEventListener("pause", () => {
  permutive.addons.ctv.pause(videoElement.currentTime * 1000)
})

// Track completion
const onVideoEnd = () => {
  permutive.addons.ctv.stop(videoElement.currentTime * 1000)
}

// Track ads manually
const onAdStart = (ad) => {
  permutive.addons.ctv.track("VideoAdView", {
    ad_id: ad.id,
    ad_position: ad.position
  })
}

Automatic Events:

Videoview - tracked when addon is initialized
VideoCompletion - tracked when .stop() is called

See Web CTV documentation for full details.

Platform: tvOSUse MediaTracker for video tracking:

import Permutive_iOS

// Create MediaTracker when video starts
mediaTracker = try? Permutive.shared.createMediaTracker(
    durationMilliseconds: videoDurationMs,
    videoProperties: MediaTracker.VideoProperties(
        title: "Show Title - S1E1",
        genre: ["Drama", "Thriller"],
        contentType: ["Series", "Episode"]
    ),
    pageProperties: MediaTracker.PageProperties(
        title: "Now Playing",
        url: URL(string: "https://example.com/show/s1e1")
    )
)

// Sync with player
player.observe(\.timeControlStatus) { player, _ in
    switch player.timeControlStatus {
    case .playing:
        try? mediaTracker?.play()
    case .paused:
        mediaTracker?.pause()
    default:
        break
    }
}

// Track completion
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    mediaTracker?.stop()
}

Automatic Events:

VideoPlay - tracked on first play() call
VideoPause - tracked on pause() call
VideoComplete - tracked on stop() call

See tvOS documentation for full details.

Platforms: Android TV, Google TVUse MediaTracker for video tracking:

import com.permutive.android.MediaTracker

// Create MediaTracker when video starts
videoTracker = permutive.trackVideoView(
    durationMilliseconds = videoDurationMs,
    videoProperties = MediaTracker.VideoProperties(
        title = "Show Title - S1E1",
        genre = listOf("Drama", "Thriller"),
        contentType = listOf("Series", "Episode"),
        seasonNumber = 1,
        episodeNumber = 1
    ),
    pageProperties = MediaTracker.PageProperties(
        title = "Now Playing",
        url = Uri.parse("https://example.com/show/s1e1")
    )
)

// Sync with ExoPlayer
exoPlayer.addListener(object : Player.Listener {
    override fun onIsPlayingChanged(isPlaying: Boolean) {
        if (isPlaying) {
            videoTracker.play()
        } else {
            videoTracker.pause()
        }
    }
})

// Track completion
override fun onDestroy() {
    super.onDestroy()
    videoTracker.stop()
}

Automatic Events:

Videoview - tracked when MediaTracker is created
VideoComplete - tracked on stop() call

See Android TV documentation for full details.

Platform: RokuTrack events manually through the Permutive Task:

' Generate view ID for this content session
m.global.permutive.view_id = CreateObject("roDeviceInfo").GetRandomUUID()

' Track video start
m.global.permutive.event = {
    name: "Videoview"
    properties: {
        title: m.video.title
        genre: m.video.genre
        season_number: m.video.season
        episode_number: m.video.episode
        runtime: m.video.duration
    }
}

' Track video completion
sub onVideoComplete()
    m.global.permutive.event = {
        name: "VideoCompletion"
        properties: {
            title: m.video.title
            completion: m.player.position / m.player.duration
            engaged_time: m.engagedSeconds
        }
    }
end sub

' Track ad events
sub onAdStart(ad as Object)
    m.global.permutive.event = {
        name: "VideoAdView"
        properties: {
            ad_id: ad.id
            ad_position: ad.position
        }
    }
end sub

Manual Events: All events must be tracked explicitly on Roku.See Roku documentation for full details.

Engagement Tracking

How Engagement Works

Engagement time measures how long a user actively watches content:

Start - When play() is called, engagement timer starts
Pause - When pause() is called, timer pauses
Resume - When play() is called again, timer resumes
Complete - When stop() is called, total engagement is recorded

Buffering Considerations

Buffering should pause engagement tracking:

Web CTV
Native (iOS/Android)

videoElement.addEventListener("waiting", () => {
  permutive.addons.ctv.pause()
})

videoElement.addEventListener("playing", () => {
  permutive.addons.ctv.play()
})

// Android example
exoPlayer.addListener(object : Player.Listener {
    override fun onPlaybackStateChanged(state: Int) {
        when (state) {
            Player.STATE_BUFFERING -> videoTracker.pause()
            Player.STATE_READY -> {
                if (exoPlayer.isPlaying) videoTracker.play()
            }
        }
    }
})

Seeking/Scrubbing

When users seek to a new position:

// Web CTV
videoElement.addEventListener("seeked", () => {
  permutive.addons.ctv.play(videoElement.currentTime * 1000)
})

// Android
exoPlayer.addAnalyticsListener(object : AnalyticsListener {
    override fun onPositionDiscontinuity(
        eventTime: AnalyticsListener.EventTime,
        reason: Int
    ) {
        if (reason == Player.DISCONTINUITY_REASON_SEEK) {
            videoTracker.play(exoPlayer.currentPosition)
        }
    }
})

Ad Break Handling

Pre-roll Ads

Track ads before main content:

// Web CTV example
const onPrerollStart = (ad) => {
  permutive.addons.ctv.track("VideoAdView", {
    ad_id: ad.id,
    ad_position: "preroll",
    ad_duration: ad.duration
  })
}

const onPrerollEnd = (ad) => {
  permutive.addons.ctv.track("VideoAdCompletion", {
    ad_id: ad.id
  })

  // Now start main content
  permutive.addon("ctv", {
    duration: videoDuration,
    videoProperties: { title: "Show Title" }
  })
  permutive.addons.ctv.play()
}

Mid-roll Ads

Pause main content tracking during ads:

const onMidrollStart = (ad) => {
  // Pause main content tracking
  permutive.addons.ctv.pause()

  // Track ad
  permutive.addons.ctv.track("VideoAdView", {
    ad_id: ad.id,
    ad_position: "midroll"
  })
}

const onMidrollEnd = (ad) => {
  permutive.addons.ctv.track("VideoAdCompletion", {
    ad_id: ad.id
  })

  // Resume main content tracking
  permutive.addons.ctv.play()
}

Post-roll Ads

Track ads after main content completes:

const onContentEnd = () => {
  // Complete main content tracking first
  permutive.addons.ctv.stop()
}

const onPostrollStart = (ad) => {
  permutive.addons.ctv.track("VideoAdView", {
    ad_id: ad.id,
    ad_position: "postroll"
  })
}

Best Practices

Do
Don't

Set duration accurately - Provide video duration in milliseconds when initializing
Sync with player state - Call play()/pause() when the player state changes
Always call stop() - Ensure stop() is called when video ends or user exits
Handle buffering - Pause tracking during buffering states
Track all ad events - Capture ad views and completions for ad analytics
Use consistent properties - Follow the standard schema across all platforms
Include video metadata - Richer metadata enables more precise cohort building
Generate unique view IDs - Create new view IDs per content session (Roku)

Don’t forget to call stop() when done
Don’t create multiple trackers simultaneously
Don’t skip duration - completion percentage requires it
Don’t track engagement during ads (pause main tracker)
Don’t use inconsistent property names across platforms
Don’t send PII in video properties
Don’t guess at video duration - wait for it to be available

Cross-Platform Consistency

For unified analytics across platforms, ensure:

Event Name Consistency

Platform	Videoview Event	Completion Event	Ad View Event
Web CTV	`Videoview`	`VideoCompletion`	`VideoAdView`
tvOS	`VideoPlay`	`VideoComplete`	Manual
Android TV	`Videoview`	`VideoComplete`	Manual
Roku	`Videoview` (manual)	`VideoCompletion` (manual)	`VideoAdView` (manual)

Property Mapping

Ensure property names are consistent:

Web CTV	iOS SDK	Android SDK	Roku
`title`	`title`	`title`	`title`
`genre`	`genre`	`genre`	`genre`
`season_number`	`seasonNumber`	`seasonNumber`	`season_number`
`episode_number`	`episodeNumber`	`episodeNumber`	`episode_number`

Work with Technical Services to configure a unified event schema across all platforms.

Troubleshooting

Engagement time is incorrect

Problem: Engaged time doesn’t match expected values.Solutions:

Ensure play() is called only when video is actually playing
Call pause() during buffering and paused states
Verify stop() is called when video ends
Check that ad breaks pause the main content tracker

Completion percentage is 0 or missing

Problem: VideoCompletion event shows 0% or null completion.Solutions:

Provide duration when creating the tracker/addon
Ensure duration is in the correct unit (milliseconds for most SDKs)
Wait for video metadata to load before creating tracker

Video events not appearing in dashboard

Problem: Events don’t show in Permutive analytics.Solutions:

Verify SDK is initialized with correct credentials
Check browser/device console for errors
Ensure events match your workspace schema
Wait 5-10 minutes for events to process

Ad events not linked to video sessions

Problem: Ad events aren’t associated with video content.Solutions:

Track ads using the same addon/tracker instance
On Roku, use the same view_id for content and ads
Ensure ad events fire during the video session

CTV Overview

Platform selection guide

Web CTV

Tizen, WebOS, HbbTV integration

tvOS

tvOS integration

Android TV

Android TV integration

Roku

Roku integration

iOS Video Tracking

Detailed iOS MediaTracker docs

Get Started

Products

SDKs

Governance

CTV Video Tracking

Event Schema

Implementation

Best Practices

Overview

Video Event Schema

Core Events

Standard Video Properties

Completion Event Properties

Ad Event Properties

Platform Implementation

Engagement Tracking

How Engagement Works

Buffering Considerations

Seeking/Scrubbing

Ad Break Handling

Pre-roll Ads

Mid-roll Ads

Post-roll Ads

Best Practices

Cross-Platform Consistency

Event Name Consistency

Property Mapping

Troubleshooting

CTV Overview

Web CTV

tvOS

Android TV

Roku

iOS Video Tracking

Get Started

Products

SDKs

Governance

Event Schema

Implementation

Best Practices

​Overview

​Video Event Schema

​Core Events

​Standard Video Properties

​Completion Event Properties

​Ad Event Properties

​Platform Implementation

​Engagement Tracking

​How Engagement Works

​Buffering Considerations

​Seeking/Scrubbing

​Ad Break Handling

​Pre-roll Ads

​Mid-roll Ads

​Post-roll Ads

​Best Practices

​Cross-Platform Consistency

​Event Name Consistency

​Property Mapping

​Troubleshooting

​Related Documentation

CTV Overview

Web CTV

tvOS

Android TV

Roku

iOS Video Tracking

Overview

Video Event Schema

Core Events

Standard Video Properties

Completion Event Properties

Ad Event Properties

Platform Implementation

Engagement Tracking

How Engagement Works

Buffering Considerations

Seeking/Scrubbing

Ad Break Handling

Pre-roll Ads

Mid-roll Ads

Post-roll Ads

Best Practices

Cross-Platform Consistency

Event Name Consistency

Property Mapping

Troubleshooting

Related Documentation