Analytics ActionScript 3.0 API
How does the analytics plug-in work?
Anvato Analytics module is implemented in ActionScript 3.0 and dynamically loaded by the Flash player. It listens to video, user engagement, and ad impression events silently and sends them to the Anvato Analytics server farm for processing. Since the plug-in sends data silently to your Anvato analytics account, you will not notice anything different about your player after it is installed.
Step 1: The plug-in gets loaded
As soon as the video player is loaded by the browser, the player will dynamically loads the plug-in from Anvato's plugin server (http://plugins.anvato.com/). You can use the Anvato open source plugin loader class that load plugins from anvato plugin site (download the sample example and anvato loader action script class ) This is a preferred method to make sure that player always loads most uptodate and smallest size of anlaytics plugin custumized for loading player.
import com.anvato.analytics.PluginLoader;
private var anvatoplugins:PluginLoader;
public var analytics:Object = null;
private function initPlayer():void{
LoadAnvatoPlugins(initVideo);
}
private function LoadAnvatoPlugins(callbackFunction:Function=null):void
{
try{
if (callbackFunction)
this.addEventListener('AnvatoPluginsReady',callbackFunction);
anvatoplugins = new PluginLoader();
anvatoplugins.addEventListener(PluginLoader.PLUGINS_READY, onAnvatoPluginsReady);
anvatoplugins.config['analytics'] = PluginLoader.OVP_PLAYER_2_2;
anvatoplugins.load();
}
catch(e:Error){
this.dispatchEvent(new Event('AnvatoPluginsReady'));
}
}
private function initVideo(e:Event=null):void {
playVideo();
}
Alternativly, Plugin can be loaded is using Adobe’s standard swfloader classes or any of your favorite swf loader class from Anvato's plugin site. In this case, you should load the plugin from http://plugins.anvato.com/1.5/as3/anvatoanalytics.swf and you sould set the type of your flash player during plugin-activation step using configration setting (e.g. analytics.config['type'] = 'ovp').
Step 2: The plug-in gets activated with initialize() API Call
After the plug-in is loaded and ready, the second step is to configure and activate the anlaytics plugin. Plugin is configured by setting necessary options and paremnetres using plugins config variable. Configuration is where you will tell plugin, tracker key, player url, and player name as well as any player-specific (e.g. netStream object) object that player will listen for AnalyticEvents.
Once configuration done, you need to activate the plugin. This is done by calling plug-in’s initialize() action script API call. Once the plugin activated, it is ready to send any analytic event to server if configuration is set correctly.
private function onAnvatoPluginsReady(e:Event):void{
if (anvatoplugins.plugins['analytics']){
analytics= anvatoplugins.plugins['analytics'].content;
if (analytics){
//configuring anlytic plugin
analytics.config['tracker'] = this.parameters['tracker'];
analytics.config['url'] = this.url;
analytics.config['name'] = 'my ovp player 2.2';
//active anlytic plugin
analytics.initialize();
//passing additional ui component to plugin to listen anlaytic events
analytics.listenComponent(this); // to listen any event dispatch by player
analytics.listenComponent(embedComp);
analytics.listenComponent(shareComp);
}
}
// let the player know the analytics plugin is initizliaed and ready to load
this.dispatchEvent(new Event('AnvatoPluginsReady'));
}
It is importent to load and activate the plugin before player starts playing video for completeness of the anlaytics events.
Step 3: The Video URL is set with onLoad() API Call
Once the video url is avaialable, you will use onLoad() api call to pass video-specific infromation such as video URL, video Title, video ID (if you have one for your CMS), video tags, and stream type. Video URL is key variable need to be set correctly. Any event that is going to be send to server will be associated that video_URL so onLoad() api should be called everytime the player will start playing a new video.
private function loadVideo():void{
.....
if (analytics)
analytics.onLoad(VideoURL,VideoTitle,VideoID,VideoTags,StreamType);
.....
}
Step 4 : Stream object are passed to plugin using addVideoStream() API call
Plugin listens to video events from stream or video object depens of the player type(e.g. netStream Flash, videoDisplay in Flex, OVPNetStream in OVP etc). AddVideoStream() api call allow you to pass video object to plugin for listeing video event whenever the videoobject is created. This will tell plugin to start listeing and reporting video events seemsly.
private function connectionReady(e:Event):void{
...........
_ns = new OvpNetStream(_nc);
if (analytics)
analytics.addVideoStream(_ns);
playVideo(..);
..........
}
Alternativly, you can configure the plugin to listen video object uising config varibale if the video/stream object has alrrady created and ready before the plugin is loaded. If the player play more than one video in a session, such as preroll, midroll or postroll in-video ads and main video. There are two function call that need to be used to differentiate main video event from ads event. Whenever the main video will be played or resumed, addVideoStream(netStreamObject) API call should be used, and whenever in video ads will be played, addAdStream(netStreamObject, ad_url,ad_id, ad_type) api call should be used. When the video ends, removeVideoStream() or removeAdStream() API call ised used.
Step 5 : The analytics events are dispatched with sendEvent() API call
By default, plugin listens all the video events generated by video/stream object. You do not need to do anything for these video events. However anvato anlaytcs plugin gives you flexiable to to send User engamenet venets, AD events or custom events to server. Why it is important, because this way you can distinuqish wther the user clik to pause video or player pause the video, or distinquish that user shared the video by email etc. In order to send the specifc User or Ad events to player, you have two option:
Using plugin's sendEvent() api call to send events to server
private function doPlayPause():void {
switch (bPlayPause.label){
case "PAUSE":
_ns.pause();
if (analytics)
analytics.sendEvent(com.anvato.analytics.AnalyticEvent.User_Pause,_ns.time.toString());
break;
case "PLAY":
bPlayPause.label = "PAUSE";
_ns.resume();
if (analytics)
analytics.sendEvent(com.anvato.analytics.AnalyticEvent.User_Play,_ns.time.toString())
break;
}
}
}
dispatching AnlayticsEvent from player or any oether UI component:
private function shareClicked():void{
var linkToCall:String = "http://www.facebook.com/share.php?u=www.anvato.com";
this.dispatchEvent(AnalyticEvent.event(AnalyticEvent.User_Share,'facebook:'+int(time).toString()));
navigateToURL(new URLRequest(linkToCall));
}
Special Cases for complex players:
How to handle if player plays both video and invideo ads using same video component
If the player play more than one video in a session, such as preroll, midroll or postroll in-video ads and main video. There are two function call that need to be used to differentiate main video event from ads event. Whenever the main video will be played or resumed, addVideoStream(netStreamObject) API call should be used, and whenever in video ads will be played, addAdStream(netStreamObject, ad_url,ad_id, ad_type) api call should be used. When the video ends, removeVideoStream() or removeAdStream() API call ised used.
How to handle if player plays video using http-seek
If the player uses http-seek instead of rtmp streaming or http downloading, onLoad() function must be call once the video starts, but addVideoStream() should be used subsequent seek operation. This will keep integrity of the analytics.
Analytics API:
initialize()
It initialize the plugin by setting player specific parameters. The paraters can be configured before the initialize() call. Note that, player parameters can be configured during initialize() call by creating a playerInfo object and pass it to plugin.
public function initialize(playerInfo:Object=null,componentList:Array=null):void
private function onAnvatoPluginsReady(e:Event):void{
ExternalInterface.call("displayAnalyticsLogs",'Plugin Load Delay: '+anvatoplugins.loadDelay.toString());
if (anvatoplugins.plugins['analytics']){
analytics= anvatoplugins.plugins['analytics'].content;
if (analytics){
analytics.config['type'] = 'ovp';
analytics.config['tracker'] = this.parameters['tracker'];
analytics.config['url'] = this.url;
analytics.config['name'] = 'my ovp player 2.2';
analytics.initialize();
//listen anlaytic events ui components
analytics.listenComponent(this);
analytics.listenComponent(embedComp);
analytics.listenComponent(shareComp);
analytics.onLoad(videoname,title,'my unique video id','my video tags','rtmp');
}
}
this.dispatchEvent(new Event('AnvatoPluginsReady'));
}
onLoad()
The onLoad() function must be called every time a new video is loaded. Video_URL is the primary key. Any events that is going to be dispatched after the onLoad() call will be associated the video_url that is provided and analytics will be collected around the video_url. It is important to provide the plugin with the full url, e.g. rtmp://c3737.edge.net/ondemand/test.flv. You can call onLoad() right after the initialize() call if the player plays single video or should be called whenecver a new video is loaded or going to be played.
public function onLoad(video_url:String,title:String,video_id:String=null, video_tags:String=null,streamType:String=null):void
sendEvent()
This function allows the player to send analytics events to the server. It is typically used to send specific User and Ads events to server, such as fullscreen on/off. Note that plugin listen and send all video event. It is important to distinquish user event from video event in to be accurate for user engagements and ad engagements statistics. Therefore all user events such as, play, pause, seek, fullscreen, share, email, or any other user events etc should be send to player using sendEvent() call when the user engage with the player.
public function sendEvent(type:String,data:String):void
private function doSeek():void {
_ns.seek(slider.value);
if (analytics)
analytics.sendEvent(com.anvato.analytics.AnalyticEvent.User_Seek,slider.value.toString());
}
addVideoStream()
If you use same video object based on NetStream or VideoDisplay/VideoClasses to play both video and invideo ads, addVideoStream() function must be called every time a main video starts (resumes in case midroll ads). This will tell the player how to make distinguish main video venets from ads events.
public function addVideoStream(video:Object):void
private function connectedHandler():void {
bPlayPause.enabled = true;
_ns = new OvpNetStream(_nc);
if (analytics){
if (adstream)
analytics.addAdStream(_ns,video[adname].url,video[adname].id,video[adname].type);
else
analytics.addVideoStream(_ns);
}
_ns.addEventListener(OvpEvent.NETSTREAM_PLAYSTATUS,streamPlayStatusHandler);
............
}
addAdStream(ad:NetStream, ad_url:String, ad_id:String, ad_type:String)
If you use same video object (netStream) to play both video and in-video ads, addAddStream() function must be called every time an in-video ad (preroll, postroll, midroll) starts This will tell the player how to make distinguish ad video events from main video events.
public function addAdStream(ns:Object,url:String=null,id:String=null,type:String=null):void
private function connectedHandler():void {
bPlayPause.enabled = true;
_ns = new OvpNetStream(_nc);
if (analytics){
if (adstream)
analytics.addAdStream(_ns,video[adname].url,video[adname].id,video[adname].type);
else
analytics.addVideoStream(_ns);
}
_ns.addEventListener(OvpEvent.NETSTREAM_PLAYSTATUS,streamPlayStatusHandler);
............
}
removeVideoStream()
If you use same video object (netStream) to play both video and invideo ads, removeVideoStream() function must be called every time a main video completes or stops by player to insert midroll/postroll invideo ads
public function removeVideoStream(ns:Object = null):void
removeAdStream()
If you use same video object (netStream) to play both video and in video ads, removeAdStream() function must be called every time an in-video ads completes or canceled by player.
public function removeAdStream(ns:Object = null):void
listenComponent(component:Object)
If the player has user interaction classes or plugins (such as embed component/plugin, etc), you can add these elements to the analytics modules for event capture. The component/plugin can be any type of display object which implements following methods: addEventListner() and removeEventListener(). The Analytics Object will access these two methods in order to listen for trackable events.
public function listenComponent(c:Object):void
Events
- Video_Load
- Video_Start
- Video_Complete
- Video_Metadata
- Video_Stop
- Video_Pause
- Video_Resume
- Video_Seek
- Video_Rewind
- Video_Error
- Video_View
- Video_Custom
Events are mapped to statistics computed in servers and displayed on web interface. It is recommended that use appropriate event name and associated data to make your analytics complete. Make sure that the plugin activated and onLoad() function is called before sending any events. When the plugin loaded and activated, it sends plugin_load events to server and creates necessary tracking parameters.
The player uses sendEvent() API function to send analytics events to the server. It is typically used to send specific User and Ads events to server, such as fullscreen on/off. Note that plugin listen and send all video event. It is important to distinquish user event from video event in to be accurate for user engagements and ad engagements statistics. Therefore all user events such as, play, pause, seek, fullscreen, share, email, or any other user events etc should be send to player using sendEvent() call when the user engage with the player.
private function doSeek():void {
_ns.seek(slider.value);
if (analytics)
analytics.sendEvent(AnalyticEvent.User_Seek,sliderValue);
}
Video Events:
Analytics plugin listens and sends standard video events to server once it is activated and video object is set (e.g netStream Object). You do not need to send any video events to server as the plugin takes care of it. Here is the list of video events that plugin listens and send it to server.Video_Load
Video_Start
Video_Metadata
Video_Complete
Video_Stop
Video_Pause
Video_Resume
Video_Seek
Video_Rewind
Video_Error
Video_ViewUpdate
User Events:
User Engagement Events: Plugin can listen user engagements event if the appropriate component or player it self are pass to plugin for listening. For example if you have component that takes care of video controls buttons, you can pass this component to plugin for listening using listenComponent() API call and you can send a User_Play events using sendEvent() api call whenever user plat button is pressed etc. User engagements events provide statistics about how users interact with video and player during the session.
User_Play
User_Replay
User_Pause
User_Seek
User_Stop
User_Embed
User_Menu
User_FullscreenOn
User_FullscreenOff
User_Video
User_Volume
User_Unmute
Ads Events:
Video Ads Analytics Events: If your player capable to server in-stream ads, you can send ads related events to server. Make sure that the plugin activated and onLoad() function is called before sending any events.
Ad_Load
Ad_Start
Ad_Complete
Ad_Metadata
Ad_PercentComplete
Ad_Resume
Ad_Rewind
Ad_Seek
Ad_Stop
Ad_Mute
Ad_Unmute
Ad_Rate
Ad_Cancel
Ad_Error