Follow

Integrating Apmetrix Flash (ActionScript 3) SDK

Click the link below to access the Apmetrix SDKs

ApmetrixSDK's

Integrating Apmetrix SDK with Flash (ActionScript 3)

 The following simple steps explain how to integrate our SDK into your game or other web application.

STEP 1 – Add the SDK to project build path in Flash Builder

Under Project -> Properties, select the “ActionScript Build Path” Resource.  Select the “Library path” tab and click the “Add SWC…” button.  Browse to the directory where you have saved the Apmetrix.swc, select the file and press OK.  In the Flash Builder Project Explorer pane you should now see Apmetrix.swc listed under “Referenced Libraries”.

ActionScript1.jpg
 

STEP 2 – Add the required frameworks to your ActionScript project

As in Step 1 above, open up the ActionScript Build Path and select the Library path tab.  Highlight the Flex library entry and click the “Add SWC…” button.  Browse to the directory where framework.swc was installed (this will depend on the versions of Flash Builder and SDK you are using).  See the following example:

...\Program Files\Adobe\Adobe Flash Builder 4.6\sdks\4.6.0\frameworks\libs\framework.swc

 

ActionScript2.jpg

 

Select the file and press OK.  As shown above, framework.swc should appear as one of the Shockwave components under Flex.

STEP 3 – Integrate with the Apmetrix SDK

Add the following import path to those class files you are calling the SDK from:

 import com.apmetrix.sdk.Apmetrix;

THAT’S IT!!!  You are now collecting the key device and session data.  At this point you have successfully completed the integration of the SDK.  You can now set up and call the various functions you need to the Apmetrix analytics platform.

SDK FUNCTIONS

INITIALIZE SESSION – Initialize (i.e. start an app session) using the following:

Function call:

Apmetrix.init(appDataset:int, appVerion:String, appUnifier:String)

 where:

appDataset

This number identifies the dataset used for the app data. Note: The dataset ID is sent to you when a new account has been registered or a new game has been added to your company. You will need to pass in this ID before any data can be collected.

appVersion

is a string that identifies the version of the application.

appUnifier

String which when combined with the appDataset identifies a unique app.

Note: The appDataset and appUnifier can be found in the dashboard under Tasks->Administration->Accounts, expanding Datasets, and selecting your Dataset.

This method returns an “int” value to indicate the resulting status of the function call and will equal one of the following:

Apmetrix.SUCCESS 

Successful operation.

Apmetrix.WARNING_IGNORED_SESSION_ALREADY_OPEN 

Function call was ignored because a session was already open.

Apmetrix.ERROR_INVALID_ARGUMENTS 

Operation could not be completed because the parameters passed were incorrect.

Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

Tracking User Interaction – To log coordinates of user events on specific screens use:

Function Call:

Apmetrix.ApTrak(event:String, location:String, ... coordinates);

event

identifies the event being logged

location

identifies the location or screen the event occurred on

coordinates

a list of coordinates for the event ordered as X, Y, [Z] and [W] (where X and Y are required and Z and W are optional)

Tracking User Interaction code example where optional Z coordinate is used (but not W coordinate):

Apmetrix.ApTrak(“died”, “screen 2”, “25.5”, 480.75”, “14.25”);

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

Apmetrix.SUCCESS

Successful operation.

Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because event parameters passed exceeded maximum amount.

Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

RESTARTING SESSION - To restart a session use:

Function Call:

Apmetrix.restartSession()

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

Apmetrix.SUCCESS 

Successful operation.

Apmetrix.WARNING_IGNORED_SESSION_ALREADY_OPEN

Function call was ignored because a session was already open().

Apmetrix.WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not yet been initialized with a call to Apmetrix.init().

Apmetrix.ERROR_INVALID_ARGUMENTS 

Operation could not be completed because the parameters passed were incorrect.

Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

 ADDING CUSTOM EVENTS - To add custom events/tags to your game or app use:

Function Call:

Apmetrix.logEvent(tableType:int, ... dimensions)

where:

tableType

Predefined value for the type of custom event

dimensions

Variable length comma delimited list of custom event dimensions.

Note: The platform has the ability to take in up to 25 string dimensions (maximum) and 4 metric dimensions (maximum).

Adding custom events to your game or app is hugely beneficial and highly encouraged as it allows you to track many types of events and actions that users and applications generate.  Our platform allows you to pass in an unlimited number of these events and track them in many different ways.  While this functionality is extremely powerful, it can also be very unwieldy if some best practices are not thought of or contemplated in advance.  While you can of course create as many dimensions as you like (up to 24 in fact), we have suggested a logical way using 4 dimensions which may make it easier to create and and report on your custom data.

