Advertisement

Integrating "Use It Better" Analytics with a Flash Website

by

This Cyber Monday Tuts+ courses will be reduced to just $3 (usually $15). Don't miss out.

Learn how you can analyze user experience and performance of Flash websites with Use It Better analytics. This tutorial will show you how to integrate analytics framework with a Demo Site to record users' visits and - with some magic - play them back as if they were videotaped!

Use It Better analytics isn't restricted to examining traffic for full Flash websites, but can be equally valuable during usability testing or measuring RIA metrics. Let's dive in..


Final Result Preview

Let's take a look at the final result we will be working towards. Click the image below to replay a sample visit to a demo site, recorded earlier with Use It Better:

Sample visit recording made with Use It Better analytics for Flash

If you want to record and play back your own visit, then click here to visit the demo site itself, then log in to the analytics panel using:

  • project: activetuts
  • password: activetuts

In the Visits tab, find yours, and click Play.


Getting Started

For the purpose of this tutorial we will use a Basic plan of Use It Better, but the integration process is the same for a Free plan.

After you download and unzip the source package you will see that there are two folders inside. Both contain sources of the same website. During the tutorial we will work on sources from Demo Site folder. If you would like to preview what we are going to achieve, check Demo Site - Final Result folder which contains sources that have already been integrated with Use It Better.

Inside each folder you will find a src folder containing *.as and *.fla files, and a bin-debug folder with all the files required to publish the website - *.swf, *.html and so on.

If you would like to learn more on any issue that I cover in the tutorial you should check the Use It Better wiki


Step 1: Download Use It Better Framework for Your Project

To save your time, I have already downloaded Use It Better framework classes and placed them in Demo Site/src/com/ directory of tutorial's source package. There is also adobe package in com directory containing some useful libraries used by and distributed with the framework.

Tutorial's source package structure

In real-case scenario, after you sign up for your own Use It Better plan (either free or paid) you will need to download framework from analytics panel where it can be found in the right column of the Settings section.


Step 2: Initialize Use It Better

First of all open UIBDemo.fla and the project's main class UIBDemo.as in which you will need to initialize Use It Better.

Start with importing the main class of the framework, uDash:

package
{
  import com.useitbetter.uDash; // core Use It Better class
  
  // ... the rest of the package body

Find init function which is executed when the main movie is added to stage. Initialize uDash by adding the following line of code:

private function init(e:Event) : void
{
  stage.addChild( uDash.init() ); // initialize and add to stage
  
  // … the rest of the function body
}

Step 3: Record Your First Visit

Save the edited file and test UIBdemo.fla (Ctrl+Enter). The website will look the same as before but you will notice a new message in the output window:

u MESSAGE: Welcome to uDash! Your version is "uDash AS3 1.0". Enjoy developing!
u MESSAGE: uDash connection to socket server 59873.s.useitbetter.com:59873 OK. Validating Connection...
u MESSAGE: uDash connection to socket server 59873.s.useitbetter.com:59873 is valid.

This means, that the website has established a connection with the Use It Better servers and is now recording your activity.

Try to navigate around the website - fill in and send the contact form, play with the car. We'll try to replay this visit in the next step to see if recording worked fine.


Step 4: Find Your Visit in Analytics Panel

If you haven't already, it's high time to visit http://panel.useitbetter.com and log in to the project using following credentials:

  • project: activetuts
  • password: activetuts

Once you log in you will see Activity Report but I recommend that you switch to Visits tab. In the left column you will see all recorded visits sorted by time - your recently recorded visit will be at the top.

Important: keep in mind that you are not the only one using this tutorial and there might be several other visits recorded.

On the right of the page you can see visit's details. Click Play button to replay the visit.


Step 5: Try Replaying the Visit in Flash IDE

Once you click Play button a new page opens with instructions how to replay a visit recorded in Flash IDE. Just copy a replay command, comment your original init, and paste one from your clipboard underneath:

// stage.addChild( uDash.init() ); // initialize and add to stage
stage.addChild( uDash.init('uTestSessionUrl@@http://panel.useitbetter.com/play/691d7f123f5d9780e613223e67ee8a22/ses/c5a72002ab439aaba2f9189718833035||uTimezoneOffset@@-120||uLocalDateTime@@Sun May 15 19:57:29 GMT+0200 2011||uSessionDateTime@@2011-05-15 18:57:30||uApiUrl@@http://api.useitbetter.com/||uSessionHash@@c5a72002ab439aaba2f9189718833035||uProjectHash@@691d7f123f5d9780e613223e67ee8a22') )

Now save your AS file and test the Flash movie again to see the replay.


Step 6: Customize Website Code for Accurate Visits Replay

Well, wasn't it magic? You could see your mouse movement, clicks and even key strokes from the recorded visit. And you made it with just two lines of code!

However, rotating the car didn't work at all. But don't worry. All we have to do is just make some little tweaks which I will cover in the next steps. But before you move forward, remove the replay init and uncommment the orignal one:

stage.addChild( uDash.init() ); // initialize and add to stage

Otherwise you would see the replay again.


Step 7: Manually Record Events That Were not Recorded

As you could see, all your interactions with the website using mouse and keyboard were recorded automatically. However, all listeners added to the stage object have to be recorded manually.

There is one such listener in CarInfo.as from Demo Site\src\core\sections\car folder. Check the line no. 272:

UIBDemo.instance.stage.addEventListener( MouseEvent.MOUSE_UP, stageMouseUpHandler );

Start with adding the import instruction:

package core.sections.car
{
  import caurina.transitions.Tweener;
  import caurina.transitions.properties.DisplayShortcuts;
  
  import com.useitbetter.uDash;

Now find the stageMouseUpHandler function which is triggered by MOUSE_UP event. It is responsible for turning off car rotation after user releases mouse button. Use recordMe method to record it manually:

private function stageMouseUpHandler( e:MouseEvent ) : void
{
	uDash.recorder.recordMe(e); // records this event
	this.removeEventListener( Event.ENTER_FRAME, thisEnterFrameHandler );
}

Step 8: Map Mouse Position During the Replay

Another thing you have to change is the code responsible for the 360 degrees view of the car. The car rotation depends on mouse position and of course you would like it to follow visitor's mouse and not yours during the replay.

Search for mouseX in CarInfo.as and replace all its occurrences (there are six of them) with uMouseX(), just like here:

lastX = carHolder.uMouseX() // mapping cursor position

It's completely safe - uMouseX() method returns real mouse position during the recording but a visitor's mouse during replay.

HINT: When you integrate a large project consider using a code editor which supports multi-file search (e.g. FlashDevelop). It will help you find all occurences in your project


Step 9: Synchronize Replay with Assets Preloading

There is just one preloaded asset in the Demo Site and that's the car. If you have a slower Internet connection than a visitor, whose visit you are replaying, the car will load with a delay. In most cases you wouldn't even notice the difference, but for the sake of this tutorial I will show you how to use checkpoints to perfectly synchronize replay.

In CarInfo.as, find the onCarLoadCompleteHandler() function which is triggered by COMPLETE event once the car preloading is done. Add a checkpoint to make sure that replay will wait until the car is loaded.

private function onCarLoadCompleteHandler( e:Event ) : void
{
  uDash.checkpoints.place("car loaded"); // checkpoint added to synchronize replay with preloading
  
  // the rest of the function body

HINT: Checkpoints are useful for synchronizing all time related events such as animations.


Step 10: Test the Replay Again

Now go through Steps 3-5 again to test recording and replaying a visit - the replay should look exactly as you recorded it. If it does - let's move forward!


Step 11: Record Meta Information for Advanced Analytics

Use It Better is more than just about replaying visits. In fact, it has some powerful analytics reports to work both on individual visits and aggregated data. In the next steps you will learn how to record important meta events: Sections and Actions which will feed these reports.

Note: If you are interested only in replaying visits you can skip to Step 14.


Step 12: Record Visited Sections With SWFAddress Integration

Let's start with the most important thing - recording which sections of the website are visited. It will enable Paths Report as well as many other functionalities across the analytics panel.

The Demo Site is using SWFAddress for deep-linking and Use It Better can automaticaly record the part of an URL after # as a section. I.e. visiting such URL:

http://mywebsite.com/#/car

would be recorded as a visit to the car section.

Open again the main project class UIBDemo.as located in Demo Site\src folder. Search for the initSWFAddress() function and initialize SWFAddress support before listening for the CHANGE event:

private function initSWFAddress() : void
{
  uSWFAddress.init(); 
  SWFAddress.setHistory( true );
  SWFAddress.addEventListener( SWFAddressEvent.CHANGE, swfAddressChangeListener );
}

Oh, and don't forget to import Use It Better module responsible for integration with SWFAddress:

package
{
  import com.useitbetter.uDash; // core Use It Better class
  import com.useitbetter.modules.uSWFAddress; // module responsible for integration with SWFAddress
  
  // ... the rest of the package body

Note: If the website doesn't have SWFAddress you can still record sections manually.


Step 13: Record Desired Actions to Measure Site's Conversion

There are certain desired Actions that visitors can perform on the Demo Site which would make the site-owner happy. For example: submitting a contact form. Let's record it.

Open ContactInfo.as from Demo Site\src\core\sections\contact folder. As always, start with the import:

 
import com.useitbetter.uDash; // core Use It Better class

Now find messageSent function which is called upon successfully submitted form and add the Action:

private function messageSent() : void
{
  uDash.recorder.saveMeta(uDash.metaevents.ACTION, "User submitted form");

  // the rest of the function body

Actions are an important part of all Use It Better Reports and they are one of the key performance indicators (KPI) which will help you evaluate your website.

HINT: You can record as many actions as you want but try to be reasonable - not every action is equally desired.


Step 14: Enable Recording and Replaying of Browser Window Resizing

OK, now there's the last but very important thing. Demo Site was embedded on HTML page using SWFObject to fit 100% of browser window. This means that the movie size will be different in different screen resolutions and can be changed during a visit by resizing the browser window. We have to record it.

Go to Demo Site\bin-debug folder where you can find index.html. Open it with a text editor and look for an id of an HTML object that contains our Flash movie. Sounds difficult but it's easy to find:

swfobject.embedSWF("UIBDemo.swf", "UIBDemo", "100%", "100%", "9", "expressInstall.swf", flashvars, params, attributes);

See the second argument passed to embedSWF? UIBDemo? That's what we were looking for!

HINT: Usually, if you export HTML from Flash IDE, the id is the same as SWF file name.

Now get back to Flash to UIBDemo.as. Press Ctrl+F and find uDash.init(). Declare a reference to HTML object before it:

private function init(e:Event) : void
{
  uDash.settings.uHtmlFlashObjectId = "UIBDemo"; // reference to HTML object containing SWF movie in index.html		
  stage.addChild( uDash.init() ); // initialize and add to stage
  
  // the rest of the function body
}

Step 15: Publish Your Website to a Server (or a localhost)

Now we're done. No more coding. All you need to do now is export the Flash movie and publish all files from Demo Site\bin-debug folder to a server (or a local host) where you could test it in a browser.


Step 16: Test Recording and Replaying a Visit in a Browser

Open the website in a browser, fool around, try resizing the browser. Once you're done, close the website and check the Visits Report in the analytics panel. Find your visit on the list and replay it to make sure that everything works fine.


The End

That's it! Working on a website's code that you haven't written by yourself is difficult but I hope you found this tutorial interesting. There is a huge potential in Use It Better and you can leverage replaying visits not just to improve usability and user experience but also to measure campaigns performance or even detect who's cheating in your Flash game.

Even though the Demo Site is quite simple I think that you will be able to integrate with Use It Better your own website no matter how big it is.

Advertisement