ActionScript3 Tracker - OXYGEN-MARKET/oxygen-market.github.io GitHub Wiki

HOME » SNOWPLOW TECHNICAL DOCUMENTATION » Trackers » Actionscript 3 (AS3) Tracker

• 1 Overview
• 2 Initialization
  • 2.1 Importing the module
  • 2.2 Creating a tracker
    • 2.2.1 emitter
    • 2.2.2 subject
    • 2.2.3 namespace
    • 2.2.4 appId
    • 2.2.5 base64Encoded
    • 2.2.6 setPlatform
• 3 Adding extra data: the Subject class
  • 3.2 setUserId
  • 3.3 setScreenResolution
  • 3.4 setViewport
  • 3.5 setColorDepth
  • 3.6 setTimezone
  • 3.7 setLanguage
• 4 Tracking specific events
  • 4.1 Common
    • 4.1.1 Custom contexts
    • 4.1.2 Optional timestamp argument
    • 4.1.3 Tracker method return values
  • 4.2 trackPageView()
  • 4.3 trackScreenView()
  • 4.4 trackEcommerceTransaction()
    • 4.4.1 TransactionItem
  • 4.5 trackStructuredEvent()
  • 4.6 trackUnstructuredEvent()
• 5 Sending event: Emitter
  • 5.1 Using a buffer
  • 5.2 Choosing the HTTP method
  • 5.3 Method of sending HTTP requests
  • 5.4 Emitter callback
• 6 Payload
  • 6.1 Tracker Payload
  • 6.2 Schema Payload

The Snowplow Actionscript 3 (AS3) Tracker allows you to track Snowplow events from a Flash movie, Flex application or Adobe AIR application.

The tracker should be straightforward to use if you are comfortable with AS3 development.

Back to top

Assuming you have completed the Actionscript 3 Tracker Setup for your project, you are now ready to initialize the AS3 Tracker.

Import the AS3 Tracker's classes into your AS3 code like so:

import com.snowplowanalytics.snowplow.tracker.*;
import com.snowplowanalytics.snowplow.tracker.emitter.*;
import com.snowplowanalytics.snowplow.tracker.payload.*;

That's it - you are now ready to initialize a Tracker instance.

Back to top

To instantiate a tracker in your code simply instantiate the Tracker interface:

Tracker(emitter:Emitter, namespace:String, appId:String, subject:Subject, stage:Stage = null, base64Encoded:Boolean = true)

For example:

var t1:Tracker = new Tracker(emitter, "AF003", "cf", user1Subject, this.stage, true);

The emitter to which the tracker will send events. See Emitters for more on emitter configuration.

The user which the Tracker will track. This should be an instance of the Subject class. You don't need to set this during Tracker construction; you can use the Tracker.setSubject method afterwards. In fact, you don't need to create a subject at all. If you don't, though, your events won't contain user-specific data such as timezone and language.

If provided, the namespace argument will be attached to every event fired by the new tracker. This allows you to later identify which tracker fired which event if you have multiple trackers running.

The appId argument lets you set the application ID to any string.

By default, unstructured events and custom contexts are encoded into Base64 to ensure that no data is lost or corrupted. You can turn encoding on or off using the Boolean base64Encoded argument.

Back to top

You can change the platform by calling:

tracker.setPlatform("cnsl");

For a full list of supported platforms, please see the Snowplow Tracker Protocol.

Back to top

You may have additional information about your application's environment, current user and so on, which you want to send to Snowplow with each event.

The Subject class has a set of set...() methods to attach extra data relating to the user to all tracked events:

• setUserId
• setScreenResolution
• setViewport
• setColorDepth
• setTimezone
• setLanguage

Here are some examples:

s1.setUserID("Kevin Gleason");
s1.setLanguage("en-gb");
s1.setScreenResolution(1920, 1080);

After that, you can add your Subject to your Tracker like so:

Tracker(emitter, namespace, appId, s1);
// OR
t1.setSubject(s1);

Back to top

You can set the user ID to any string:

s1.setUserId( "{{USER ID}}" )

Example:

s1.setUserId("alexd")

Back to top

If you wish to track the device's screen resolution, then you can pass this in to Snowplow too:

