How to Capture Analytics with Vocal Video Embeds

Embed Architecture

Vocal Video embeds are based on iframes. Here's a typical example:

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. To access the Embed Builder you can click on the lavender "embed" button below any published video and then hit "customize."

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

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 restriction 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 (96.82% of global users).

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 setup 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. You can target our iframe based on their name, or add a unique ID use any other Javascript based method (e.g. jquery).

The first parameter of the postMessage method call, start, will instruct our Javascript to begin the process of sending analytics data to you.

By including vocalvideo.com as the second parameter, you are explicitly allowing the message to be received by our iframe. In turn, our iframe will capturing 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.

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:

Note: you should always verify that the message are coming from vocalvideo.com.

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: The type of interaction that occurred. Valid values are: play, pause, and seeked

currentTime: The current timestamp of the video

duration: The total duration of the video

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

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

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:

Keep in mind your analytics endpoint (e.g. ga 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.