C++ API Documentation

Version 0.3 (Experimental)

Current as of 01/04/2012. If you see or have any problems let us know!

Setting up the C++ API

Download precompiled version: playtomic-cpp-0.3-precompiled.zip, or get it from GitHub (with examples)

You will also need to download boost and curl lib to compile the API. You can download the dependencies package from here.

• Visual Studio
• Xcode (Mac OS X)
• Xcode (iOS)
• Android

Playtomic::CPlaytomic *mInstance = new Playtomic::CPlaytomic( SWFID, GUID, true);
mInstance->Init();

Playtomic::CPlaytomic *mInstance = new Playtomic::CPlaytomic( SWFID, GUID, true);
mInstance->Init();

Playtomic::CPlaytomic *mInstance = new Playtomic::CPlaytomic( SWFID, GUID, true);
mInstance->Init();

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
PLAYTOMIC_PATH := #your path to playtomic should go here
LOCAL_MODULE := Playtomic-prebuilt
LOCAL_SRC_FILES := $(PLAYTOMIC_PATH)/libs/$(TARGET_ARCH_ABI)/libPlaytomic.so
include $(PREBUILT_SHARED_LIBRARY)
include $(CLEAR_VARS)


#...
#...
#in your project add this

LOCAL_CFLAGS += -fexceptions
LOCAL_CFLAGS += -D__ARM_ARCH_5__
LOCAL_CFLAGS += -D__ANDROID__
PLAYTOMIC_PATH := #your path to playtomic should go here

LOCAL_C_INCLUDES += $(PLAYTOMIC_PATH)/Dependencies/Android/Boost/ \
					$(PLAYTOMIC_PATH)/CurlWrap/ \
					$(PLAYTOMIC_PATH)/Tools/ \
					$(PLAYTOMIC_PATH)/json/include \
					$(PLAYTOMIC_PATH)/Dependencies/Android/curllib/include/ \
					$(PLAYTOMIC_PATH)/Playtomic/ \
                	$(PLAYTOMIC_PATH)/

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Playtomic::CPlaytomic *mInstance = new Playtomic::CPlaytomicAndroid(SWFID, GUID, vmPtr, activity, autoUpdate);
mInstance->Init();

Analytics

Views

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

Log()->View();

Plays

A play occurs when someone begins a game by clicking your play button or whatever action is relevant to your game. A person can get between 0 and many plays during a single view.

They're tracked seperately because the main menu is the first thing the player sees after loading and splash animations, and if they don't like it they'll leave.

Play time, countries and sources

This data is logged automatically when you send other events.

