Skip to main content

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

EventDescriptionTrigger
VideoviewUser initiated video playbackWhen video starts or user selects content
VideoCompletionUser finished watchingWhen video ends or user exits
VideoAdViewVideo ad started playingWhen ad playback begins
VideoAdCompletionVideo ad finishedWhen ad playback ends
VideoAdClickedUser clicked video adWhen 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.
PropertyTypeDescription
titlestringVideo title
genrestring[]List of genres (e.g., [“Drama”, “Thriller”])
content_typestring[]Content types (e.g., [“Series”, “Episode”])
age_ratingstringAge rating (e.g., “PG-13”, “TV-MA”)
runtimenumberRuntime in seconds
countrystringOrigin country
original_languagestringOriginal language code
audio_languagestringAudio language being watched
subtitles.enabledbooleanWhether subtitles are enabled
subtitles.languagestringSubtitle language
season_numbernumberSeason number (for series)
episode_numbernumberEpisode number (for series)
consecutive_episodesnumberConsecutive episodes watched
iab_categoriesstring[]IAB content taxonomy categories

Completion Event Properties

Additional properties for VideoCompletion:
PropertyTypeDescription
completionnumberPercentage watched (0.0 - 1.0)
engaged_timenumberTime spent watching in seconds

Ad Event Properties

Properties for video ad events:
PropertyTypeDescription
ad_idstringAdvertisement identifier
ad_positionstringPosition: “preroll”, “midroll”, “postroll”
ad_durationnumberAd duration in seconds
campaign_idstringCampaign identifier
creative_idstringCreative identifier

Platform Implementation

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.

Engagement Tracking

How Engagement Works

Engagement time measures how long a user actively watches content:
  1. Start - When play() is called, engagement timer starts
  2. Pause - When pause() is called, timer pauses
  3. Resume - When play() is called again, timer resumes
  4. Complete - When stop() is called, total engagement is recorded

Buffering Considerations

Buffering should pause engagement tracking:
videoElement.addEventListener("waiting", () => {
  permutive.addons.ctv.pause()
})

videoElement.addEventListener("playing", () => {
  permutive.addons.ctv.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

  • 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)

Cross-Platform Consistency

For unified analytics across platforms, ensure:

Event Name Consistency

PlatformVideoview EventCompletion EventAd View Event
Web CTVVideoviewVideoCompletionVideoAdView
tvOSVideoPlayVideoCompleteManual
Android TVVideoviewVideoCompleteManual
RokuVideoview (manual)VideoCompletion (manual)VideoAdView (manual)

Property Mapping

Ensure property names are consistent:
Web CTViOS SDKAndroid SDKRoku
titletitletitletitle
genregenregenregenre
season_numberseasonNumberseasonNumberseason_number
episode_numberepisodeNumberepisodeNumberepisode_number
Work with Technical Services to configure a unified event schema across all platforms.

Troubleshooting

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
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
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
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