Welcome guest , come try our free game analytics!

• Create Account
• Sign in

Setting up the AS3 API

Download Browse on Github

Unzip that file so that the Playtomic folder is in the same folder as your game FLA and import the Playtomic classes into any of your ActionScript files or code sections that will use them:

import Playtomic.*;

Initialize the API by logging the view

A view occurs when someone loads the game in any way. Begin by registering the view early in your game. You must log the view before anything else to initialize the Playtomic API.

Log.View(gameid, "guid", "apikey", root.loaderInfo);

Check the API page for your game in the dashboard to get your codes. Remember to encrypt your game with something like Kindisoft to protect your API key.

Use the coupon Playtomic to get 25% off Kindisoft!

SSL (https)

Premium users can use SSL for all API communication by calling this method before logging the view:

Playtomic.Log.SetSSL();

Analytics

Views / sessions

A view occurs whenever somebody views your game. This should go somewhere very early in your code like before the preloader.

Because the View method initializes the entire Playtomic API it has several parameters that must be passed, and it must be called before you can log anything else.

Log.View(gameid, "guid", "apikey", root.loaderInfo);

Note: We are currently changing the naming to Sessions as it is more appropriate today. Changes will be applied in next API version.

Plays / Engages

This occurs wherever you feel a player has become engaged in your game. It's subjective, previously we recommended putting it on the play button but that is less suitable in a mobile environment so you should use this at some point early in your game where you feel a player has decided to really play your game rather than open it.

Note: We are currently changing the naming to Engages. Changes will be applied in next API version.

Play time, countries and sources

This data is logged automatically when you send other events.