t1.setScreenResolution( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

t1.setScreenResolution(1366, 768)

You can get these values by referencing flash.system.Capabilities.screenResolutionX and flash.system.Capabilities.screenResolutionY, although they will only reflect the dimensions of the main screen.

Alternatively, if your AS3 code has script access via ExternalInterface, you can use Javascript to query these values from the browser or another player context.

Back to top

If your AS3 code has access to the viewport dimensions (by calling Javascript code through ExternalInterface), then you can pass this in to Snowplow too:

s.setViewport( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

s.setViewport(300, 200)

Back to top

If your AS3 code has access to the bit depth of the device's color palette for displaying images (by calling Javascript's screen.colorDepth via ExternalInterface), then you can pass this in to Snowplow too:

s.setColorDepth( {{BITS PER PIXEL}} )

The number should be a positive integer, in bits per pixel. Example:

s.setColorDepth(32)

Back to top

This method lets you pass a user's timezone in to Snowplow:

s.setTimezone( {{TIMEZONE}} )

The timezone should be a string:

s.setTimezone("Europe/London")

Back to top

This method lets you pass a user's language in to Snowplow:

s.setLanguage( {{LANGUAGE}} )

The language should be a string:

s.setLanguage('en')

Back to top

Snowplow has been built to enable you to track a wide range of events that occur when users interact with your Flash apps. We are constantly growing the range of functions available in order to capture that data more richly.

Tracking methods supported by the AS3 Tracker at a glance:

Back to top

All events are tracked with specific methods on the tracker instance, of the form trackXXX(), where XXX is the name of the event to track.

Back to top

In short, custom contexts let you add additional information about the circumstances surrounding an event in the form of an Object. Each tracking method accepts an additional optional contexts parameter after all the parameters specific to that method:

t1.trackScreenView(name:String, id:String, context:Array, timestamp:Number);

The context argument should consist of a Array of SchemaPayload representing an array of one or more contexts. The format of each individual context element is the same as for an unstructured event.

If a visitor arrives on a page advertising a movie, the context dictionary might look like this:

{
  "schema": "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
  "data": {
    "movie_name": "Solaris",
    "poster_country": "JP",
    "poster_year": "1978"
  }
}

Note that even if there is only one custom context attached to the event, it still needs to be placed in an Array.

Back to top

In all the trackers, we offer a way to set the timestamp if you want the event to show as tracked at a specific time. If you don't, we create a timestamp while the event is being tracked.

Here is an example:

t1.trackScreenView("HUD > Save Game", "screen23", contextList, 123456789);

Back to top

To be confirmed. As of now, trackers do not return anything.

Back to top

Use trackPageView() to track a user viewing a screen within your Flash app, in the case where the screen behaves like a web page and has its own unique URL that appears in the browser's address bar. Arguments are:

Example:

tracker.trackPageView("www.mysite.com#page3", "Page Three", "www.me.com", contextList);

In Flash, the more common case is to use trackScreenView.

Back to top

Use trackScreenView() to track a user viewing a screen (or equivalent) within your app. Arguments are:

Example:

t1.trackScreenView("HUD > Save Game", "screen23", contextList, 123456);

Back to top

Use trackEcommerceTransaction() to track an ecommerce transaction.

Arguments:

The items argument is a List of individual TransactionItem elements representing the items in the e-commerce transaction. Note that trackEcommerceTransaction fires multiple events: one transaction event for the transaction as a whole, and one transaction item event for each element of the items List. Each transaction item event will have the same timestamp, order_id, and currency as the main transaction event.

Back to top

To instantiate a TransactionItem in your code, simply use the following constructor signature:

trackEcommerceTransactionItem(order_id:String, sku:String, price:Number, quantity:int, name:String, category:String, currency:String, context:Array, timestamp:Number)

These are the fields that can appear as elements in each TransactionItem element of the transaction item Array:

Example of tracking a transaction containing two items:

// Example to come, in the meantime here is the type signature:
t1.trackEcommerceTransaction(order_id:String, total_value:Number, affiliation:String, tax_value:Number, shipping:Number, city:String, state:String, country:String, currency:String, items:Array, context:Array = null, timestamp:Number = 0);
t1.trackEcommerceTransaction("6a8078be", 300, "my_affiliate", 30, 10, "Boston", "Massachusetts", "USA", "USD", items, context);

Back to top

Use trackStructuredEvent() to track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required):

