Robots Rule | MindSculpt.net

New media has met its match.

The MindSculpt Design Syndicate focuses on code that works, from CSS, XHTML and JavaScript tips and tutorials to Flash and ActionScript how-to's. Robots not included.

Category: Analytics


Omniture implementation, tagging and troubleshooting in Flash

October 25th, 2009 — 10:07am

The following assumes you have downloaded and installed the latest ActionSource component from Omniture. This is a quick setup and troubleshooting guide; please refer to your Omniture documentation for more in-depth tracking procedures and options.

If you’ve stumbled upon this article, you’re one of the many frustrated Flash developers starving for insight into the mysterious, alternate reality that is Omniture tagging implementation.

The truth is this: It’s all one big misunderstanding.

Now I must admit I was once a subscriber to the belief that Omni tagging was a daunting task. There’s nothing mysterious, harrowing or even mythological about adding Omniture tags to your Flash project. If you possess intermediate ActionScript programming knowledge, Omniture implementation in Flash AS2 or AS3 is amazingly simple.

Importing the component: AS2 and AS3
Add 2 new layers to the top of your AS2 or AS3 file above any previous code layers. Make sure to label them (labeling and file organization is a design and programming fundamental, but I am confident you are already labeling your layers and commenting your code, right?). Open Flash’s Components Inspector (or copy and paste the component from another Flash file) and drag or copy/paste the component into the named layer in your timeline.

Figure 1. Place your Omniture code at the top of your file. Keep the code and component on separate layers as a best practice.

Figure 1. Place your Omniture code at the top of your file. Keep the code and component on separate layers as a best practice.

If your file uses more than one frame, the layers containing the Omniture component and ActionScript code must span the length of the movie:

Figure 2. A common mistake is not extending the frames containing the Omniture component and config code the length of your movie.

Figure 2. A common mistake is not extending the frames containing the Omniture component and config code the length of your movie.

Lastly, select the Omniture component on the stage and give it an instance name of s. Without an instance name, the config code we’ll be adding to the stage in the next section will not run.

Instantiating the ActionSource Component
AS2: Add the following code to the AS: Omniture layer of your file:

  1. function configActionSource() {
  2. /* Specify the Report Suite ID(s) to track here */
  3.    s.account = "your_account";
  4. /* You may add or alter any code config here */
  5.    s.pageName = "test_movie";
  6.    s.pageURL = "";
  7.    s.charSet = "ISO-8859-1";
  8.    s.currencyCode = "USD";
  9. /* Turn on and configure ClickMap tracking here */
  10.    s.trackClickMap = true;
  11.    s.movieID = "";
  12. /* Turn on and configure debugging here */
  13.    s.debugTracking = true;
  14.    s.trackLocal = true;
  15. /* WARNING: Changing any of the below variables will cause drastic changes to how your visitor data is collected. Changes should only be made when instructed to do so by your account manager.*/
  16.    s.visitorNamespace = "your_visitor_namespace";
  17.    // Identifies the Omniture data center ›› do not change this value unless so instructed by your Omniture  representative
  18.    s.dc = "122";
  19. }
  20. // now configure the component
  21. configActionSource();

AS3: Add the following code to the AS: Omniture layer of your file:

  1. import com.omniture.ActionSource;
  2. // create a reference to the ActionSource component
  3. var s:ActionSource;
  4. function configActionSource() {
  5.    // instantiate the ActionSource component
  6.    s = new ActionSource();
  7. /* Specify the Report Suite ID(s) to track here */
  8.    s.account = "your_account";
  9. /* You may add or alter any code config here */
  10.    s.pageName = "test_movie";
  11.    s.pageURL = "";
  12.    s.charSet = "ISO-8859-1";
  13.    s.currencyCode = "USD";
  14. /* Turn on and configure ClickMap tracking here */
  15.    s.trackClickMap = true;
  16.    s.movieID = "";
  17. /* Turn on and configure debugging here */
  18.    s.debugTracking = true;
  19.    s.trackLocal = true;
  20. /* WARNING: Changing any of the below variables will cause drastic changes to how your visitor data is collected.  Changes should only be made when instructed to do so by your account manager.*/
  21.    s.visitorNamespace = "your_visitor_namespace";
  22.    // Identifies the Omniture data center.  Do not change this value unless so instructed by your Omniture representative.
  23.    s.dc = "122";
  24.    // add the component to the display list
  25.    addChild(s);
  26. }
  27. // now configure the component
  28. configActionSource();

Your ActionSource component is now instantiated and ready to receive tracking calls from events within your project. Make sure you replace the generic values for s.account, < code >s.pageName and < code >s.visitorNamespace with the values given to you by your analytics team lead.