package
{
    import flash.display.MovieClip;
    import flash.events.MouseEvent;
    import Playtomic.*;
    
    public class MainMenu extends MovieClip
    {
        public function ClickedPlayButton(e:MouseEvent):void
        {
            Log.Play();
            
            // continue starting game
            ...

Freezing, unfreezing and force-sending events

Events are sent in batches each time the play timer updates (every 30 seconds after the first minute). If you want to ensure an event gets sent:

Log.ForceSend();

Some games are very resource-intensive and the API might send off a batch of events at exactly the wrong time. You can freeze and unfreeze the logging at any time by:

Log.Freeze();
Log.UnFreeze();

When logging is frozen all events are queued but not sent until you unfreeze the API.

Custom metrics

Custom metrics allow you to track how many people do something in your game, for instance how many play on easy, medium or hard, or how many play in English vs. Spanish, or how many view the tutorial or skip it. Anything you think can help you improve your game.

You can define custom metrics directly in your game and they will be added to Playtomic automatically. Groups can be automatically assigned via an optional second parameter or set up later in the dashboard.

You can also limit custom metrics to unique-per-view occurances with a third parameter.

Log.CustomMetric("ViewedCredits"); // metric, names must be alphanumeric
Log.CustomMetric("Credits", "Screens"); // metric with group, groups must be alphanumeric
Log.CustomMetric("ClickedSponsorsLinks", "Links", true); // unique metric with group

Level metrics

Level metrics track events on a per-level basis so you can drill down into your difficulty and retention by identifying which levels have problems and what those problems are.

There are three types of level metrics - counters (like custom metrics), ranged-value and average-value.

Note that you can pass either an integer level number or a string name of the level. If your game is not using numeric levels (eg an escape game) then you would pass the name of each screen / area as a level.

You can define level metrics directly in your game and they will be added to Playtomic automatically.

Level metrics support unique-per-play occurrances via an optional second parameter. If the player starts a new game they will be tracked again.

Counter metrics

These metrics track how many times something occurs in your levels, for instance deaths and restarts.

One of the most valuable pieces of data you can track is how many people begin each level, this allows you to see where you lose players.

Log.LevelCounterMetric("Deaths", level_number); // names must be alphanumeric
Log.LevelCounterMetric("Restarts", "LevelName"); // level names must be alphanumeric
Log.LevelCounterMetric("Restarts", "LevelName", true); // unique only

Average metrics

These metrics track the average of something in your levels, for instance the average time to finish a level or the average number of retries. It also tracks the minimum and maximums.

Log.LevelAverageMetric("Time", level_number, seconds);
Log.LevelAverageMetric("Retries", level_number, retries);
Log.LevelAverageMetric("Retries", level_number, retries, true); // unique only

Ranged-value metrics

These metrics track metrics with values, for instance in a golf game you might track how many shots it takes to complete each level, or you might track the % of coins collected on each level.

Log.LevelRangedMetric("Shots", level_number, shots);
Log.LevelRangedMetric("PercentCoinsCollected", level_number, int(coins / coinstotal * 100));
Log.LevelRangedMetric("Shots", level_number, shots, true); // unique only

Heatmaps

Heatmaps allow you to map activity (clicks, deaths, first deaths, or anything else you want) against an image you upload in the dashboard.

Log.Heatmap("Metric", "Heatmap", x, y);

In the dashboard you upload a background image for the heatmap, and then it is shared by any metrics using it.

Referrers

Referrers allow you to track who has referrered your game.

Log.SetReferrer("Referrer");

Link tracking

Link tracking allows you to keep track of how many people open URLs in your game, providing you information on unique, total and failed clicks that can fully audited to allow you to identify good sources of traffic and sites that block links.

Link tracking does not change your URL or redirect traffic through a different url!

How to track a link

You track a link by passing a URL and some other information to the API. The API will return true or false if the link opens, everything else is automatic.

Link.Open(url:String, name:String, group:String):Boolean

Link.Open("http://website.com/?gameref=my_game", "PlayMoreGames", "Sponsor");

Optionally specify trackonly to true to not try and open the link, or if you are opening the link a 'target' to open the link in. By default it is now using '_blank' for 3.47+ and you may override this with a fifth parameter:

Link.Open("http://website.com/?gameref=my_game", "PlayMoreGames", "Sponsor", trackonly, "mytarget");

Domain Totals

When you track a link it automatically also tracks the totals for the domain in a group it creates called DomainTotals. The DomainTotals allows you to see how many unique, total and failed clicks occurred for a single domain even if you have multiple, different links to it (eg walkthrough or differently-structured sponsor links).

Remember

Links must be opened by a mouse event - a click on a button - or else popup blocks may interfere. Your code needs to look something like this:

function SplashClick(e:MouseEvent):void
{
    Link.Open("http://website.com/?gameref=my_game&location=splash", "Splash", "Sponsor");
}

Parse custom databases

This feature is provided in conjunction with Parse so you will need to create your account with them before you can use it.

Custom databases allow you to store and manipulate any data you want in any way you want, like:

• User registration
• Mailing list (and send through MailChimp)
• Saved games
• Surveys & feedback
• Messaging
• etc

The PFObject

This object represents a piece of data in your database. It has the following properties:

Property	Type	Description
ObjectId	String	If your object already exists in your database it will have this unique identifier.
ClassName	String	The 'type' of data this is - user, score, etc
Data	Object	Your actual data to save, eg po.Data.FirstName
UpdatedAt	Date	When the object was last updated in the database
CreatedAt	Date	When the object was created in the database
Password	String	If an object has a password when it is saved the password must be included to update it.

The PFQuery

This object allows you to construct a query to run against your database to find objects you've saved.

Property	Type	Description
ClassName	String	The 'type' of data to return - user, score, etc
WhereData	Object	Data to filter by, eg pq.WhereData.FirstName = 'ben'
Order	String	What field (from Data) to sort by
Limit	int	Numner of results to return

Saving / updating an object

You can save any object you want by creating a PFObject and sending it to Parse.Save. An object will save if it does not have an ObjectId, if it does then it will update.

var po:PFObject = new PFObject();
po.ClassName = "savedgames";
po.Data.Name = "Ben";
po.Data.Level = 1;
po.Data.Stage = 7;
Parse.Save(po, SaveComplete);

function SaveComplete(po:PFObject, response:Response):void
{
    if(response.Success)
    {
        trace("Saved object: " + po.ObjectId);
    }
    else
    {
        trace("Failed to save: " + response.ErrorMessage);
    }
}

Loading an object

You can load any object as long as you know it's ClassName and ObjectId (which you might obtain from a PFPointer).

var po:PFObject = new PFObject();
po.ClassName = "savedgames";
po.ObjectID = "asdfasdf";
Parse.Load(po, LoadComplete);

function LoadComplete(po:PFObject, response:Response):void
{
    if(response.Success)
    {
        trace("Loaded object: " + po.ObjectId);
    }
    else
    {
        trace("Failed to load: " + response.ErrorMessage);
    }
}

Finding objects / querying your database

Using the PFQuery object you can locate data in your database:

var pq:PFQuery = new PFQuery();
pq.ClassName = "savedgames";
pq.WhereDate.Name = "Ben";
pq.Limit = 5;

Parse.Find(pq, FindComplete);

function FindComplete(results:Array, response:Response):void
{
    if(response.Success)
    {
        trace("Loaded objects");

        for(var i=0; i<results.length; i++)
            trace(results[i].ObjectId);
    }
    else
    {
        trace("Failed to find: " + response.ErrorMessage);
    }
}

Deleting objects

You can delete an object easily:

// po is a PFObject you've previously loaded from somewhere
Parse.Delete(po, DeleteComplete);
            
function DeleteComplete(response:Response):void
{
    if(response.Success)
    {
        trace("Deleted object");
    }
    else
    {
        trace("Failed to delete: " + response.ErrorMessage);
    }
}

Level sharing

The level sharing API provides a way to store and retrieve user-generated content for your game. It can operate anonymously or authenticated via any 3rd party service you're already using.

The PlayerLevel class

Saving and listing levels uses this class to represent a level.

Property	Type	Description
PlayerName	String	The name of the player (or "anonymous", "guest", etc), or the name provided by any 3rd party API.
PlayerId	String	If you're working under a 3rd party API you can include the player's user id
PlayerSource	String	If you're working under a 3rd party API you can specify which, eg "gamersafe" or "mochicoins"
Name	String	The name of the level
Data	String	The data for the level. You can Base 64 encode a ByteArray to a string if necessary.
Votes	int	The number of votes the level has
Score	int	The sum of all votes the level has
Rating	int	The rating the level has (score / votes)
SDate	Date	The date of the level, determined automatically by Playtomic
RDate	String	The relative date of the level eg "7 minutes ago", determined automatically by Playtomic
CustomData	Object	Any additional data you want to (or have) attached to a score, like the level the player reached or what character they used
Thumbnail	Func, ret. string	The URL of the thumbnail, unless you generate them from data (recommended)
Starts	int	The number of times the level has been started
Wins	int	The number of times the level has been won
Quits	int	The number of times the level has been quitted
Retries	int	The number of times the level has been retried
Flags	int	The number of times the level has been flagged

Saving levels

PlayerLevels.Save(level:PlayerLevel, thumb:DisplayObject=null, callback:Function=null)

Parameter	Type	Description
level	PlayerLevel	An instance of PlayerLevel holding the level data
thumb	DisplayObject	A DisplayObject (movieclip, sprite, bitmap etc) the level is rendered on
callback	Function	Optional function to pass the submission result to

Example saving level:

function SaveLevel(e:MouseEvent):void
{
    var level:PlayerLevel = new PlayerLevel();
    level.Name = "My level";
    level.Data = level_data; // level data is a string and can be up to about 3 megabytes
			
    PlayerLevels.Save(level, my_thumbnail, this.SaveComplete);
}

function SaveComplete(level:PlayerLevel, response:Object):void
{
    if(response.Success)
    {
        trace("Level saved successfully, the level parameter is ready for use!");
    }
    else
    {
        // failed because of response.ErrorCode
    }
}

Rating levels

Levels can be rated 1 - 10 by players. Rating can be done anonymously with some protection against repeat voting, or bound to PlayerIds if you specify them.

PlayerLevels.Rate(levelid:String, rating:int, callback:Function=null)

Parameter	Type	Description
levelid	String	a_player_level.LevelId
rating	int	1 - 10
callback	Function	Optional function to pass the submission result to

Example rating level:

function Rate(e:MouseEvent):void
{
    PlayerLevels.Rate(currentlevel.LevelId, rating_amount, this.RateComplete);
}

function RateComplete(response:Object):void
{
    if(response.Success)
    {
        trace("Rating complete"");
    }
    else
    {
        // Rating failed because of response.ErrorCode
    }
}

Listing levels

Listing levels can be done by popular or newest, with optional filtering by date ranges and/or custom data.

PlayerLevels.List(callback:Function, options:Object)

Parameter	Type	Description
callback	Function	Function to pass the levels to
options	Object	Optional object which may contain these properties: mode (String): 'popular' or 'newest' datemin (String): 'mm/dd/yyyy' for the minimum date the level was created datemax (String): 'mm/dd/yyyy' for the maximum date the level was created data (Boolean): specify true if you want level data returned with the list customfilters (Object): filter by custom data you've saved with levels page (int): The page you want (default is 1) perpage (int): The number of level to return (default is 20)

An example listing levels:

function ListLevels(e:MouseEvent):void
{
    PlayerLevels.List(this.ListLoaded, {mode: "newest", customfilters: {difficulty: "hard"}});
}
		
function ListLoaded(levels:Array, numlevels:int, response:Object):void
{
    if(response.Success)
    {
        for(var i:int=0; i<levels.length; i++)
        {
            trace(" - " + levels[i].LevelId + ": " + levels[i].Name);
        }
    }
    else
    {
        // Level list failed to load because of response.ErrorCode
    }
}

Loading levels

If you do not include the data when you load lists of levels then you can request it seperately:

PlayerLevels.Load(levelid:String, callback:Function)

Parameter	Type	Description
levelid	String	a_player_level.LevelId
callback	Function	Function to pass the level to

An example loading a single level

function Load(e:MouseEvent):void
{
    PlayerLevels.Load(level.LevelId, this.LoadComplete);
}
		
function LoadComplete(level:PlayerLevel, response:Object):void
{
    if(response.Success)
    {
        trace("Level has been loaded, now you can begin playing it");
    }
    else
    {
        // level failed to load because of response.ErrorCode
    }
}

Defering to Kongregate

If you are using our level sharing API you can easily patch your game to work with Kongregate's API on their website. The big advantage of this is on Kongregate they will list player created levels on user profiles to drive more traffic on to your game.

You can still use the Playtomic API calls you already have to save, list, load and rate levels, and it will automatically pass the request on to Kongregate!

First create a function that will receive levels from the Playtomic API:

private function KongLevelReceiver(level:PlayerLevel):void
{
    // start your level as if it came from your level-browsing screen
}

Next we tell the Playtomic API to defer using this function:

PlayerLevels.DeferToKongregate(KONG_API_SERVICE, KongLevelReceiver);

You will need to hide the in-game browsing screens and just have those buttons call the PlayerLevels.List() methods instead. These will be passed on to Kongregate and open their out-of-game level browser.

Leaderboards

The Leaderboards API gives you very flexible high and low score leaderboards. They can be created in your game dynamically or set up in the edit leaderboards page.

The scores code includes basic protection from cheating but you should also include options like Mochi Digits to protect values in-memory.

The PlayerScore class

The leaderboards use the PlayerScore class for representing the players' scores.

Property	Type	Description
Name	String	The player name. This can be by the player or provided by any 3rd party
FBUserId	String	If you're working with Facebook scores specify the player's user id
Points	Number	The player's score
Rank	int	The rank based on your listing parameters.
Website	String	The website the score occurred on, determined automatically by Playtomic
SDate	Date	The date of the score, determined automatically by Playtomic
RDate	String	The relative date of the score eg "7 minutes ago", determined automatically by Playtomic
CustomData	Object	Any additional data you want to (or have) attached to a level.

Submitting scores

Score submission is handled by:

Leaderboards.Save(score:PlayerScore, table:String, callback:Function=null, options:Object=null);

Parameter	Type	Description
score	PlayerScore	An instance of PlayerScore which contains score information
table	String	The score table to submit to, alphanumeric
callback	Function	Optional function to pass the submission result to
options	Object	Optional object which may contain these properties: facebook (boolean): Set this to true if your score is for a Facebook leaderboard highest (boolean): Set this to false if your leaderboard is for lowest scores allowduplicates (boolean): Set this to false if you don't want players' scores to be overwritten

function SubmitScore(e:MouseEvent):void
{
    var simple_score:PlayerScore = new PlayerScore();
    simple_score.Name = player_name;
    simple_score.Points = player_score;

    // submit to the highest-is-best table "highscores"
    Leaderboards.Save(simple_score, "highscores"); 

    // submit to the lowest-is-best table "besttimes"
    Leaderboards.Save(simple_score, "besttimes", null, {highest: false}); 

    // submit an advanced score with custom data and a callback function
    var advanced_score:PlayerScore = new PlayerScore();
    advanced_score.Name = player_name;
    advanced_score.Points = player_score;
    advanced_score.CustomData["Character"] = player_character;
    advanced_score.CustomData["Level"] = current_level;

    Leaderboards.Save(advanced_score, "highscores", this.SubmitComplete);
}

function SubmitComplete(response:Object):void
{
    if(response.Success)
    {
        trace("Score saved!");		
    }
    else
    {
        // submission failed because of response.ErrorCode
    }
}

Showing scores

Scores are loaded via a simple method that returns an array of PlayerScore objects to your function where you can display the data in your leaderboard.

Leaderboards.List(table:String, callback:Function, options:Object=null);

Parameter	Type	Description
table	String	Your leaderboard table name, must be alphanumeric
callback	Function	Your function that receives the data
options	Object	Optional object which may contain: global (boolean): Show scores from all websites or only the website the player is on highest (boolean): Set this to false if your leaderboard is for lowest scores mode (String): Show scores from 'last7days', 'last30days', 'alltime' (default), 'today' or the special mode 'newest' which gives you a stream of unranked scores customfilters (Object): Filter by scores with specific CustomData page (int): The page you want (default is 1) perpage (int): The number of scores to return facebook (Boolean): false, unless you set it to true to return their FBUserId friendslist (Array): if it's Facebook scores you can provide an array of their friends' user ids to show friends scores

function ShowScores(e:MouseEvent):void
{
    Leaderboards.List("highscores", this.ListComplete);
}

function ListComplete(scores:Array, numscores:int, response:Object):void
{
    if(response.Success)
    {
        trace(scores.length + " scores returned out of " + numscores);
				
        for(var i:int=0; i<scores.length; i++)
        {
            var score:PlayerScore = scores[i];
            trace(" - " + score.Name + " got " + score.Points + " on " + score.SDate);
            
            // including custom data?  score.CustomData.property
        }
    }
    else
    {
        // score listing failed because of response.ErrorCode
    }
}

Save and list

You can now submit scores and at the same time return the leaderboard page that that score is on.

This combines the Save and List approaches from above:

Playtomic.Leaderboards.SaveAndList(score:PlayerScore, table:String, callback:Function=null, options:Object=null)

Some important notes:

• You don't specify a page, you specify the PerPage (default 20) and it will automatically decide which page to return based on the submitted score's rank. If you submit the 1187th best score at 30 per page then it will show you page 39, scores #1170 - #1200.
• Ranks are returned, so you are not viewing the top N scores you are viewing the top N scores from rank X onwards.

Private leaderboards (EXPERIMENTAL NEW FEATURE!)

You can now provide your players the ability to create their own leaderboard complete with a permalink and shortened URL they can give their friends to compete against each other.

Note - your website, or your sponsor's website, must have allowScriptAccess set to always or sameDomain otherwise this will not work.

Note: The permalink is going to append the leaderboard table's id, it should be like "http://site.com/game/?leaderboard=" or http://site.com/game?something=whatever&leaderboard=

Creating a leaderboard is simply:

Playtomic.Leaderboards.CreatePrivateLeaderboard(name, highest, permalink, callback);

function CreateMyLeaderboard(e:MouseEvent):void
{
    Leaderboards.CreatePrivateLeaderboard(leaderboardname.text, true, "http://mysponsorsite.com/mygame?leaderboard=", this.CreateComplete);
}

function CreateComplete(response:Object):void
{
    if(response.Success)
    {
        trace(response.Name);
        trace(response.Permalink); // full link, eg sponsorwebsite.com/play/my/game?leaderboard=asdfasfasdfasdf
        trace(response.Bitly); // bitly link to their leaderboard, eg bitly.com/blabla
        trace(response.Highest);
        trace(response.RealName); // internally used guaranteed unique name: user_RANDOMSTUFF_the name they provided
    }
    else
    {
        // leaderboard failed to save because of response.ErrorCode
    }
}

When a person visits either the Permalink or the shortened Bitly link you can make them use that leaderboard by:

var leaderboardid:String = Leaderboards.GetLeaderboardFromUrl();
            
if(leaderboardid != null)
{
    Leaderboards.Load(leaderboardid, this.PrivateLeaderboarLoaded);
}

function PrivateLeaderboardLoaded(response:Object):void
{
    trace(response.Name);
    trace(response.Permalink);
    trace(response.Bitly);
    trace(response.Highest);
    trace(response.RealName);
}

When you save scoers on a private leaderboard you must use the RealName, not the Name.

Showing Facebook scores

This is now merged with normal listing. Set the option property facebook to true, and optionally pass an array of the user's friend ids to only show their friends scores.

Embedding scores on your website

Scores are no longer available directly via URL as they expect POST data now. You will need to use the HTML5 / JavaScript API for showing scores on your web page, or the Flash or other APIs for embedding them in a SWF or other container.

GameVars

GameVars let you change the value of key variables in your game any time you want. They must be configured in the edit GameVars page in advance.

It is called via:

GameVars.Load(callback);

Load individually

You can load variables individually, for instance if you are caching the GameVars you can check a 'version' GameVar to decide whether to reload the full collection.

GameVars.LoadSingle("name", callback);

The callback parameter is your function that receives an object that has properties matching the variables you have configured in the dashboard. The callback is the same for all or single GameVars.

// our variables with default, original values
var BaseHitPoints:int = 100;
var BaseGold:int = 50;

function InitialiseGame():void
{
    // load GameVars
    GameVars.Load(this.GameVarsLoaded);
    // or GameVars.LoadSingle("gameconfig", this.GameVarsLoaded);

    // carry on initializing your game
}

function GameVarsLoaded(vars:Object, response:Object):void
{
    if(response.Success)
    {
        // sync the in-game variables
        this.BaseHitPoints = vars.BaseHitPoints;
        this.BaseGold = vars.BaseGold;
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

Geolocation

The GeoIP service identifies which country the player is from, returning their country code and name.

It is called via:

GeoIP.Lookup(callback);

The callback function receives an object that has Code and Name properties:

function SetPlayerCountry(country:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the country data
        trace("Player is from " + country.Code + " / " + country.Name);
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

Data lookup

Note: You must enable this functionality in each game's settings. By default it is disabled becaue it can expose your game data.

The Data class in the API allows you to retrieve any of your game data to display in your game.

Each function for retrieving data takes an optional parameters object for day, month and year, with default values of 0.

• When day, month and year are specified you will receive data for that specific day.
• When month and year are specified you will receive data for that specific month.
• When day, month and year are unspecified or 0 then you will receive data for all time.

Views, Plays and Play Time

The Views, Plays and PlayTime functions returns this data to you for processing:

Data.Views(callback:Function, options:Object=null);

Parameter	Type	Description
callback	Function	Your function that receives the data
options	Object	Optional object which may contain day, month and year properties

Data.Views(this.OutputData); // views for all time
Data.Plays(this.OutputData, {day: 22, month: 3, year: 2010}); // plays on March 22, 2010
Data.PlayTime(this.OutputData, {month: 3, year: 2010}); // play time for March, 2010

function OutputData(data:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the data
        trace(data.Name + " has value " + data.Value + " for " + data.Month + "/" + data.Day + "/" + data.Year);
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

Custom metrics

The CustomMetric function returns data about a custom metric to your function, which receives the same parameters as views/plays/play time above.

Data.CustomMetric(name:String, callback:Function, options:Object=null);

Parameter	Type	Description
name	String	The name of your custom metric
callback	Function	Your function that receives the data
options	Object	Optional object which may contain day, month and year properties

Data.CustomMetric("Clicked sponsor link", this.OutputData);

function OutputData(data:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the data
        trace(data.Name + " - " + data.Metric + " has value " + data.Value + " for " + data.Month + "/" + data.Day + "/" + data.Year);
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

Level metrics

There are three methods for retrieving level metrics. The functions that receive the data are different from the above examples.

Data.LevelCounterMetric(name:String, level:*, callback:Function, options:Object=null);
Data.LevelRangedMetric(name:String, level:*, callback:Function, options:Object=null);
Data.LevelAverageMetric(name:String, level:*, callback:Function, options:Object=null);

Parameter	Type	Description
name	String	The name of your custom metric
level	int or String	The level number or name
callback	Function	Your function that receives the data
options	Object	Optional object which may contain day, month and year properties

Data.LevelCounterMetric("Started level", level_number, this.OutputLevelCounter);
Data.LevelRangedMetric("Shots remaining", level_name, this.OutputLevelRanged, {month: 3, year: 2010});
Data.LevelAverageMetric("Retries", level_number, this.OutputLevelAverage, {day: 22, month: 3, year: 2010});
            
function OutputLevelCounter(data:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the data
        trace(data.Name + " - " + data.Metric + "on level " + data.Level + " has value " + data.Value + " for " + data.Month + "/" + data.Day + "/" + data.Year);
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

function OutputLevelRanged(data:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the data
        trace(data.Name + " - " + data.Metric + "on level " + data.Level + " for " + data.Month + "/" + data.Day + "/" + data.Year);

        for(var i:int=0; i<data.Values; i++)
        {
            trace(" - Tracking value " + data[i].Value + " ocurred " + data[i].Occurances + " times");
        }
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

function OutputLevelAverage(data:Object, response:Object):void
{
    if(response.Success)
    {
        // we have the data
        trace(data.Name + " - " + data.Metric + "on level " + data.Level + " has min " + data.Min + ", max " + data.Max + ", average " + data.Average + " for " + data.Month + "/" + data.Day + "/" + data.Year);
    }
    else
    {
        // request failed because of response.ErrorCode
    }
}

Error codes

When a Playtomic service is unreachable or has an error it will return a numeric error code. This table describes those errors:

General errors

These errors may be returned from any service.

Code	Meaning
0	No error
1	General error, this typically means the player is unable to connect to the Playtomic servers
2	Invalid game credentials. Make sure you use your SWFId and GUID from the "API" section in the dashboard.
3	Request timed out.
4	Invalid request. This means the request wasn't formed right, probably because the API key wasn't provided or was incorrect.

GeoIP errors

Code	Meaning
100	GeoIP API has been disabled. This may occur if your game is faulty or overwhelming the Playtomic servers.

Leaderboard errors

Code	Meaning
200	Leaderboard API has been disabled. This may occur if your game is faulty or overwhelming the Playtomic servers.
201	The source URL or name weren't provided when saving a score. Make sure the player specifies a name and the game is initialized before anything else using the code in the "Set your game up" section.
202	Invalid auth key. You should not see this normally, players might if they tamper with your game.
203	No Facebook user id on a score specified as a Facebook submission.
204	Table name wasn't specified for creating a private leaderboard.
205	Permalink structure wasn't specified: http://website.com/game/whatever?leaderboard=
206	Leaderboard id wasn't provided loading a private leaderboard.
207	Invalid leaderboard id was provided for a private leaderboard.
208	Player is banned from your leaderboard.
209	SaveAndList only. The score was not the player's best score. You can message the player, highlight their best via the SubmittedOrBest boolean property of scores, or override this by setting allowduplicates to true.

GameVars errors

Code	Meaning
300	GameVars API has been disabled. This may occur if your game is faulty or overwhelming the Playtomic servers.

Level sharing errors

Code	Meaning
400	Level sharing API has been disabled. This may occur if your game is faulty or overwhelming the Playtomic servers.
401	Invalid rating value (must be 1 - 10).
402	Player has already rated that level.
403	The level name wasn't provided when saving a level.
404	Invalid image auth. You should not see this normally, players might if they tamper with your game.
405	Invalid image auth (again). You should not see this normally, players might if they tamper with your game.
406	The level already exists. This is determined via a hash of the game id, level name, player ip address and name, and source url.

Data API errors

Code	Meaning
500	Data API has been disabled. This may occur if the Data API is not enabled for your game, or your game is faulty or overwhelming the Playtomic servers.

Parse Custom Database errors

Code	Meaning
600	You have not configured your Parse.com database. Sign up at Parse and then enter your API credentials in your Playtomic dashboard.
601	No response was returned from Parse. If you experience this a lot let us know exactly what you're doing so we can sort out a fix for it.
6021	Parse's servers had an error.
602101	Object not found. Make sure you include the classname and objectid and that they are correct.
602102	Invalid query. If you think you're doing it right let us know what you're doing and we'll look into it.
602103	Invalid classname.
602104	Missing objectid.
602105	Invalid key name.
602106	Invalid pointer.
602107	Invalid JSON.
602108	Command unavailable.