Example:

t1.trackStructuredEvent(category:String, action:String, label:String, property:String, value:int, context:Array = null, timestamp:Number = 0);

Back to top

Custom unstructured events are a flexible tool that enables Snowplow users to define their own event types and send them into Snowplow.

When a user sends in a custom unstructured event, they do so as a JSON of name-value properties, that conforms to a JSON schema defined for the event earlier.

Use trackUnstructuredEvent() to track a custom event which consists of a name and an unstructured set of properties. This is useful when:

• You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
• You want to track events which have unpredictable or frequently changing properties

The arguments are as follows:

Example:

t1.trackUnstructuredEvent(eventData, contextList);

For more on JSON schema, see the [blog post][self-describing-jsons].

Back to top

Events are sent using an Emitter class. You can initialize a class with a collector endpoint URL and optionally choose the HTTP POST method instead of GET.

Emitter(uri:string, httpMethod:String)

For example:

var e1:Emitter = new Emitter("d3rkrsqld9gmqf.cloudfront.net");
var e2:Emitter = new Emitter("d3rkrsqld9gmqf.cloudfront.net", URLRequestMethod.POST);

A buffer is used to group events together in bulk before sending them. This is useful to reduce network usage. By default, the AS3 Emitter does not buffer but instead sends events instantly as soon as they are created. You can use a buffer instead by calling setBufferOption with the number of events to batch together in the buffer:

var e1:Emitter = new Emitter("d3rkrsqld9gmqf.cloudfront.net");
e1.setBufferOption(BufferOption.BATCH);

There are two predefined constants but you can use any integer value:

Back to top

Snowplow supports receiving events via GET and POST requests. In a GET request, each event is sent in an individual request. With POST requests, events are bundled together in one request.

You can set the HTTP method in the Emitter constructor:

var e1:Emitter = new Emitter("d3rkrsqld9gmqf.cloudfront.net", URLRequestMethod.POST);

The default method is GET.

Actionscript provides standard constants for the two options in the URLRequestMethod class:

URLRequestMethod.GET URLRequestMethod.POST

Back to top

An AS3 Emitter sends requests asynchronously. Flash does not support synchronous requests.

Back to top

The AS3 Emitter dispatches events when it succeeds or fails to flush the buffer.

You can register event listeners for these events if you need to handle the success or failure case. Here is a sample bit of code to show how it could work:

var emitter:Emitter = new Emitter(testURL);
emitter.addEventListener(EmitterEvent.SUCCESS, function(bufferLength:int) {
    trace("Buffer length for POST/GET:" + bufferLength);
  }
);
emitter.addEventListener(EmitterEvent.FAILURE, function (successCount:int, failedEvents:Array, errorString:String) {
    trace("Failure, successCount: " + successCount + "\nfailedEvents:\n" + failedEvents.toString() + "\nerror:\n" + errorString:String);
  }
);

In the example, we can see in-line handling of the both cases. If events are all successfully sent, the success callback method receives the number of successful events sent. If there were any failures, the failure callback method receives the number of successful events sent (if any) and a Array of events that failed to be sent (i.e. the HTTP state code did not return 200). In addition, in the case of failure, an additional parameter is provided with the text of the network or security error that caused the failure.

Back to top

A Payload interface is used for implementing a TrackerPayload and SchemaPayload, but accordingly, can be used to implement your own Payload class if you choose.

Back to top

A TrackerPayload is used internally within the AS3 Tracker to create the tracking event payloads that are passed to an Emitter to be sent accordingly.

Back to top

A SchemaPayload is used primarily as a wrapper around a TrackerPayload. After creating a TrackerPayload, you create a SchemaPayload and use setData with the Payload, followed by, setSchema to set the schema that the payload will be used against.

This is mainly used under the hood, in the Tracker class but is useful to know if you want to create your own Tracker class.

Here's a short example:

// This is our TrackerPayload that we created
var payload:IPayload = new TrackerPayload();
trackerPayload.add("key", "value");

// We wrap that payload in a SchemaPayload before sending it.
var payload:SchemaPayload = new SchemaPayload();
payload.setSchema(Constants.SCHEMA_SCREEN_VIEW);
payload.setData(trackerPayload);

Back to top