void StartedGame
{
            gPlaytomic->Log()->Play();
            
            // continue starting game
            ...

Freezing, unfreezing and force-sending events

Note: This is inherited from the Flash version which runs on a single thread, and is unlikely to be necessary in C++ games.

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.

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(const std::string& url, const std::string& name,const std::string& group);

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

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

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:

The PFQuery

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

The PFPointer

This object allows you to create a relationship between two objects - for instance my saved game might point to the inventory items I have.

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.

Saving levels

PlayerLevels()->SaveLevel(CLevel& level)

Example saving level:

void SaveLevel()
{
    CLevel level("My level","PlayerName", "Playerid","Any data");
    			
    SLevelListPtr list = gPlaytomic->PlayerLevels()->SaveLevel(level);

    if(list->sSucceded)
    {
        std::cout << "Level saved successfully, the level parameter is ready for use!" ;
    }
    else
    {
        // failed because of  list->sErrorCode
    }
}

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()->RateLevelId(const std::string& levelId, int rating);

Example rating level:

void Rate()
{
    CPlaytomicResponsePtr response = Playtomic::gPlaytomic->PlayerLevels()->RateLevelId(name,rating);

    if(response->ResponseSucceded())
    {
         std::cout << "Rating complete" << std::endl;
    }
    else
    {
         // Rating failed because of response->ResponseError()
    }
 
}

Listing levels

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

PlayerLevels()->List(const std::string& mode, int page, int perPage,
							        bool includeData, bool includeThumbs,
							        const CustomData& customFilter)

An example listing levels:

void ListLevels()
{
   SLevelListPtr list = gPlaytomic->PlayerLevels()->List("",1,10,false,false,customData);

   if(list->sSucceded)
   {
        std::list<Playtomic::CLevel>::iterator it = list->sLevelList.begin();
        for (; it != list->sLevelList.end(); it++)
        {
                std::cout << "name: " << it->GetName() << " LevelId: " 
                << (it->GetLevelId()) << "PlayerName: " << it->GetPlayerName() <<
                "date: "<< it->GetRelativeDate() <<std::endl;
        }
    }
    else
    {
        // Level list failed to load because of list->sErrorCode
    }
}

Loading levels

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

PlayerLevels()->LoadLevel(const std::string& levelId);

An example loading a single level

 void Load()
{
    SLevelListPtr list = gPlaytomic->PlayerLevels()->LoadLevel( level.GetLevelId());

    if(list->sSucceded)
    {
       //"Level has been loaded, now you can begin playing it"
    }
    else
    {
       // level failed to load because of list->sErrorCode
    }
}

Asynchronous Version

Asynchronous request are similar to the synchronous request but you need to set a delegate that implement IPlayerLevelDelegate to preocess the request.

To set the delegate you need to call:

CPlayerLevels::SetDelegate(IPlayerLevelDelegate* targetDelegate)

When you use the asynchronous calls you need to inherit from IPlayerLevelDelegate and implement its four pure virtual methods:

class IPlayerLevelDelegate
{
public:
    virtual void RateLevelComplete(CPlaytomicResponsePtr& result)=0;
    virtual void LevelListComple(SLevelList& result)=0;
    virtual void SaveLevelComple(SLevelList& result)=0;
    virtual void LoadLevelComplete(SLevelList& result)=0;
};

An example

class CMyClass : public IPlayerLevelDelegate
{
public:
    virtual void RateLevelComplete(CPlaytomicResponsePtr& result);
    virtual void LevelListComple(SLevelList& result);
    virtual void SaveLevelComple(SLevelList& result);
    virtual void LoadLevelComplete(SLevelList& result);
            void CallAsyncRequest();
};

void MyClass::CallAsyncRequest()
{
    CustomData customData;
    gPlaytomic->PlayerLevels()->SetDelegate(this);
    Playtomic::CLevel level( "Test Level", "My Name", "234561", "there should be data here");
	
    gPlaytomic->PlayerLevels()->SaveLevelAsync(level);
    gPlaytomic->PlayerLevels()->ListAsync("",1,10,false,false,customData);
    gPlaytomic->PlayerLevels()->LoadLevelAsync("4e9ef2b94d81233f30921596"); //hardcoded id from the dashboard
    gPlaytomic->PlayerLevels()->RateLevelIdAsync("4e9ef2b94d81233f30921596",10.0);
}

void MyClass::RateLevelComplete( CPlaytomicResponsePtr& result )
{
    if(result->ResponseSucceded())
    {
        std::cout << "rating succeded!" << std::endl;
    }
    else
    {
        std::cout << "rating failed! Err Code:" 
                  << result->ResponseError() << std::endl;
    }
}

void MyClass::LevelListComple( SLevelList& result )
{
    std::cout << std::endl << std::endl << "levels" 
              << " page: 0" << std::endl << std::endl;
    std::list<CLevel>::iterator it = result.sLevelList.begin();
    for (; it != result.sLevelList.end(); it++)
    {
        std::cout << "name: " << it->GetName() << " LevelId: " 
                  << (it->GetLevelId()) << "PlayerName: " << it->GetPlayerName() 
                  << "date: " << it->GetRelativeDate() << std::endl;
    }
}

void MyClass::SaveLevelComple(SLevelList& result )
{
    if(!result.sSucceded)
    {
        std::cout << "failed to save level, error code :" << result.sErrorCode;
    }
}

void MyClass::LoadLevelComplete( SLevelList& result )
{
    if(result.sSucceded)
    {
        if(result.sLevelList.size() == 0)
        {
            std::cout << "could not find the entry:" << std::endl;
        }
        else
        {
            std::list<CLevel>::iterator it = result.sLevelList.begin();
            for (; it != result.sLevelList.end(); it++)
            {
                std::cout << "name: " << it->GetName() << " LevelId: "
                          << (it->GetLevelId()) << "PlayerName: " << it->GetPlayerName() 
                          << "date: " << it->GetRelativeDate() << std::endl;
            }
         }
    }
    else
    {
        std::cout << "failed to get the level!" << std::endl;
        std::cout << "error number: " << result.sErrorCode << std::endl;
    }
} 

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 PlayerScore class

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

Submitting scores

Score submission is handled by:

Leaderboards()->SaveTable(const std::string& tableName, const CScore& score, bool highest, bool allowDuplicates);

void SubmitScore()
{

    CScore simpleScore("Player Name", 1000);
     // submit to the highest-is-best table "highscores"  
    response = gPlaytomic->Leaderboards()->SaveTable("highscores", simpleScore,true,true);
    if(response->ResponseSucceded())
    {
        std::cout << "new score entry success!" <<std::endl;
    }
    else
    {
        std::cout << "failed to save the score!" << std::endl;
        std::cout << "error number: " << response->ResponseError() << std::endl;
    }
     // submit an advanced score with custom data
    CustomData customData;
    customData.insert(std::make_pair("Character", playerCharacter));
    customData.insert(std::make_pair("Level", currentLevel));
    CScore advancedScore("Player Name", 1000, customData);
    response = gPlaytomic->Leaderboards()->SaveTable("highscores", advancedScore,true,true);
    if(response->ResponseSucceded())
    {
        std::cout << "new score entry success!" << std::endl;
    }
    else
    {
        std::cout << "failed to save the score!" << std::endl;
        std::cout << "error number: " << response->ResponseError() << std::endl;
    }
}

Showing scores

Scores are loaded via a simple method that returns an array of CScore objects so you can display the data in your leaderboard.

Leaderboards()->ListTable(const std::string& tableName, bool highest, const std::string& mode, int page, int perPage, const CustomData& customFilter);

void ShowScores()
{
   CustomData filter;
   SSCoreTablePtr table = gPlaytomic->Leaderboards()->ListTable("Demo Table",true,"last7days", 1,10 , filter);

   if (table->sSucceded)
   {
        std::cout << std::endl << std::endl << "scoretable" 
                  << " page: 1" << std::endl << std::endl;
        std::list<CScore>::iterator it = table->sScoreList.begin();
        for (; it != table->sScoreList.end(); it++)
        {
            std::cout << "name: " << it->GetName() << " Score: " 
                      << (int)(it->GetPoints()) << "Rank: " << it->GetRank() <<
                      "date: "<< it->GetRelativeDate() << std::endl;
        }
   }
}

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:

gPlaytomic->Leaderboards()->SaveAndListTable(const std::string& tableName, const CScore& score, bool highest, bool allowDuplicates, const std::string& mode, int perPage, const CustomData& customFilter)

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.

Asynchronous Version

Asynchronous request are similar to the synchronous request but you need to set a delegate that implement ILeaderboardDelegate to preocess the request.

To set the delegate you need to call

 CLeaderboard::SetDelegate(ILeaderboardDelegate* targetDelegate)

when you use the asynchronous calls you need to inherit from ILeaderboardDelegate and implement its three pure virtual methods:

class ILeaderboardDelegate
{
public:
    virtual void SaveComplete(CPlaytomicResponsePtr& result)=0;
    virtual void ListTableComple(SSCoreTable& result)=0;
    virtual void SaveAndListComple(SSCoreTable& result)=0;
};

An example

class CMyClass : public ILeaderboardDelegate
{
public:
    virtual void SaveComplete(CPlaytomicResponsePtr& result);
    virtual void ListTableComple(SSCoreTable& result);
    virtual void SaveAndListComple(SSCoreTable& result);
            void CallAsyncRequest();
};

void MyClass::CallAsyncRequest()
{
    CustomData filter;
	CScore scoreData;
    gPlaytomic->Leaderboards()->SetDelegate(this);
    scoreData.SetDefaultValues("Player name", 100);
    gPlaytomic->Leaderboards()->SaveTableAsync("Demo Table", scoreData,true,true);
    gPlaytomic->Leaderboards()->SaveAndListTableAsync("Demo Table", scoreData,true,true,"last7days",10 , filter);
    gPlaytomic->Leaderboards()->ListTableAsync("Demo Table",true,"last7days", 1,10 , filter);
}

void MyClass::SaveComplete( CPlaytomicResponsePtr& result )
{
    if(result->ResponseSucceded())
    {
        std::cout << "new score entry success!" << std::endl;
    }
    else
    {
        std::cout << "failed to save the score!" << std::endl;
        std::cout << "error number: " << result->ResponseError() << std::endl;
    }
}

void MyClass::ListTableComple( SSCoreTable& result )
{
	if (result.sSucceded)
    {
        std::cout << std::endl << std::endl << "scoretable"
                  << " page: 0" << std::endl << std::endl;
        std::list<CScore>::iterator it = result.sScoreList.begin();
        for (; it != result.sScoreList.end(); it++)
        {
            std::cout << "name: " << it->GetName() << " Score: "
                      << (int)(it->GetPoints()) << "Rank: " << it->GetRank() 
                      << "date: "<< it->GetRelativeDate() << std::endl;
        }
	}
}

void MyClass::SaveAndListComple( SSCoreTable& result )
{
    if (result.sSucceded)
    {
        std::cout << std::endl << std::endl << "scoretable"
                  << " page: 0" << std::endl << std::endl;
        std::list<CScore>::iterator it = result.sScoreList.begin();
        for (; it != result.sScoreList.end(); it++)
        {
            std::cout << "name: " << it->GetName() << " Score: " 
                      << (int)(it->GetPoints()) << "Rank: " << it->GetRank() 
                      << "date: " << it->GetRelativeDate() << std::endl;
        }
    }
    else
    {
        std::cout << "failed to save the score!" << std::endl;
        std::cout << "error number: " << result.sErrorCode << std::endl;
    }
}

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();
GameVars()->LoadAsync(RequestDelegate targetDelegate);

The targetDelegate parameter is your function that receives a CPlaytomicResponsePtr reference

// our variables with default, original values
int gBaseHitPoints = 100;
int gBaseGold = 50;

void InitialiseGame()
{
   // load GameVars
   CPlaytomicResponsePtr response = gPlaytomic->GameVars()->Load();
   if (response->ResponseSucceded())
   {
        FData array;
        array = response->ResponseData();
        if(array.size() == 0)
        {
            std::cout << " empty game vars" << std::endl;
            break;
        }
        else
        {
            FData value;
            for (size_t i = 0; i < array.size(); i++)
            {
                value = array[i];
                FData name;
                name = value.get("Name", name);
                FData varValue;
                varValue = value.get("Value",varValue);
                
                std::cout << name.asString() << "=" << varValue.asString() << std::endl; 
            }
        }
   }
   // carry on initializing your game
}

Asynchronous Version

// our variables with default, original values
int gBaseHitPoints = 100;
int gBaseGold = 50;

void InitialiseGame()
{
   // load GameVars
   gPlaytomic->GameVars()->LoadAsync(fastdelegate::MakeDelegate(this,&MyClass::GameVarsDelegate));
   
    // carry on initializing your game
}

void MyClass::GameVarsDelegate(CPlaytomicResponsePtr& response)
{
   if (response->ResponseSucceded())
   {
        FData array;
        array = response->ResponseData();
        if(array.size() == 0)
        {
            std::cout << " empty game vars" << std::endl;
            break;
        }
        else
        {
            FData value;
            for (size_t i = 0; i < array.size(); i++)
            {
                value = array[i];
                FData name;
                name = value.get("Name", name);
                FData varValue;
                varValue = value.get("Value",varValue);
                
                std::cout << name.asString() << "=" << varValue.asString() << std::endl; 
            }
        }
   }
}

Geolocation

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

It is called via:

GeoIP()->Load();
GeoIP()->LoadAsync(RequestDelegate targetDelegate)

The delegate method receives a CPlaytomicResponsePtr reference with an object that has Code and Name properties:

Example

void MyClass::GetLocation()
{
    response = Playtomic::gPlaytomic->GeoIP()->Load();

    if (response->ResponseSucceded())
    {
        FData geoIpInfo;
        geoIpInfo = response->ResponseData();
        
        FData code,name;
        code = geoIpInfo.get("Code",code);
        name = geoIpInfo.get("Name", name);
        
        std::cout << "Code: " << code.asString() << std::endl;
        std::cout << "Name: " << name.asString() << std::endl;
     }
}

Asynchronous Version

void MyClass::GetLocation()
{
   Playtomic::gPlaytomic->GeoIP()->LoadAsync(fastdelegate::MakeDelegate(this,&MyClass::LocationDelegate));
}

void MyClass:::LocationDelegate(CPlaytomicResponsePtr& response)
{
    if (response->ResponseSucceded())
    {
	    FData geoIpInfo;
        
        geoIpInfo = response->ResponseData();
        
        FData code,name;
        code = geoIpInfo.get("Code",code);
        name = geoIpInfo.get("Name", name);
        
        std::cout << "Code: " << code.asString() << std::endl;
        std::cout << "Name: " << name.asString() << std::endl;
    }
}

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:

Synchronous Version

Data()->Views(int month = 0, int year= 0);
Data()->Views(int day, int month, int year);

Data()->Plays(int month = 0, int year= 0);
Data()->Plays(int day, int month, int year);

Data()->Playtime(int month = 0, int year= 0);
Data()->Playtime(int day, int month, int year);

Asynchronous Version

Data()->ViewsAsync(RequestDelegate targetDelegate);
Data()->ViewsAsync(int day, int month, int year, RequestDelegate targetDelegate);
Data()->ViewsAsync(int month, int year, RequestDelegate targetDelegate);

Data()->PlaysAsync(RequestDelegate targetDelegate);
Data()->PlaysAsync(int day, int month, int year, RequestDelegate targetDelegate);
Data()->PlaysAsync(int month, int year, RequestDelegate targetDelegate);

Data()->PlaytimeAsync(RequestDelegate targetDelegate);
Data()->PlaytimeAsync(int day, int month, int year, RequestDelegate targetDelegate);
Data()->PlaytimeAsync(int month, int year, RequestDelegate targetDelegate);

gPlaytomic->Data()->ViewsAsync(fastdelegate::MakeDelegate(this,&MyClass::ViewFinish));
gPlaytomic->Data()->Plays(22,3, 2010,fastdelegate::MakeDelegate(this,&MyClass::PlaysFinish)); // plays on March 22, 2010 
gPlaytomic->Data()->PlaytimeAsync(3, 2010,fastdelegate::MakeDelegate(this,&MyClass::PlayTimeFinish)); // play time on March, 2010

void MyClass::ViewFinish(CPlaytomicResponsePtr& response)
{
    if (response->ResponseSucceded())
    {
       FData value;
       value = response->ResponseData().get("Value",value);
       std::cout << "views = " << value.asString() << std::endl;
    }
    else
    {
       std::cout << "response failed error code = " << response->ResponseError() << std::endl;
    }
}

void MyClass::PlaysFinish(CPlaytomicResponsePtr& response)
{
    if (response->ResponseSucceded())
    {
       FData value;
       value = response->ResponseData().get("Value",value);
       std::cout << "Plays = " << value.asString() << std::endl;
    }
    else
    {
       std::cout << "response failed error code = " << response->ResponseError() << std::endl;
    }
}

void MyClass::PlaytimeFinish(CPlaytomicResponsePtr& response)
{
    if (response->ResponseSucceded())
    {
       FData value;
       value = response->ResponseData().get("Value",value);
       std::cout << "play time = " << value.asString() << std::endl;
    }
    else
    {
       std::cout << "response failed error code = " << response->ResponseError() << std::endl;
    }
}

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.

Synchronous Version

Data()->CustomMetric(const std::string& name, int day=0, int month=0, int year=0);

Asynchronous Version

Data()->CustomMetric(const std::string& name, RequestDelegate targetDelegate);
Data()->CustomMetric(const std::string& name, int day, int month, int year, RequestDelegate targetDelegate);

gPlaytomic->Data()->CustomMetricAsync("Clicked sponsor link"e,fastdelegatee::MakeDelegate(thise,&CMyClasse::CustomMetricFinish));

voide CMyClasse::CustomMetricFinish( CPlaytomicResponsePtre& response )
{

   if (response->ResponseSucceded())
   {
       FDatae value;
       value = response->ResponseData().get("Value"e,value);
       std::coute << "custom metric = "e << value.asString() << std::endle;
   }
   else
   {
       std::coute << "response failed error code = " << response->ResponseError() << std::endle;
   }
}

Level metrics

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

Synchronous Version

Data()->LevelCounterMetric(const std::string& name, const std::string& level, int month=0, int year=0);
Data()->LevelCounterMetric(const std::string& name, const std::string& level,int day,int month, int year);
Data()->LevelCounterMetric(const std::string& name, int levelNumber, int month=0, int year=0);
Data()->LevelCounterMetric(const std::string& name, int levelNumber, int day,int month, int year);

Data()->LevelAverageMetric(const std::string& name, const std::string& level, int month=0, int year=0);
Data()->LevelAverageMetric(const std::string& name, const std::string& level, int day, int month, int year);
Data()->LevelAverageMetric(const std::string& name, int levelNumber, int month=0, int year=0);
Data()->LevelAverageMetric(const std::string& name, int levelNumber, int day,int month, int year);

Data()->LevelRangedMetric(const std::string& name, const std::string& level, int month=0, int year=0);
Data()->LevelRangedMetric(const std::string& name, const std::string& level, int day, int month, int year);
Data()->LevelRangedMetric(const std::string& name, int levelNumber, int month=0, int year=0);
Data()->LevelRangedMetric(const std::string& name, int levelNumber, int day,int month, int year);

gPlaytomic->Data()->LevelCounterMetricAsync("Started level","level 1",fastdelegate::MakeDelegate(this,&MyClass::LevelCounterFinish));
gPlaytomic->Data()->LevelRangedMetricAsync("Shots remaining","level 1",3,2010,fastdelegate::MakeDelegate(this,&MyClass::LevelRangedFinish));
gPlaytomic->Data()->LevelAverageMetricAsync("Retries","level 1",22,3,2010,fastdelegate::MakeDelegate(this,&MyClass::LevelAverageFinish));


void MyClass::LevelCounterFinish()
{
    if (response->ResponseSucceded())
    {
        FData value;
        value = response->ResponseData().get("Value",value);
        std::cout << "level counter = " << value.asString() << std::endl;
    }
    else
    {
        std::cout << "response failed error code = " << response->ResponseError() << std::endl;
    }
}

void MyClass::LevelRangedFinish()
{
    if (response->ResponseSucceded())
    {
        FData value;
        value = response->ResponseData().get("Value",value);
        std::cout << "level ranged = " << value.asString() << std::endl;
    }
    else
    {
        std::cout << "response failed error code = " << response->ResponseError() << std::endl;
    }
}

void MyClass::LevelAverageFinish()
{
    if (response->ResponseSucceded())
    {
        FData value;
        value = response->ResponseData().get("Average",value);
        if(value.isInt())
            std::cout << "level Average = " << value.asInt() << std::endl;
        value = response->ResponseData().get("Min",value);
        if(value.isInt())
            std::cout << "level Min = " << value.asInt() << std::endl;
        value = response->ResponseData().get("Max",value);
        if(value.isInt())
            std::cout << "level Max = " << value.asInt() << std::endl;
        value = response->ResponseData().get("Total",value);
        if(value.isInt())
           std::cout << "level Total = " << value.asInt() << std::endl; 
     }
}

ErrorCodes

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.

GeoIP errors

Leaderboard errors

GameVars errors

Level sharing errors

Data API errors