How to Capture Analytics with Vocal Video Embeds

Embed Architecture

Vocal Video embeds are based on iframes. To find embed code, go to a published video, click Share > Embed

The Embed window for a published video, showing the embed code to copy

The two divs wrapping the iframe are configurable to ensure the iframe fits the space available (while maintaining the proper aspect ratio). You can use our Embed Builder to customize these parameters.

The trailing ld+json    script tag is a standard used by search engines to help indexing your videos. You can learn more here.

Analytics messages are sent by single-video embeds, both the standard player and the popover. Gallery embeds don't send them.

iframe Constraints

An iframe effectively wraps a contained version of Vocal Video in your site. In earlier days of the web, iframes had a number of issues and could be used for nefarious purposes. Thankfully web browsers have come a long way and are now enforcing security measures that make iframes a great solution for embedding videos.

These security restrictions do require a small bit of effort, but nothing a few lines of Javascript can't solve. Plus, you'll have complete control over how data flows to and from your site.

All communication between iframes and your site are mediated by the postMessage API. This API is supported by all modern browsers.

postMessage    enforces the origin policy of both your parent window and the Vocal Video controlled iframe. In general, Vocal Video will only operate on its primary domain, vocalvideo.com   , but postMessage    provides a mechanism for Vocal Video to send data to your domain.

Registering the Origin of an Embed

As the parent window, you know that the Vocal Video iframe will be hosted on vocalvideo.com   , but Vocal Video doesn't know your domain. To set up the secure cross-domain communication, you'll need to send us a message to start the process.

To begin, we load the iframe element using querySelector   . Every Vocal Video iframe is named vocalvideo_  followed by the video's ID, so you can target it by name, add your own unique ID, or use any other Javascript based method (e.g. jQuery). Wait for the iframe to finish loading before you send the message:

const iframe = document.querySelector('iframe[name^="vocalvideo_"]');

iframe.addEventListener('load', () => {
  iframe.contentWindow.postMessage('vocal-video:analytics-start', 'https://vocalvideo.com');
});

The first parameter of postMessage  is the message itself. Use vocal-video:analytics-start  to start analytics messages and vocal-video:analytics-stop  to stop them. Older examples that use start  should be updated.

By including https://vocalvideo.com    as the second parameter, you are explicitly allowing the message to be received by our iframe. In turn, our iframe will capture the originating domain of this message and begin sending Javascript events to your parent window.

Should you ever want to stop delivery of analytics messages from our iframe, just send the vocal-video:analytics-stop   message:

iframe.contentWindow.postMessage('vocal-video:analytics-stop', 'https://vocalvideo.com');

Capturing Messages for Analytics

Once your origin domain is registered, we'll begin delivering analytics via postMessage  . To receive these messages, you'll need to set up an event listener on your window:

const PLAYBACK_ACTIONS = ['play', 'pause', 'seeked'];

window.addEventListener('message', (event) => {
  // Only accept messages from Vocal Video
  if (event.origin !== 'https://vocalvideo.com') return;

  const data = event.data;
  // The embed sends a few other messages too; keep only playback events
  if (!data || !PLAYBACK_ACTIONS.includes(data.action)) return;

  console.log(data.action, data.title, data.currentTime);
});

Note: you should always verify that messages are coming from https://vocalvideo.com   , as the example does with event.origin . The embed also sends a few housekeeping messages whose action  starts with vocal-video: , so filter on the playback actions below.

The Analytics Object

Analytics information from Vocal Video iframes will be contained in the data    attribute of the event object. The data    object has the following attributes:

action   : After analytics messages are started, the embed posts a playback event each time the viewer plays (play ), pauses (pause ) or skips to a new point (seeked ).

currentTime   : The current timestamp of the video, in seconds

duration   : The total duration of the video, in seconds

id   : The numeric ID of the video. This is a fixed value and is used in the src    attribute of the iframe.

slug   : The customizable url variable used to identify the video on public pages (should you have the visibility setting enabled) and inside the Vocal Video application. It's empty when you embed a single response rather than a video.

title   : The current public title of the video (customizable inside Vocal Video)

A typical message looks like this:

{
  action: 'play',
  id: 12345,
  slug: 'customer-story-acme',
  currentTime: 0,
  duration: 94.5,
  title: 'Customer Story: Acme'
}

Putting It All Together

Now that you're receiving the analytics event objects, it's just a matter of sending the necessary data to your analytics platform. Your particular needs and data format may vary, but here are some examples.

Google Analytics 4

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://vocalvideo.com') return;
  const data = event.data;
  if (!data || !['play', 'pause', 'seeked'].includes(data.action)) return;

  gtag('event', 'vocal_video_' + data.action, {
    video_title: data.title,
    video_current_time: Math.round(data.currentTime),
    video_duration: Math.round(data.duration),
    video_provider: 'Vocal Video'
  });
});

Google Tag Manager

window.dataLayer = window.dataLayer || [];

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://vocalvideo.com') return;
  const data = event.data;
  if (!data || !['play', 'pause', 'seeked'].includes(data.action)) return;

  window.dataLayer.push({
    event: 'vocal_video_' + data.action,
    videoId: data.id,
    videoTitle: data.title,
    videoCurrentTime: data.currentTime,
    videoDuration: data.duration
  });
});

Keep in mind your analytics endpoint (e.g. gtag    in the case of Google Analytics) may be defined in a variety of places or using different aliases. These examples are meant to be a jumping off point. You'll need to decide what metrics are important to your business and your nomenclature of events.

Still need help? Contact Support at support@vocalvideo.com

Related Articles