We have predefined several datasets which should cover most of custom events which you would want to track:

User Events:                  

This can be any event created by a user in your game or app. 

Application Events:     

These are events generated by your game or app and are events not associated with user actions.

Un-Grouped Events:   

These are any custom events which are not covered under with the User or Application events.

As a game or app can have many such custom events, it is important to logically categorize your local application variables as you would logically think such an event should be tracked.  A suggested structure (at least for the first four dimensions) would be as follows;

  • Verb – What event is occurring such as “crashed”, “invited”, “fired”, “damaged” etc.
  • Object – What action is occurring on what object such as “car”, “friend”, “house” etc.
  • Location – Where did such an event occur?  It is useful to think of this within the context of your game or app as each is different based on context.  For example; for an adventure game you may want to list the map or level where the event occurred.  For a racing game, perhaps the track, or for a puzzle game, the name of the puzzle or level.  Think in terms of relevant location data you’d need to know.
  • Value – This is additional information in the form of a string you may wish to pass in depending on the specific event you are tracking. For example; you may want to pass in the time for the car crashed, determine whether a condition was True or False, etc.
  • Numerical Value - This is additional information you may wish to pass in depending on whether or not you need to pass in a number (i.e. if you want to track currency or economy flows such as "Primary Currency at Session Start", Primary Currency Earned", "Primary Currency Spent", "Primary Currency at Session End" ).

Important Notes:

Since the system defaults to treating incoming data as strings, you will need to include the “#” symbol in front of your metric data so the system recognizes it as a numerical value.

Also note that since these are literal examples you will need to replace the parameter with the actual local game variable you wish to pass in to the platform so as to appropriately reflect your own data structure.


Custom Event Code Examples:

Following are some examples that demonstrate use of the logEvent() function using the above suggested ordering or dimensions.

Apmetrix.logEvent(Apmetrix.USERS_TABLE, “Car Status”, “Type of Race”, “Track Name”, “Time and Date”);
Apmetrix.logEvent(Apmetrix.USERS_TABLE, “Character Action”, “Spell Type”, “Level”, “Power”);
Apmetrix.logEvent(Apmetrix.USERS_TABLE, “Offerwall Popup”, “Offer Type”, “Where Offer Selected”, "Purchased");
Apmetrix.logEvent(Apmetrix.APPS_TABLE, “Logon”, null, “Facebook”, null);
Apmetrix.logEvent(Apmetrix.UN_GROUPED_TABLE, “Start Session”, “Primary Virtual Currency”, null, “#Currency Amount”);
Note: These are for example only and you are not limited to using this or any structure in sending custom events.  Simply replace the custom tags listed with your own game or app variables which occurred at the time of the event.  If there is no data in a particular field, make sure to type the word   null in the function call.

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

Apmetrix.SUCCESS

Successful operation.

Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because event parameters passed exceeded maximum amount.

Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

SET GEO TRACKING PERMISSIONS – To enable / disable tracking of user’s location:

Function Call:

Apmetrix.setTracking(trackingPermissions:int);

Where trackingPermissions can be set to the following:

Apmetrix.ALLOW_TRACKING_PERMISSION

The device GPS location is sent to the server (this is not child safe).

Apmetrix.BLOCK_TRACKING_PERMISSION

The device GPS location is NOT sent to the server.

Apmetrix.CHILD_SAFE_PERMISSION

The device GPS location is NOT sent to the server and the server does not use any other means (i.e. external IP Address) to determine user location.

Note:
1. calls to “setTracking” must be made BEFORE the call to “init” to take effect. 
2. If “setTracking” is not called before “init” then the default behavior to allow tracking is assumed.

Set Tracking Permissions code example (for the child safe condition):

Apmetrix setTracking(Apmetrix.CHILD_SAFE_PERMISSION);

 This method returns an "int" value to indicate the status of the function call and will equal one of the following:

Apmetrix.SUCCESS

Successful operation

Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect

ADDING “ONE-TIME” CUSTOM EVENTS - To add a custom event/tags to your game or app that occurs once use:

Function Call:

Apmetrix.logOneTimeEvent(tableType:int, tag:String, ... dimensions)

where:

tableType

Predefined value for the type of custom event

tag

Name identifying this one-time event

dimensions

Variable length comma delimited list of custom event dimensions.

 

Note:  See the documentation for the Apmetrix.logEvent() function for:

  1. the predefined values used for the table parameter,
  2. code examples of how the dimensions parameter may be used and,
  3. values the function can return to indicate the resulting status of the function call.

END SESSION - To end a session, use the following command:

Function:

Apmetrix.endSession()

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

Apmetrix.SUCCESS

Successful operation.

Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to end (or close).

Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. 

 

 

Have more questions? Submit a request