API reference

Use the JavaScript functions, identified in this article, to control video tracking behavior. Call PARSELY.video.trackPlay() and PARSELY.video.trackPause() to manually track video playback, PARSELY.video.detectVideos() to scan for new player instances, or PARSELY.video.addStrategy() to implement custom player integrations.

Detect videos

By default, the Parse.ly tracker automatically discovers video players when the page loads. For Single Page Applications (SPAs) or sites that lazy-load videos, call detectVideos() whenever you add a new player instance to the page.

This function is not necessary for new video assets loaded into an existing player instance, as they are tracked automatically.

Syntax

PARSELY.video.detectVideos()

Parameters

None.

Return value

None (undefined).

Track video playback

Call trackPlay() when a video begins playing. The function can be called on the initial play and on subsequent plays after pausing. The tracker continues sending heartbeat events until calling trackPause().

Syntax

PARSELY.video.trackPlay(videoId, metadata)
PARSELY.video.trackPlay(videoId, metadata, urlOverride)

Parameters

Return value

None (undefined).

Side effects

• Sets PARSELY.video.trackedVideos[videoId].hasStartedPlaying to true
• Sets PARSELY.video.trackedVideos[videoId].isPlaying to true
• Sends a videostart event on the first call after page load or after calling reset()
• Starts an internal timer that sends vheartbeat events periodically until trackPause() is called

Example

Basic usage:

PARSELY.video.trackPlay('video-abc123', {
  title: 'Product Demo Video',
  duration: 180000,  // 3 minutes in milliseconds
  image_url: 'https://example.com/video-thumb.jpg',
  pub_date_tmsp: 1704067200000,
  section: 'tutorials',
  authors: ['Jane Smith'],
  tags: ['product', 'demo', 'tutorial']
});

Pause video playback

Call trackPause() when a video stops playing, whether due to the user pausing it or the video ending. This stops the heartbeat timer until video playback resumes.

Syntax

PARSELY.video.trackPause(videoId, metadata)
PARSELY.video.trackPause(videoId, metadata, urlOverride)

Parameters

Return value

None (undefined).

Side effects

• Sets PARSELY.video.trackedVideos[videoId].isPlaying to false
• Stops the internal vheartbeat timer
• If metadata is different since calling trackPlay(), it will overwrite PARSELY.video.trackedVideos[videoId].metadata. However, only the metadata called by trackPlay() will display in the Dashboard video listing.

Reset video

Use reset() when a video player loads a new video. This ensures that the next trackPlay() call generates a new videostart event rather than continuing the previous video’s tracking session.

Syntax

PARSELY.video.reset(videoId)

Parameters

Return value

None (undefined).

Side effects

• Sets PARSELY.video.trackedVideos[videoId].hasStartedPlaying to false
• Clears the flag indicating the video has started. The next call to trackPlay() will send a videostart event.

Add custom strategy

Use addStrategy() to add tracking support for custom or unsupported video players. The strategy object defines how Parse.ly detects and interacts with your video player.

Syntax

PARSELY.video.addStrategy(strategy)

Parameters

Return value

None (undefined).

Examples

See Custom video tracking for examples.

Video metadata

The metadata object passed to trackPlay() and trackPause() contains information about the video. This metadata appears in the Parse.ly Dashboard and enables filtering, reporting, and analysis.

Metadata fields

Best practices

Align with post metadata: Use the same metadata structure for videos and posts to enable consolidated analysis across content types.

Include recognizable identifiers: Always provide title and image_url so videos are easily identifiable in the Dashboard.

Enable date filtering: Include pub_date_tmsp to allow filtering by publication date in Dashboard reports and API queries.

Use consistent sections and tags: Maintain consistency with your post metadata taxonomy for better cross-content reporting.

Examples

Minimal metadata (required field only):

{
  title: 'Getting Started Tutorial'
}

Recommended metadata:

{
  title: 'Advanced Analytics Dashboard Tour',
  image_url: 'https://example.com/videos/analytics-tour.jpg',
  duration: 300000,  // 5 minutes
  pub_date_tmsp: 1704067200000,  // January 1, 2024
  section: 'tutorials'
}

Complete metadata with all optional fields:

{
  title: 'Q4 2024 Product Launch Event',
  image_url: 'https://example.com/events/q4-launch.jpg',
  duration: 3600000,  // 1 hour
  pub_date_tmsp: 1704067200000,
  section: 'events',
  authors: ['Marketing Team', 'Product Division'],
  tags: ['product-launch', 'q4-2024', 'keynote', 'live-event']
}

Customizing metadata for supported players:

window.PARSELY = window.PARSELY || {
  video: {
    onPlay: function(playerApi, videoId, metadata) {
      // Add custom section based on video ID
      if (videoId.startsWith('premium-')) {
        metadata.section = 'premium-content';
      }
      
      // Add tags from your data store
      metadata.tags = myDataStore.getVideoTags(videoId);
      
      // Override title if needed
      if (!metadata.title) {
        metadata.title = myDataStore.getVideoTitle(videoId);
      }
      
      PARSELY.video.trackPlay(videoId, metadata);
    }
  }
};