Overview
Web-based CTV platforms run JavaScript applications in embedded browser engines. Permutive’s JavaScript SDK integrates with these platforms through the CTV addon, which provides specialized video tracking capabilities for streaming content. Supported Platforms:Prerequisites
Permutive Workspace
An active Permutive workspace. If you’re not yet a customer, get in touch.
Public API Key
Your API key from the Dashboard.
CTV Addon
Enable the CTV addon in your Dashboard integrations.
Setup
The JavaScript Tag
Deploy the Permutive JavaScript tag in your CTV web application. The tag initializes the SDK and downloads your workspace-specific bundle.<WORKSPACE_API_KEY>- Your workspace API key<WORKSPACE_ID>- Your workspace ID<ORGANIZATION_ID>- Your organization ID<CTV_PLATFORM>- The platform identifier (e.g.,hbbtv,lg-webos-24)
Deployment Considerations
CTV Browser Limitations: CTV platforms use embedded browser engines with different JavaScript capabilities than desktop browsers. Always use the platform-specific SDK bundle that matches your target platform version.
- Use the correct platform bundle - Each platform version has a specific SDK bundle optimized for its JavaScript engine
- Initialize before video playback - Ensure the SDK is loaded before initializing the CTV addon
- Test on device - Emulators may not reflect actual device behavior; test on physical CTV hardware
- Configure network access - Add required domains to your app’s external access policy (especially on Tizen)
Samsung Tizen
Platform Version SDKs
Tizen requires platform-specific SDK bundles. Select the bundle matching your target Tizen platform version:| Platform Version | Script Source |
|---|---|
| Tizen 8.0 | <WORKSPACE_ID>-tizen-8-0.js |
| Tizen 7.0 | <WORKSPACE_ID>-tizen-7-0.js |
| Tizen 6.5 | <WORKSPACE_ID>-tizen-6-5.js |
| Tizen 6.0 | <WORKSPACE_ID>-tizen-6-0.js |
| Tizen 5.5 | <WORKSPACE_ID>-tizen-5-5.js |
| Tizen 5.0 | <WORKSPACE_ID>-tizen-5-0.js |
| Tizen 4.0 | <WORKSPACE_ID>-tizen-4-0.js |
| Tizen 3.0 | <WORKSPACE_ID>-tizen-3-0.js |
| Tizen 2.4 | <WORKSPACE_ID>-tizen-2-4.js |
| Tizen 2.3 | <WORKSPACE_ID>-tizen-2-3.js |
Privileges
Configure the required Tizen privileges in your application:| Privilege | Description |
|---|---|
http://tizen.org/privilege/internet | Required for network access |
External Access Policy
Add Permutive’s CDN and APIs to your external access policy inconfig.xml:
TIFA (Tizen ID for Advertising)
Samsung provides TIFA as a unique advertising identifier. To use TIFA with Permutive:- Add
tifaas an identifier in your Dashboard identifiers settings - Identify users using the TIFA ID:
LG WebOS
Platform Version SDKs
LG WebOS requires platform-specific SDK bundles. Select the bundle matching your target WebOS platform version:| Platform Version | Script Source |
|---|---|
| webOS TV 24 | <WORKSPACE_ID>-lg-webos-24.js |
| webOS TV 23 | <WORKSPACE_ID>-lg-webos-23.js |
| webOS TV 22 | <WORKSPACE_ID>-lg-webos-22.js |
| webOS TV 6.x | <WORKSPACE_ID>-lg-webos-6.js |
| webOS TV 5.x | <WORKSPACE_ID>-lg-webos-5.js |
| webOS TV 4.x | <WORKSPACE_ID>-lg-webos-4.js |
| webOS TV 3.x | <WORKSPACE_ID>-lg-webos-3.js |
| webOS TV 2.x | <WORKSPACE_ID>-lg-webos-2.js |
| webOS TV 1.x | <WORKSPACE_ID>-lg-webos-1.js |
Script Example
HbbTV
HbbTV (Hybrid Broadcast Broadband TV) applications use the standard CTV script path:CTV Addon
The CTV addon provides video-specific tracking APIs. Initialize it when video content starts:Initialization
permutive.addons.ctv.
Addon Methods
| Method | Description | Events Tracked |
|---|---|---|
.play(position?) | Call when content plays or position changes. Starts engagement tracking. Position in milliseconds. | - |
.pause(position?) | Call when content pauses. Stops engagement tracking. Position in milliseconds. | - |
.stop(position?) | Call when user stops/exits content. Sends completion event. Position in milliseconds. | VideoCompletion |
.setDuration(duration) | Update content duration in milliseconds. Set before stopping for accurate completion. | - |
.track(name, properties, options) | Track custom events (e.g., ad events). | Specified event |
Video Properties
The following properties are available for video events. All are optional but tracking more enables richer cohort building:| Property | Type | Description |
|---|---|---|
title | string | Video title |
genre | string[] | List of genres |
content_type | string[] | Content types |
age_rating | string | Age rating (e.g., “PG-13”) |
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 |
episode_number | number | Episode number |
consecutive_episodes | number | Consecutive episodes watched |
iab_categories | string[] | IAB content taxonomy categories |
Properties are sanitized to match expected types. Invalid types are removed rather than causing errors.
Complete Example
Event Tracking
Automatic Events
The CTV addon automatically tracks:| Event | Description |
|---|---|
| Videoview | Tracked when addon is initialized. Indicates user intent to watch content. |
| VideoCompletion | Tracked when .stop() is called. Includes completion percentage and engaged_time. |
Manual Events
Track additional video events using.track():
| Event | Description |
|---|---|
| VideoAdView | Video ad started playing |
| VideoAdCompletion | Video ad finished |
| VideoAdClicked | User clicked on video ad |
JavaScript SDK Reference
For advanced use cases, the full JavaScript SDK is available. Key APIs include:permutive.identify([...])- Set user identitiespermutive.track(eventName, properties)- Track custom eventspermutive.segments()- Get current cohort membershipspermutive.ready(callback)- Execute code when SDK is ready
Troubleshooting
SDK not loading
SDK not loading
Problem: Permutive SDK fails to load on CTV device.Solutions:
- Verify external access policy includes Permutive domains
- Check network connectivity on the device
- Ensure correct platform-specific script URL
- Verify API key and workspace ID are correct
Events not being tracked
Events not being tracked
Problem: Events don’t appear in the dashboard.Solutions:
- Verify CTV addon is enabled in dashboard settings
- Check browser console for JavaScript errors
- Ensure events match your workspace schema
- Wait 5-10 minutes for events to process
Engagement time incorrect
Engagement time incorrect
Problem: Engagement metrics don’t match expected values.Solutions:
- Ensure
.play()is called when video plays - Ensure
.pause()is called when video pauses or buffers - Call
.stop()when video ends or user exits - Set correct duration before calling
.stop()
GAM targeting not working
GAM targeting not working
Problem: Google Ad Manager targeting values not applied.Solutions:
- Ensure GPT library loads before Permutive
- Verify
_pdfpsexists in localStorage - Check that ad requests fire after Permutive initializes