Setting up your tracking functions (AS2 and AS3)
Now it’s time to set up some functions to handle your tracking events. Select the AS: Omniture layer in your document and add the following:

  1. // function to reset all data stored in the component after each tracking call
  2. function clearOmniTags():Void {
  3.    // set a generic number reference
  4.    var i:Number;
  5.    // for…in conditional runs through all of the variables and clears them
  6.    for (i in s)   {
  7.       // set a temp var to hold the value found at each index
  8.       var varString:String = i.toString();
  9.       if (varString.indexOf("eVar") == 0) {
  10.          s[i] = "";
  11.       }
  12.       if (varString.indexOf("event") == 0)  {
  13.          s[i] = "";
  14.       }
  15.       if (varString.indexOf("prop") == 0) {
  16.          s[i] = "";
  17.       }
  18.       if (varString.indexOf("pageName") == 0) {
  19.          s[i] = "";
  20.       }
  21.    }
  22. }
  23. // example of a dynamic function to handle calls from anywhere in your application
  24. function setOmniTags(myEventNumber:Number):Void {
  25.    // eVar1 through eVar50 values are supplied by the analytics team
  26.    s.eVar1 = "Button Clicked";
  27.    // dynamically set the s.events value based on the value of myEventNumber
  28.    s.events = myEventNumber;
  29.    // send tracking info to the component
  30.    s.track();
  31.    // now that we’ve made the tracking call, reset and clear all tags
  32.    clearOmniTags();
  33. }

The first function, clearOmniTags(), resets the variables in the ActionSource component. This function should be called immediately after every tracking call, otherwise duplicate values could be set and sent for reporting, which will leave you with a confused and angry analytics team.

The second function, setOmniTags(), is an example of a dynamic function that takes an event as a parameter from anywhere in your application, then makes the tracking call. There are countless ways to configure this type of dynamic function; this workflow example should spark some thought about the best way to handle tracking for your current project. Now that you have these functions set up, here’s an example of how you could make a tracking call:

AS2 example:

  1. myButton.onRelease = function():Void {
  2.    // call the master tracking function and pass it your event
  3.    setOmniTags(event20);
  4. };

AS3 example:

  1. // add an event listener
  2. // advanced users can configure the setOmniTags() function to directly accept this event and skip the setTags() event handler function below
  3. myButton.addEventListener(MouseEvent.CLICK, setTags, false, 0, false);
  4. // event handler function receives CLICK event
  5. function setTags(evt:MouseEvent):void
  6. {
  7.    // call the master tracking function and pass it your event
  8.    setOmniTags(event20);
  9. }

There are numerous tracking calls that can be made to the component after Omniture variables have been set by the user; I won’t go through them all since they are listed in the Omniture documentation manuals. This basic approach should help you get through most of the setup process, and give you some food for thought on different ways to approach tracking in your application.

How can I see if calls are being made?
Many calls can be tested locally through Flash’s output panel. You’ll see a long string of tracking code fire off every time one of your events is triggered.

Regardless of whether or not your tags are firing locally, it is imperative for them to be tested in a live staging environment to ensure the tags are firing correctly remotely as well. The most popular programs for Flash tracing are Flash Tracer and Firebug, both of which are Firefox plugins. There are other programs out there, however I find that both of these do the trick nicely.

“Why the F*** don’t I see the calls?”
So you’ve considered my approach, tried my examples and have taken my name in vain several times. That’s not very nice. Let’s step back, take a deep breath, and start from the beginning.

Troubleshooting in Flash is an art form. It’s also an essential skill to master in order to become a proficient programmer. After spending countless hours troubleshooting Omni tags in Flash, I’ve compiled the most common errors that can be easily overlooked.

  • Double check that you have the latest version of the Omniture component. Delete it from the stage and your libray, then re-import it…
  • …now make sure you’ve given the component the instance name s.
  • Make sure the layers your component and the config code are on span the entire length of your timeline (see fig. 2 above).
  • The config variable, s.account must have a value for the ActionSource to receive tracking calls. If you are using a FlashVar to pull in the value for s.account, it is possible that configActionSource() gets called before the HTML page where your application is embedded has loaded in the FlashVar. You can fix this one of two ways: move your Omniture layers below the rest of your code, or set up some sort of initial function that gets called after your Flash app has loaded, and call configActionSource() at the end of that function. A quick way to test this is to comment out the current value for s.account and assign it any test string value.
  • Triple-check your ActionScript syntax and make sure your functions are all named and spelled correctly
  • Still having trouble? Step away from the desk for a while and come back to it in an hour. You’ve probably overlooked something very simple, perhaps one of the items covered in this article.

Please be aware that this article details what I’ve found to be successful when using Omniture. Your results and needs will differ from these generic examples, and you should always have an Omniture representative confirm the tagging calls are set up and functioning correctly before your application goes live. The purpose of this article is to shed light on so often misunderstood Omniture tagging implementation. Hopefully this article will help developers (and other related industry disciplines) save valuable time and effort adding Omniture tags to their Flash projects.

Share this post:
  • Twitter
  • Facebook
  • del.icio.us
  • Digg
  • LinkedIn
  • Reddit
  • StumbleUpon
  • Technorati
  • Google Bookmarks
  • Yahoo! Buzz

3 comments » | Analytics, Flash AS2, Flash AS3, Omniture in Flash

     

↑ Back to top