Flash ActionScript 2 API Documentation

Setting up the AS2 API

Unzip that file so that the Playtomic folder is in the same folder as your game FLA.

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.

Playtomic.Log.View(gameid, "guid", _root._url);

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 game.

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.

Playtomic.Log.View(xxx, "xxxxxxxxxxxx", root.loaderInfo.loaderURL);

Note: We are currently changing the naming to Sessions as it is more appropriate today. AS2 api will not be updated to reflect this.

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.

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:

Playtomic.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:

Playtomic.Log.Freeze();
Playtomic.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.

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.

Heatmaps

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

Playtomic.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.

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.

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).

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"

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:

Playtomic.GameVars.Load(callback);

The callback parameter is your function that receives an object that has properties matching the variables you have configured here:

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.

Friends:

Attribution:

Goodbye

Friends, Playtomic has come to an end. Part of this service will live on at Playtomic.org as a
self-hosted, open source platform I am continuing to develop in my spare time. The rest is unfortunately finished.