Integrating Players with Quantcast Analytics

In this topic you will learn how to integrate the Quantcast analytics service into your Video Cloud players. By integrating Quantcast into your players, you will receive detailed analytics information about the reach and engagement of your content as it relates to your audience.

Note: The steps outlined in this topic are for Flash based players only.

Leveraging Quantcast in your Video Cloud players is as simple as setting some configuration parameters and dropping the Quantcast module into the Video Cloud players that you want 'quantified'.

This article provides information on how to use the Quantcast analytics SWF as well as how it was implemented. You can download the source to this analytics SWF and modify it to meet your business requirements.

What is Tracked

The following events are tracked in Quantcast:

• Impression
• Played
• Progress
• Paused
• Resumed
• Seeked
• Finished

For each of these events, the following information is tracked:

• videoID: the id of the video in the Brightcove system
• media: "video", representing the type of media that is being tracked
• title: the display name of the video that is currently being tracked
• labels: player_name.playlist_name.video_name by default, can be overriden via flashvars
• duration: the duration of the video that is currently playing
• meta: not sent unless you explicitly set this value via flashvars
• time: the location of the playhead in the currently playing video (only relevant for seek and progress events)

Using the Quantcast Analytics SWF

Follow these steps in order to use the Quantcast analytics SWF:

1. If you have not signed up for a Quantcast account, you should do so here.
2. Download this zip file. Unzip the contents and place the QuantcastAnalyticsModule.swf onto your web server. Write down the URL to the location where you placed the QuantcastAnalyticsModule.swf.
3. At the root of the web server where you placed the QuantcastAnalyticsModule.swf, place a file named crossdomain.xml with the following contents:

<allow-access-from domain="admin.brightcove.com" />

You may have to contact your webmaster in order to make this modification. The crossdomain.xml file is a file that lives on your domain that contains a list of trusted third party domains. If you're unsure how to modify this file as described here, please consult your webmaster. For more information and sample crossdomain files, read Cross-Domain Security

4. Set your players to use the Quantcast Analytics SWF, as described in Developing an Analytics SWF. You can do this either by editing your plug-ins player settings in the Publishing module or by adding the SWF as a module in your player template. Note that you will need to pass in your Quantcast ID using the qacct parameter in the Analytics SWF URL you enter. So, for example, you should set your Analytics SWF URL as:
   

   http://mysite.com/QuantcastAnalyticsModule.swf?qacct=AA-123456-A

Extended Configuration

This section lists additional configuration you can make to the Quantcast Analytics SWF to enable you to customize the data that is tracked for each event fired into Quantcast.

You can customize the following options that are sent to Quantcast:

• labels: By default, when an event is fired into Quantcast, several labels are sent.  The player name, playlist name (if available) and video name are sent.  Additionally, another label is sent which is captured as [player name.playlist name. video name].  This hierarchical dot notation enables you to view reports at the roll-up level.  You can override the labels that are sent in two ways:
  
  • You can configure your Brightcove account to use custom fields for your videos.  Any custom field name that begins with qcast_' is considered to be intended to be used as a Quantcast label and will be fired off to Quantcast.  So, if you define qcast_site and qcast_category as custom fields and then on a specific video, you set qcast_site=foo and qcast_category=bar, two labels will be sent to Quantcast (foo,bar).  You can learn more about custom fields here.
  • By passing in your own labels to the Quantcast Analytics SWF.  To do this, set the quantcastLabels query parameter when referencing the SWF to the value you want.  For example, to set your label to sport,  reference the SWF as follows:

http://mysite.com/QuantcastAnalyticsModule.swf?qacct=AA-1234-A&quantcastLabels=sport

• meta: With the meta option, you can pass arbitrary data into the Quantcast tracking event.  You can set this the same way you do labels.  Set the quantcastMeta query parameter to the value you want tracked for this option.  For example, to set the meta option to bar, reference the SWF like this:

http://mysite.com/QuantcastAnalyticsModule.swf?qacct=AA-1234-A&quantcastMeta=bar

Implementation

You can download and examine the source for the Quantcast Analytics SWF.  You can modify this source to customize the way that events are tracked into your Quantcast account. This zip file contains all required libraries and source files. Here is a summary of how this project was constructed:

1. Download the ActionScript 3 source file from Quantcast to track events.  You can download the source here.
2. Download the Brightcove Player API SWC from here.
3. In the document class for the component, import all of the required classes including the Quantcast library from step 1 as well as com.brightcove.api.CustomModule, which is the class that your document class extends.
4. In the initialize() method, grab a reference to the player modules you will need to reference (the VideoPlayerModule and ExperienceModule). In addition, register listeners for the VideoPlayerModule events that will trigger the firing of events into Quantcast.
5. As the VideoPlayerModule fires events to the QuantcastAnalyticsModule class, this class in turn maps and fires these events into Quantcast.

initialize() function: Getting a reference to the player modules

We take advantage of the Player API SWC by enabling the document class to extend the com.brightcove.api.CustomModule class. By extending this class, you just need to define the initialize() function which will be called automatically when the Brightcove player has been created, initialized and is ready to be interacted with. 

In the initialize() method, we capture references to the VideoPlayerModule and ExperienceModule. These references are stored on class instance variables. Additionally, a Quantcast object is constructed (which, as a side effect, will track an impression event).  Finally, event handlers are attached to the VideoPlayerModule to handle all of the events from the VideoPlayer that we care about. Here is what the complete initialize() method looks like:

override protected function initialize():void {
        // grab a reference to our player module event
        _experienceModule = player.getModule(APIModules.EXPERIENCE) as ExperienceModule;
        _videoPlayerModule = player.getModule(APIModules.VIDEO_PLAYER) as VideoPlayerModule;
        _contentModule = player.getModule(APIModules.CONTENT) as ContentModule;
         
        // track our 'impression' event
        _qc = new Quantcast(defaultQuantcastOptions(), this);
         
        // register our event listeners that we can map to Quantcast events
        _videoPlayerModule.addEventListener(MediaEvent.BEGIN, onBegin);
        _videoPlayerModule.addEventListener(MediaEvent.PROGRESS, onProgress);
        _videoPlayerModule.addEventListener(MediaEvent.STOP, onStop);
        _videoPlayerModule.addEventListener(MediaEvent.PLAY, onPlay);
        _videoPlayerModule.addEventListener(MediaEvent.SEEK, onSeek);
        _videoPlayerModule.addEventListener(MediaEvent.COMPLETE, onComplete);
        _videoPlayerModule.addEventListener(MediaEvent.CHANGE, onMediaChange);
      }

Firing events to Quantcast

Tracking events in Quantcast is just a matter of calling the appropriate function on the Quantcast object that was created in our initialize() function. From the example above, you can see that the Quantcast object is assigned to a class instance variable named _qc. Here are examples of calling the appropriate methods on the Quantcast object from the various event handlers on the VideoPlayerModule:

    internal function onBegin(evt:MediaEvent):void {
       _lastBeginEvent = new Date().getTime();
       _qc.played(quantcastOptionsWithMediaInfo(evt));
    } 
    internal function onProgress(evt:MediaEvent):void {
       _qc.progress(quantcastOptionsWithMediaAndTimeInfo(evt));       
    }     internal function onStop(evt:MediaEvent):void {
        _pauseCalled = true;
        _qc.paused(quantcastOptionsWithMediaInfo(evt));
    }