Main

Advanced Setup Guide

Get the complete experience. Follow this Advanced Setup Guide to get the most out of Katana Analytics. This guide includes the information you need to log all available events, including events custom to your title. You'll find the events are organized based on 10 primary event categories:

System Events System events include those events that are system related, such as when a player logs in or out of the application, or when a shard is initialized.

Account Management Events Account Management events include those events that are related to the creation, deletion, and management of a user or character account.

Game Events Game events include those events that are related to in-game characters, actions, and combat.

Item Events# Item events include those events that are related to the creation, use, and transaction of in- game items.

Group Events Group events include those events involving player interaction with a group or guild such as entry, exit, or a player's position within a guild (e.g. Guild Leader).

Environment Events Environment events include those events that are related to in-game levels and areas that players may encounter.

Economic Events Economic events include those events that are related to in-game stores and purchases such as a player's interaction with a store and items within it.

Transaction Events Transaction events include those events that are related to economic events outside of the game such as when an item is purchased outside of the developer game store, or when a subscription changes.

Social Events Social events include social interactions between players in and outside of the game such as messages, off-game-interactions, friend requests, etc.

Custom Events Custom events include those events that relate to custom actions, and CRM actions. As a Ninja Metrics customer you have the freedom to define custom events in any way that you want given the fields described under the Custom Slot Action and Custom Action sections.

System Events

System events include those events that are system related, such as when a player logs in or out of the application, or when a shard is initialized. Details on how to execute calls to log system events can be found below for each corresponding event.

Login (Event ID#1)

This event records the time at which the user logged into the system (website, game, software, etc.). To log a login event, you need to pass the user's account ID, character ID, platform, and timestamp. Optionally, you may pass the shard ID, and login area name and ID.

Impacted UI Features

  • KPI
  • System Metrics (Items, Location/Maps, NPC, Social)
  • User Metrics (Churn, Farming, Integrity)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
StringplatformOther
Longarea_idNull
Stringarea_nameNull

Sample Use

  • Java

//Log when a user logs in
public void aKApi.logLogin(timestamp, account_id, character_id, shard_id, platform, area_id, area_name);

  • JavaScript

//Log when a user logs in
aKApi.logLogin(timestamp, account_id, character_id, shard_id, platform, area_id, area_name);

  • PHP

//Log when a user logs in
$aKApi->logLogin(timestamp, account_id, character_id, shard_id, platform, area_id, area_name);

  • JSON

//Log when a user logs in

        {
                "timestamp":"2013-11-14T13:43:06.308Z",
                 "data":{
                        "type":1,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
                        "platform":"Facebook Mobile",
                        "area_id":0,
                        "area_name":0
                }
        }

NOTE: All parameters are required in JSON, except "shard_id", "area_id" and "area_name" which are optional.

Back to Top


Logout (Event ID#2)

This event records the time at which the user logged out of the system (website, game, software, etc.). To log a logout event, you need to pass the user's account ID, character ID, and timestamp.

Impacted UI Features

  • KPI
  • User Metrics (Churn, Farming, Integrity)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id

Sample Use

  • Java

//Log when a user logs out
public void aKApi.logLogout(timestamp, account_id, character_id);

  • JavaScript

//Log when a user logs out
aKApi.logLogout(timestamp, account_id, character_id);

  • PHP

//Log when a user logs out
$aKApi->logLogout(timestamp, account_id, character_id);

  • JSON

//Log when a user logs out

        {
                "timestamp":"2013-11-14T13:51:53.035Z",
                "data":{
                        "type":2,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Initialize Shard (Event ID#13)

Many games and environments have multiple instances running in parallel. In our schema, these parallel instances are referred to as shards. Shards are the same as running multiple instances of the game, or other environments, on different servers. To initialize a shard, you need to pass the shard ID and description, as well as a timestamp.

Note: You must log the shard creation information before any log or load command references the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Longshard_idNo Default Value
Stringshard_descNA

Sample Use

  • Java

//Log shard creation information
public void aKApi.loadInitShard(timestamp, shard_id, shard_desc);

  • JavaScript

//Log shard creation information
aKApi.loadInitShard(timestamp, shard_id, shard_desc);

  • PHP

//Log shard creation information
$aKApi->loadInitShard(timestamp, shard_id, shard_desc);

  • JSON

//Log shard creation information

        {
                "timestamp":"2013-11-14T16:15:08.347Z",
                "data":{
                        "type":13,
                        "shard_id":42,
                        "shard_desc":"the shard with answers to it all"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Account Management Events

Account Management events include those events that are related to the creation, deletion, and management of a user or character account. Details on how to execute calls to log account events can be found below for each corresponding event.

Create Account (Event ID#9)

This event records information regarding the creation of a new account, including the user's demographics. To log the creation of an account you need to pass the account ID and type; the user's language, country, gender, and date of birth; as well as the platform and the timestamp. Optionally, you may pass their currency balance and old account ID.

Note: You must log the account creation information before any log or load command references the account ID.

Impacted UI Features

  • KPI
  • User Metrics (Churn, Farming, Integrity)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_id"No Default Value"
Stringaccount_sub_typeFree
Stringaccount_langN0
Stringaccount_countryN0
Stringaccount_genderN
Dateaccount_dob"1900-01-01T00:00:00.000Z"
Floataccount_currency_balance0
StringplatformOther
Stringold_account_idNull

Sample Use

  • Java

//Log when a user creates an account
public void aKApi.loadAccountCreate(timestamp, account_id, account_sub_type, account_lang, account_country, account_gender, account_dob, platform, account_currency_balance, old_account_id);

  • JavaScrip

//Log when a user creates an account
aKApi.loadAccountCreate(timestamp, account_id, account_sub_type, account_lang, account_country, account_gender, account_dob, platform, account_currency_balance, old_account_id);

  • PHP

//Log when a user creates an account
$aKApi->loadAccountCreate(timestamp, account_id, account_sub_type, account_lang, account_country, account_gender, account_dob, platform, account_currency_balance, old_account_id);

  • JSON

//Log when a user creates an account

       {
                "timestamp":"2013-11-14T15:18:30.726Z",
                "data":{
                        "type":9,
                        "account_id":"cool_guy@example.com",
                        "account_sub_type":"Free",
                        "account_lang":"NA",
                        "account_country":"de",
                        "account_gender":"N",
                        "account_dob":"1900-01-01T00:00:00.000Z",
                        "account_currency_balance":55,
                        "platform":"Social",
                        "old_account_id":"small_cat@example.com"
                }
        }	

NOTE: All parameters are required in JSON, except "account_currency_balance_" and "old_account_id" which are optional.

Back to Top


Delete Account (Event ID#10)

This event records information regarding account deletion, including reasoning for deletion, in terms of churn or account compromise. To log the deletion of an account you need to pass the account ID, churn type, and timestamp.

Impacted UI Features

  • KPI
  • User Metrics (Churn, Farming, Integrity)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringaccount_statusStopped

Sample Use

  • Java

//Log when a user deletes an account
public void aKApi.loadAccountDeleted(timestamp, account_id, account_status);

  • JavaScript

//Log when a user deletes an account
aKApi.loadAccountDelete(timestamp, account_id, account_status);

  • PHP

//Log when a user deletes an account
$aKApi->loadAccount''Delete(timestamp, account_id, account_status);

  • JSON

//Log when a user deletes an account

        {
                "timestamp":"1989-08-15T05:00:00.000Z",
                "data":{
                        "type":10,
                        "account_id":"cool_guy@example.com",
                        "account_status":"Failed"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Create Character (Event ID#11)

Relates to the creation of characters or aliases within the game, where the character's attributes may vary from the attributes of the person in the real world. Once a character is created their attributes are usually fixed. To log a character creation, you need to pass the character and account IDs; the character class, subclass, gender, race, and name; along with the timestamp. Optionally, you may pass the shard ID.

Note: You must log the character creation information before any log or load command references the character ID.

Impacted UI Features

  • KPI

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Stringcharacter_classNA
Stringcharacter_sub_classNA
Stringcharacter_genderMust be 'M' or 'F' or 'N'
Stringcharacter_raceNA
Stringcharacter_nameNA
Longshard_id0

Sample Use

  • Java

//Log the creation of a character
public void aKApi.loadCharacterCreate(timestamp, account_id, character_id, character_class, character_sub_class, character_gender, character_race, character_name, shard_id);

  • JavaScript

//Log the creation of a character
aKApi.loadCharacterCreate(timestamp, account_id, character_id, character_class, character_sub_class, character_gender, character_race, character_name, shard_id);

  • PHP

//Log the creation of a character
$aKApi->loadCharacterCreate(timestamp, account_id, character_id, character_class, character_sub_class, character_gender, character_race, character_name, shard_id);

  • JSON

//Log the creation of a character

        {
                "timestamp":"2013-11-14T15:47:36.202Z",
                "data":{
                        "type":11,
                       "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "character_class":"magic",
                        "character_sub_class":"healer",
                        "character_gender":"N",
                        "character_race":"fish",
                        "character_name":"small_fish",
                        "shard_id":0
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Delete Character (Event ID#12)

This event records information regarding the deletion of a character. To log a character deletion, you need to pass the character ID, account ID, and timestamp.

For related information, see Create Character.

Impacted UI Features

  • KPI

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idNo Default Value

Sample Use

  • Java

//Log the deletion of a character
public void aKApi.loadCharacterDelete(timestamp , account_id, character_id);

  • JavaScript

//Log the deletion of a character
aKApi.loadCharacterDelete(timestamp , account_id, character_id);

  • PHP

//Log the deletion of a character
$aKApi->loadCharacterDelete(timestamp , account_id, character_id);

  • JSON

//Log the deletion of a character

        {
                "timestamp":"2013-11-14T16:03:13.367Z",
                "data":{
                        "type":12,
                        "account_id":"cool_guy@example.com",
		       "character_id":"Wizard"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Game Events

Game events include those events that are related to in-game characters, actions, and combat. Details on how to execute calls to log game events can be found below for each corresponding event.

Begin Combat (Event ID#21)

This event records information regarding the beginning of combat between a player and a non-player character (NPC). To log when a player begins combat, you need to pass the account and character IDs; the NPC ID; the area ID, name and position; as well as the timestamp. Optionaly, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longnpc_idNo Default Value
Longarea_id0
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameNA

Sample Use

  • Java

//Log when a combat event begins
public void aKApi.combatStart(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a combat event begins
aKApi.combatStart(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • PHP

//Log when a combat event begins
$aKApi->combatStart(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • JSON

//Log when a combat event begins

        {
                "timestamp":"2013-11-14T18:55:58.241Z",
                "data":{
                        "type":21,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
                        "npc_id":23456,
                        "area_id":552,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


End Combat (Event ID#22)

This event records information regarding the end of combat between a player and a non- player character (NPC). To log when a player ends combat, you need to pass the account and character IDs; the NPC ID; the area ID, name, and position; as well as the timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longnpc_idNo Default Value
Longarea_id0
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameNA

Sample Use

  • Java

//Log when a combat event ends
public void aKApi.combatEnd(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a combat event ends
aKApi.combatEnd(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • PHP

//Log when a combat event ends
$aKApi->combatEnd(timestamp, account_id, character_id, shard_id, npc_id, area_id, position_x, position_y, position_z, area_name);

  • JSON

//Log when a combat event ends

        {
                "timestamp":"2013-11-15T12:41:31.575Z",
                "data":{
                        "type":22,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "shard_id":42,
                        "npc_id":23456,
                        "area_id":552,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Kill (NPC) (Event ID#23)

This event records when a non-player character (NPC) is killed by a player in the game. To log an NPC kill, you need to pass the account and character ID, the character level, the killed NPC ID, and the timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longcharacter_lvl0
Longnpc_idNo Default Value

Sample Use

  • Java

//Log when an NPC is killed
public void aKApi.logKillNpc(timestamp, account_id, character_id, shard_id, character_lvl, npc_id);

  • JavaScript

//Log when an NPC is killed
aKApi.logKillNpc(timestamp, account_id, character_id, shard_id, character_lvl, npc_id);

  • PHP

//Log when an NPC is killed
$aKApi->logKillNpc(timestamp, account_id, character_id, shard_id, character_lvl, npc_id);

  • JSON

//Log when an NPC is killed
{

                "timestamp":"2013-11-15T13:08:45.954Z",
                "data":{
                        "type":23,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "shard_id":52,
                        "character_lvl":42,
                        "npc_id":23456
                }
        }

NOTE: All parameter are required in JSON, except "shard_id" which is optional.

Back to Top


Player Points (Event ID#24)

This event records information regarding when a player gains points in the game. Points are used as an indicator of how well the player is doing in the game and how far they have progressed. Typically, gaining enough points leads the player to level-up to a higher level. To log player points, you need to pass the account and character IDs, the character level, the point amount and type, along with the timestamp. Optionally, you may pass the shard ID and whether or not the points are grouped.

Impacted UI Features

  • System Metrics (Levels)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvlIf Generic Character then Account Level; If no concept of Levels then 0.
Longshard_id0
Longpoint_typeDefault = XP, {XP, GENERIC_POINTS, OTHER}
Longxp_amountNo Default Value
Booleangrouped_flagN

*Point Type default is XP, alternate options include 'Generic Point', and 'Other'.

Sample Use

  • Java

//Log player XP
public void aKApi.playerXp(timestamp, account_id, character_id, character_lvl, shard_id, point_type, xp_amount, grouped_flag);

  • JavaScript

//Log player XP
aKApi.playerXp(timestamp, account_id, character_id, character_lvl, shard_id, point_type, xp_amount, grouped_flag);

  • PHP

//Log player XP
$aKApi->playerXp(timestamp, account_id, character_id, character_lvl, shard_id, point_type, xp_amount, grouped_flag);

  • JSON

//Log player XP

        {
                "timestamp":"2013-11-15T13:17:01.847Z",
                "data":{
                        "type":24,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "character_lvl":1,
                        "shard_id":42,
                        "point_type":"XP"
                        "xp_amount":34,
                        "grouped_flag":"Y"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" and "grouped_flag" which are optional.

Back to Top


Player Versus Player (PVP) Duel (Event ID#25)

Please use Social Interactions Event #6 to record Player Versus Player actions. This event records information when a player enters into combat against another player. Note that this event is only applicable for games and environments where a player is able to fight another player. To log a PVP duel, you need to pass the account and character IDs, the timestamp, and whether or not the player won. Optionally, you may pass the shard ID. Parameters || border=1 rules=rows frame=hsides ||! Type ||! Parameter ||! Default Value || || Date || PVP DUEL TIMESTAMP || (Current Time) || || String || ACCOUNT ID || No Default Value || || String || CHARACTER ID || ACCOUNT ID || || Long || SHARD ID || 0 || || Boolean || WIN FLAG || No Default Value || Sample Use *Java //Log a PVP Duel
public void aKApi.logPvpDuel(PVP_DUEL_TIMESTAMP, ACCOUNT_ID, CHARACTER_ID, SHARD_ID, WIN_FLAG); *JavaScript //Log a PVP Duel
aKApi.logPvpDuel(PVP_DUEL_TIMESTAMP, ACCOUNT_ID, CHARACTER_ID, SHARD_ID, WIN_FLAG); *PHP //Log a PVP Duel
$aKApi->logPvpDuel(PVP_DUEL_TIMESTAMP, ACCOUNT_ID, CHARACTER_ID, SHARD_ID, WIN_FLAG); *JSON //Log a PVP Duel
{ "timestamp":"2013-11-15T13:26:39.832Z", "data":{

                        "type":25,

"account_id":"cool_guy@example.com", "character_id":"Wizard", "shard_id":42, "win_flag":"Y" } } NOTE: All parameters are required in JSON, except "shard_id" which is optional

Back to Top


Player Death (Event ID#26)

This event records information regarding the death of a player by a non-player character (NPC). To log a player death, you need to pass the account and character IDs; the Area ID and name; the NPC ID; the position; the type of death; and the timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longnpc_idNo Default Value
Stringdeath_typeNA
Longarea_id0
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameNA

Sample Use

  • Java

//Log a player death
public void aKApi.logPlayerDeath(timestamp, account_id, character_id, shard_id, npc_id, death_type, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log a player death
aKApi.logPlayerDeath(timestamp, account_id, character_id, shard_id, npc_id, death_type, area_id, position_x, position_y, position_z, area_name);

  • PHP

//Log a player death
$aKApi->logPlayerDeath(timestamp, account_id, character_id, shard_id, npc_id, death_type, area_id, position_x, position_y, position_z, area_name);

  • JSON

//Log a player death

        {
                "timestamp":"2013-11-15T13:32:33.452Z",
                "data":{
                        "type":26,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
                        "npc_id":23456,
                        "death_type":"Immolation",
                        "area_id":512,
                        "position_x":678,
                        "position_y":231, 
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameter are required in JSON, except "shard_id" which is optional.

Back to Top


Non-Player Character (NPC) (Event ID#31)

Non-player characters (NPCs) are characters within the game that are not controlled by players. They have different levels of difficulty and may be either friendly or aggressive. This event records information regarding interactions between NPCs and players in the game environment. Recording NPC's also populates the dimension table for NPCs, which is later referred to for all other NPC related events. To log NPC events, you need to pass the account and character IDs; the NPC ID, name, and type; the event type and name; along with the toughness and timestamp. Optionally, you may pass the shard ID, and the minimum and maximum levels.

Impacted UI Features

  • KPI
  • System Metrics (NPC)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Stringnpc_event_nameNo Default Value
Stringnpc_event_typeNo Default Value
Stringnpc_idIf NPC ID is empty, and NPC Name is not empty, use 0.
Stringnpc_nameIf NPC ID is not empty, and NPC Name is empty, use NA.
Stringnpc_typeOther
Integernpc_level_minSet as Optional, with Null value
Integernpc_level_maxSet as Optional, with Null value
Integernpc_toughnessSet as Optional, with Null value
Stringnpc_toughness_enumSet as Optional, with Null value

Sample Use

  • Java

//Log an NPC event occurred
public void aKApi.logNpcInteraction(timestamp, account_id, character_id, shard_id, npc_event_name, npc_event_type, npc_id, npc_name, npc_type, npc_level_min, npc_level_max, npc_toughness, npc_toughness_enum);

  • JavaScript

//Log an NPC event occurred
aKApi.logNpcInteraction(timestamp, account_id, character_id, shard_id, npc_event_name, npc_event_type, npc_id, npc_name, npc_type, npc_level_min, npc_level_max, npc_toughness, npc_toughness_enum);

  • PHP

//Log an NPC event occurred
$aKApi->logNpcInteraction(timestamp, account_id, character_id, shard_id, npc_event_name, npc_event_type, npc_id, npc_name, npc_type, npc_level_min, npc_level_max, npc_toughness, npc_toughness_enum);

  • JSON

//Log an NPC event occurred

        {
                "timestamp":"2013-11-15T14:22:57.102Z",
                "data":{
                        "type":31,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "shard_id":42,
                        "npc_event_name":"npcEventName",
                        "npc_event_type":"Combat",
                        "npc_id":2345,
                        "npc_name":"the Mort of T",
                        "npc_type":"Enemy",
                        "npc_level_min":5,
                        "npc_level_max":10,
                        "npc_toughness":0.25,
                        "npc_toughness_enum":"Quarter"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id", "npc_level_min", and "npc_level_max" which are optional.

Back to Top


Challenge (Event ID#32)

Challenges, sometimes referred to as Quests, are elements of the game where a player, or group of players, can perform tasks for a reward or opportunity to level-up within the game. This event records information regarding challenges. To log a challenge event, you need to pass the account and character IDs; the challenge ID, type, and status; along with the timestamp. Optionally, you may pass the shard ID.

Impacted UI Features

  • KPI

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Stringchallenge_idNo Default Value
Stringchallenge_typeOther (See Appendix A for more types)
Stringchallenge_statusAccepted*

*The Challenge Status default is 'Accepted', but alternate options include 'Completed', or 'Abandoned'.

Sample Use

  • Java

//Log a challenge event occurred
public void aKApi.logChallenge(timestamp, account_id, character_id, shard_id, challenge_id, challenge_type, challenge_status);

  • JavaScript

//Log a challenge event occurred
aKApi.logChallenge(timestamp, account_id, character_id, shard_id, challenge_id, challenge_type, challenge_status);

  • PHP

//Log a challenge event occurred
$aKApi->logChallenge(timestamp, account_id, character_id, shard_id, challenge_id, challenge_type, challenge_status);

  • JSON

//Log a challenge event occurred

        {
                "timestamp":"2013-11-15T14:31:40.633Z",
                "data":{
                        "type":32,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
                        "challenge_id":"challenge_Id",
                        "challenge_type":"Kill NPC",
                        "challenge_status":"Abandonded"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Item Events

Item events include those events that are related to the creation, use, and transaction of in-game items. Details on how to execute calls to log item events can be found below for each corresponding event.

Initialize Item (Event ID#15)

This event records information regarding virtual items in the game. Such items may be made available by non-player characters, or they may be created by players in the game. Initializing an item also initializes the dimension table for the item, which is later referred to for all other item related events. To initialize an item, you need to pass the item ID, name, type, and segment, as well as the timestamp. Optionally, you may pass the account and character IDs of the creator.

Note: You must log the item creation information before any log or load command references the item ID.
Note: item_type may be any string, but use it consistently. some examples: "Raw materials", "Mounts and pets", "armor", "tools", "containers"
Note: item_value is a floating point value which would be used for the store price of the item
Note: item_segment may be "UGC" when the item is user-generated or "INGAME" when part of the original application
Note: IF the item_segment field is "UGC" then the creator_account_id and creator_character_id fields should be set appropriately, otherwise they should be empty strings

Impacted UI Features

  • KPI
  • System Metrics (Items)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Longitem_id0
Stringitem_nameNA
Stringitem_typeOther (See Appendix for more types)
Stringitem_segment"UGC or INGAME"
Stringaccount_idIf ITEM_SEGMENT=UGC, then Required.
Stringcharacter_idIf ITEM_SEGMENT=UGC, then account_id

Sample Use

  • Java

//Log item creation information
public void aKApi.loadInitItem(timestamp, item_id, item_name, item_type, item_segment, account_id, character_id);

  • JavaScript

//Log item creation information
aKApi.loadInitItem(timestamp, item_id, item_name, item_type, item_segment, account_id, character_id);

  • PHP

//Log item creation information
$aKApi->loadInitItem(timestamp, item_id, item_name, item_type, item_segment, account_id, character_id);

  • JSON

//Log item creation information

        {
		"timestamp":"2013-11-14T17:11:33.720Z",
		"data":{
		"type":15,
		"item_id":66,
		"item_name":"the big blaster gun",
		"item_type":"weapon",
		"item_segment":"UGC",
		"account_id":"cool_guy@example.com",
		"character_id":"Wizard"
		}

}

NOTE: All parameters are required in JSON, except "account_id" and "character_id" which are optional.

Back to Top


Item Used (Event ID#16)

This event records information regarding the usage of items in the game, such as the usage location, and includes account and character information for the user who used the item. To log an item's use, you need to pass the account and character IDs; the character level; the item ID, name, and count; the area ID, name, and position; as well as the timestamp. Optionally, you may pass the shard ID.

Impacted UI Features

  • KPI
  • System Metrics (Items)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvlIf Generic Character then Account Level; If no concept of levels then 0.
Longshard_id0
Longitem_idIf ITEM_ID is empty and ITEM_NAME is not empty, use 0.
Stringitem_nameIf ITEM_ID is not empty and ITEM_NAME is empty, use NA.
Integeritem_countNo Default Value
Longarea_id0
Stringarea_nameNA
Floatposition_x0
Floatposition_y0
Floatposition_z0

Sample Use

  • Java

//Log that an item was used
public void aKApi.logItem(timestamp, account_id, character_id, character_lvl, shard_id,item_id, item_name, item_count, area_id, area_name, position_x, position_y, position_z);

  • JavaScript

//Log that an item was used
aKApi.logItem(timestamp, account_id, character_id, character_lvl, shard_id,item_id, item_name, item_count, area_id, area_name, position_x, position_y, position_z);

  • PHP

//Log that an item was used
$aKApi->''logItem(timestamp, account_id, character_id, character_lvl, shard_id, item_id, item_name, item_count, area_id, area_name, position_x, position_y, position_z);

  • JSON

//Log that an item was used

        {
                "timestamp":"2013-11-14T17:42:49.185Z",
                "data":{
                        "type":16,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "character_lvl":52,
                        "shard_id":42,
                        "item_id":66,
                        "item_name":"The Blaster Gun",
                        "item_count":1,
                        "area_id":42,
                        "area_name":"Area_Name",
                        "position_x":678,
                        "position_y":231,
                        "position_z":517
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Social Group Events

Group events include those events involving player interaction with a group or guild, such as entry, exit, or a player's position within a guild (e.g. Guild Leader). A guild is analogous to an organization in many online games. Details on how to execute calls to log group events can be found below for each corresponding event.

Social Group Enter (Event ID#4)

This event records the time at which a user joins a group. In this case, groups are likely to be impermanent. Note that grouping is not applicable for solo games. To log a user's entry into a group you need to pass the account, character, and group IDs; the character level, and timestamp of entry. Optionally, you may pass the shard ID.

Impacted UI Features

  • System Metrics (Social)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longgroup_idNo Default Value

Sample Use

  • Java

//Log when a user enters a group
public void aKApi.logEnterGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • JavaScript

//Log when a user enters a group
aKApi.logEnterGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • PHP

//Log when a user enters a group
$aKApi->logEnterGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • JSON

//Log when a user enters a group

        {
                "timestamp":"2013-11-14T14:10:36.792Z",
                "data":{
                        "type":4,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "character_lvl":50,
                        "shard_id":42,
                        "group_id":42
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Social Group Exit (Event ID#5)

This event records the time at which a user leaves a group. To log a user's exit from a group you need to pass the account, character, and group IDs; the character level; and timestamp of exit. Optionally, you may pass the shard ID>

For related information, see Group Enter.

Impacted UI Features

  • System Metrics (Social)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longgroup_idNo Default Value

Sample Use

  • Java

//Log when a user exits a group
public void aKApi.logExitGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • JavaScript

//Log when a user exits a group
aKApi.logExitGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • PHP

//Log when a user exits a group
$aKApi->logExitGroup(timestamp, account_id, character_id, character_lvl, shard_id, group_id);

  • JSON

//Log when a user exits a group
{

                "timestamp":"2013-11-14T14:16:15.375Z",
                "data":{
                        "type":5,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "character_lvl":50,
                        "shard_id":42,
                        "group_id":42
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Enter Guild (Event ID#41)

This event records information regarding when a player becomes part of a guild and whether they are the leader of the guild, or not. To log a player's entry into a guild, you need to pass the user's account ID, character ID, character level, guild ID, along with the time of entry. Optionally, you can pass their shard ID.

Impacted UI Features

  • System Metrics (Social)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longguild_idNo Default Value

Sample Use

  • Java

//Log when a player enters a guild
public void aKApi.logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id);

  • JavaScript

//Log when a player enters a guild
aKApi.logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id);

  • PHP

//Log when a player enters a guild
$aKApi->logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id);

  • JSON

//Log when a player enters a guild

        {
                "timestamp":"2013-11-15T16:21:24.890Z",
                "data":{
                        "type":41,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "character_lvl":52,
                        "shard_id":1,
                        "guild_id":42
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Exit Guild (Event ID#42)

This event records information regarding exiting a guild, including the guild exited and reason for leaving such as being evicted, leaving voluntarily, etc. To log a player's exit from a guild, you need to pass the user's account ID, character ID, character level, guild ID, along with the time of entry and reason for exiting the guild. Optionally, you can pass their shard ID.

Impacted UI Features

  • System Metrics (Social)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longguild_idNo Default Value
Stringguild_exit_reasonNA

Sample Use

  • Java

//Log when and why a player exits a guild
public void aKApi.logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id, guild_exit_reason);

  • JavaScript

//Log when and why a player exits a guild
aKApi.logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id, guild_exit_reason);

  • PHP

//Log when and why a player exits a guild
$aKApi->logEnterGuild(timestamp, account_id, character_id, character_lvl, shard_id, guild_id, guild_exit_reason);

  • JSON

//Log when and why a player exits a guild

        {
                "timestamp":"2013-11-15T17:28:35.133Z",
                "data":{
                        "type":42,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "character_lvl":52,
                        "shard_id":1,
                        "guild_id":42,
                        "guild_exit_reason":"hacking"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Guild Leader (Event ID#45)

This event records information regarding a player's position within a guild (i.e. whether they are the leader of a guild, and if so, which guild). To log if a player is a guild leader, you need to pass the user's account ID, character ID, guild ID, along with the timestamp.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longguild_idNo Default Value

Sample Use

  • Java

//Log if a player is a guild leader
public void aKApi.putGuildLeader(timestamp, account_id, character_id, guild_id);

  • JavaScript

//Log if a player is a guild leader
aKApi.putGuildLeader(timestamp, account_id,character_id, guild_id);

  • PHP

//Log if a player is a guild leader
$aKApi->putGuildLeader(timestamp, account_id, character_id, guild_id);

  • JSON

//Log if a player is a guild leader

        {
                "timestamp":"2013-11-15T17:45:12.627Z",
                "data":{
                        "type":45,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "guild_id":777
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Environment Events

Environment events include those events that are related to in-game levels and areas that players may encounter. Details on how to execute calls to log environment events can be found below for each corresponding event.

Level Begin (Event ID#27)

This event records information regarding the time at which a player begins a level. To log when a player begins a level, you need to pass the account and character ID, the character level, the area ID and name, the position, and the timestamp. Optionally, you may pass the shard ID.

Note that if there is no concept of levels in your application this event need not be used.

Impacted UI Features

  • KPI
  • System Metrics (Levels)
  • User Metrics (Churn)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvlIf Generic Character then Account Level.
Longshard_id0
Longarea_id0
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameNA

Sample Use

  • Java

//Log when a player begins a level
public void aKApi.levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a player begins a level
aKApi.levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • PHP

//Log when a player begins a level
$aKApi->levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JSON

//Log when a player begins a level

        {
                "timestamp":"2013-11-15T13:41:08.559Z",
                "data":{
                        "type":27, 
                        "account_id":"cool_guy@example.com", 
                        "character_id":"Wizard", 
                        "character_lvl":52, 
                        "shard_id":42, 
                        "area_id":2,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Level End (Event ID#28)

This event records information regarding the time at which a player ends or completes a level. To log when a player ends a level, you need to pass the account and character ID, the character level, the area ID and name, the position, and the timestamp. Optionally, you may pass the shard ID.

Note that if there is no concept of levels in your application this event need not be used.

Impacted UI Features

  • KPI
  • System Metrics (Levels)
  • User Metrics (Churn)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvlIf Generic Character then Account Level.
Longshard_id0
Longarea_id0
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameNA

Sample Use

  • Java

//Log when a player begins a level
public void aKApi.levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a player begins a level
aKApi.levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • PHP

//Log when a player begins a level
$aKApi->levelBegin(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JSON

//Log when a player ends a level

        {
                "timestamp":"2013-11-15T13:50:42.553Z",
                "data":{
                        "type":28,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "character_lvl":52,
                        "shard_id":42,
                        "area_id":2,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Enter Area (Event ID#29)

An Area refers to a geographical area or region that makes up a larger virtual world. This event records information regarding the time at which a player enters an area. To log when a player enters an area, you need to pass the account and character IDs; area ID, level, and position; and the timestamp. Optionally, you may pass the shard ID.

Impacted UI Features

  • KPI - Optional
  • System Metrics (Location/Maps)
  • User Metrics (Farming)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longarea_idIf AREA_ID is not empty, and AREA_NAME is empty, set AREA_NAME=NA.
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameIf AREA_ID is not empty, and AREA_NAME is empty, set AREA_NAME=NA.

Sample Use

  • Java

//Log when a player enters an area
public void aKApi.logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a player enters an area
aKApi.logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name)

  • PHP

//Log when a player enters an area
$aKApi->logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name)

  • JSON

//Log when a player enters an area

        {
                "timestamp":"2013-11-15T14:04:32.369Z",
                "data":{
                        "type":29,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "character_lvl":52,
                        "shard_id":42,
                        "area_id":200,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Exit Area (Event ID#30)

This event records information regarding the time at which a player exits an area. To log when a player exits an area, you need to pass the account and character IDs; the area level, position, and ID; and the timestamp. Optionally, you may pass the shard ID.

For related information, see Enter Area.

Impacted UI Features

  • KPI - Optional
  • System Metrics (Levels, Location/Maps)
  • User Metrics (Farming)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longcharacter_lvl0
Longshard_id0
Longarea_idIf AREA_ID is not empty, and AREA_NAME is empty, set AREA_NAME=NA.
Floatposition_x0
Floatposition_y0
Floatposition_z0
Stringarea_nameIf AREA_ID is not empty, and AREA_NAME is empty, set AREA_NAME=NA.

Sample Use

  • Java

//Log when a player enters an area
public void aKApi.logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name);

  • JavaScript

//Log when a player enters an area
aKApi.logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name)

  • PHP

//Log when a player enters an area
$aKApi->logAreaEnter(timestamp, account_id, character_id, character_lvl, shard_id, area_id, position_x, position_y, position_z, area_name)

  • JSON

//Log when a player exits an area

        {
                "timestamp":"2013-11-15T14:11:05.873Z",
                "data":{
                        "type":30,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "character_lvl":52,
                        "shard_id":42,
                        "area_id":200,
                        "position_x":678,
                        "position_y":231,
                        "position_z":517,
                        "area_name":"Area_Name"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Area Dim (Event ID#50)

For games with geographical areas and maps that make up a larger virtual world, this event records the dimension information about these maps. To log area dimensions, you need to pass the area name and ID, the map label and ID, the min and max positions, as well as the timestamp.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringarea_nameIf AREA ID is not empty and AREA NAME is empty, use NA.
Longarea_idIf AREA ID is empty, and AREA NAME is not empty, use 0.
Longmap_id0
Stringmap_labelNA
Floatmin_x0
Floatmin_y0
Floatmin_z0
Floatmax_x0
Floatmax_y0
Floatmax_z0

Sample Use

  • Java

//Log area dimensions
public void aKApi.logAreaDim(timestamp, area_name, area_id, map_id, map_label, min_x, min_y min_z, max_x, max_y, max_z);

  • JavaScript

//Log area dimensions
aKApi.logAreaDim(timestamp, area_name, area_id, map_id, map_label, min_x, min_y, min_z, max_x, max_y, max_z);

  • PHP

//Log area dimensions
$aKApi->logAreaDim(timestamp, area_name, area_id, map_id, map_label, min_x, min_y, min_z, max_x, max_y, max_z);

  • JSON

//Log area dimensions

        {
                "timestamp":"2013-11-15T18:13:04.432Z",
                "data":{
                        "type":50,
                        "area_name":"NA",
                        "area_id":2,
                        "map_id":-1,
                        "map_label":"map label",
                        "min_x":0,
                        "min_y":0,
                        "min_z":0,
                        "max_x":4,
                        "max_y":5,
                        "max_z":6
                }
        }

NOTE: All parameters are required in JSON, except "min_z" and "max_z" which are optional.

Back to Top


Economic Events

Economic events include those events that are related to in-game stores and purchases, such as a player's interaction with a store and items within it. Details on how to execute calls to log economic events can be found below for each corresponding event.

Note: Virtual Currency will be automatically initialized upon virtual currency transactions.

Store Create (Event ID#35)

For games that allow players to setup an in-game store where they can sell items, this event records information regarding the creation of an in-game store. To log when a store is created, you need to pass the store ID and description, as well as the address, city, state, country, zip code, and timestamp.

Note: You must log the store creation information before any log or load command references the store ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Longstore_idNo Default Value
Stringstore_descNA
Stringmap_real_addressNA
Stringmap_real_cityNA
Stringmap_real_stateNA
Stringmap_real_countryNA
Stringmap_real_postal_code0

Sample Use

  • Java

//Log when a store is created
public void aKApi.storeCreate(timestamp, store_id, store_desc, map_real_address, map_real_city, map_real_state, map_real_country, map_real_postal_code);

  • JavaScript

//Log when a store is created
aKApi.''storeCreate(timestamp, store_id, store_desc, map_real_address, map_real_city, map_real_state, map_real_country, map_real_postal_code);

  • PHP

//Log when a store is created
$aKApi->storeCreate(timestamp, store_id, store_desc, map_real_address, map_real_city, map_real_state, map_real_country, map_real_postal_code);

  • JSON

//Log when a store is created

        {
                "timestamp":"2013-11-15T15:03:32.064Z",
                "data":{
                        "type":35, 
                        "store_id":8729, 
                        "store_desc":"the cool store", 
                        "map_real_address":"123 Fake St", 
                        "map_real_city":"Walla Walla", 
                        "map_real_state":"Tuvalu", 
                        "map_real_country":"United States", 
                        "map_real_postal_code":"55667"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Store Delete (Event ID#36)

This event records information regarding the deletion of an in-game store. To log when a store is deleted, you need to pass the store ID and timestamp.

For related information, see Store Create.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringstore_idNo Default Value

Sample Use

  • Java

//Log when a store is deleted
public void aKApi.StoreDelete(timestamp, store_id);

  • JavaScript

//Log when a store is deleted
aKApi.StoreDelete(timestamp, store_id);

  • PHP

//Log when a store is deleted
$aKApi->StoreDelete(timestamp, store_id);

  • JSON

//Log when a store is deleted

        {
                "timestamp":"2013-11-15T15:11:15.847Z",
                "data":{
                        "type":36,
                        "store_id":8729
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Buy Store Item (Event ID#37)

This event records information regarding item purchases from an in-game store and includes details on the type of currency used. To log when a player buys a store item, you need to pass the account, character, and store IDs; the shard ID; the recipient account and character IDs; the item ID, name, and price; the currency type and value; and the timestamp. Optionally, you may pass the name of the virtual currency and the virtual currency count.

Impacted UI Features

  • KPI
  • User Metrics (Churn)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idaccount_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id
Longshard_id0
Longstore_idNo Default Value
Longitem_idIf Item ID is empty and Item Name is not empty, use 0.
Stringitem_nameIf Item ID is not empty and Item Name is empty, use NA.
Floatitem_priceNo Default Value
Integercurrency_typeNo Default Value*
Stringvirtual_currency_labelIf Currency Type is 1 then mandatory, else NULL.
Floatcurrency_valueNo Default Value
Integervirtual_currency_countNull

*Currency Type must be 0 or 1, where 0 equals 'Real' and 1 equals 'Virtual Currency'.

Sample Use

  • Java

//Log when a player buys a store item
public void aKApi.storeBuyItem(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, store_id, item_id, item_name, item_price, currency_type, virtual_currency_label, currency_value, virtual_currency_count);

  • JavaScript

//Log when a player buys a store item
aKApi.storeBuyItem(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, store_id, item_id, item_name, item_price, currency_type, virtual_currency_label, currency_value, virtual_currency_count);

  • PHP

//Log when a player buys a store item
$aKApi->storeBuyItem(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, store_id, item_id,item_name, item_price, currency_type, virtual_currency_label, currency_value, virtual_currency_count);

  • JSON

//Log when a player buys a store item

        {
                "timestamp":"2013-11-15T15:18:44.377Z",
                "data":{
                        "type":37,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"Wizard",
                        "shard_id":42,
                        "store_id":1,
                        "item_id":66,
                        "item_name":"The Blaster Gun",
                        "item_price":3,
                        "currency_type":1,
                        "virtual_currency_label":"MCH",
                        "currency_value":"4",
                        "virtual_currency_count":1
                }
        }

NOTE: All parameters are required in JSON, except "shard_id", "virtual_currency_label", and "virtual_currency_count" which are optional.

Sample Use

Example: If you had $1 per 100 tokens, and you bought an item for 200 tokens, you will send:

Item Price: 200
Currency Type: 1
Virtual Currency Name: Tokens
Currency Value: 2
Virtual Currency Count: 200

Example: If a user buys an item using $5 in real money then send:

Item Price: 5
Currency Type: 0
Virtual Currency Name: (null)
Currency Value: 5
Virtual Currency Count: 0

Example: If a user buys an item for 500 tokens send:

Item Price: 500
Currency Type: 1
Virtual Currency Name: Tokens
Currency Value: 0
Virtual Currency Count: 500

Back to Top


Store Login (Event ID#38)

This event records information regarding the time at which a player logs in to an in-game virtual store. To log when a player logs into a store, you need to pass the account, character, and store IDs; and the timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longstore_idNo Default Value

Sample Use

  • Java

//Log when a player logs in to a store
public void aKApi.storeLogin(timestamp , account_id, character_id, shard_id, store_id);

  • JavaScript

//Log when a player logs in to a store
aKApi.storeLogin(timestamp , account_id, character_id, shard_id, store_id);

  • PHP

//Log when a player logs in to a store
$aKApi->storeLogin(timestamp , account_id, character_id, shard_id, store_id);

  • JSON

//Log when a player logs in to a store

        {
                "timestamp":"2013-11-15T15:31:43.299Z",
                "data":{
                        "type":38,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
			"store_id":1
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Store Logout (Event ID#39)

This event records information regarding the time at which a player logs out of an in- game virtual store. To log when a player logs out of a store, you need to pass the account, character, and store IDs; and the timestamp. Optionally you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Longstore_idNo Default Value

Sample Use

  • Java

//Log when a player logs out of a store
public void aKApi.storeLogout(timestamp,account_id, character_id, shard_id, store_id);

  • JavaScript

//Log when a player logs out of a store
aKApi.storeLogout(timestamp, account_id, character_id, shard_id, store_id);

  • PHP

//Log when a player logs out of a store
$aKApi->storeLogout(timestamp, account_id, character_id, shard_id, store_id);

  • JSON

//Log when a player logs out of a store

        {
                "timestamp":"2013-11-15T15:39:58.675Z",
                "data":{
                        "type":39,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "shard_id":42,
                        "store_id":1
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Store Selection / Add to Cart (Event ID#40)

This event records information regarding when an item is selected or added to a player's cart. Note that this event may be a pre-requisite for buying an item; however it is not the same as buying an item. To log when a player selects a store item, you need to pass the account, character, and store IDs; the item name, type, and ID; and the timestamp.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longstore_idNo Default Value
Longitem_idIf ITEM NAME is not empty, defaults to 0. Otherwise mandatory.
Stringitem_nameIf ITEM ID is not empty, defaults to NA. Otherwise mandatory.
Stringitem_typeOther (See Appendix A for more types)

Sample Use

  • Java

//Log when a player selects a store item
public void aKApi.storeAddToCart(timestamp, account_id, character_id, store_id, item_id, item_name, item_type);

  • JavaScript

//Log when a player selects a store item
aKApi.storeAddToCart(timestamp, account_id, character_id, store_id, item_id, item_name, item_type);

  • PHP

//Log when a player selects a store item
$aKApi->storeAddToCart(timestamp, account_id, character_id, store_id, item_id, item_name, item_type);

  • JSON

//Log when a player selects a store item

        {
                "timestamp":"2013-11-15T16:01:45.370Z",
                "data":{
                        "type":40,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "store_id":1,
                        "item_id":66,
                        "item_name":"Sword",
                        "item_type":"Weapon"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Transaction Events

Transaction events include those events that are related to economic events outside of the game, such as when an item is purchased outside of the developer game store, or when a subscription changes. Details on how to execute calls to log transaction events can be found below for each corresponding event.

Subscription Change (Event ID#3)

This event records a change in subscription type (e.g. from free play to a paid subscriber or premium player). Subscription changes are only applicable to games with subscriptions, not free-to-play (F2P) games. To log a change of subscription, you need to pass the user's account ID, subscription status and type, and a timestamp for both subscription and expiry. Optionally, you can also pass the subscription value.

Impacted UI Features

  • KPI
  • System Metrics (Items, Levels, Social, NPC, Location/Maps)
  • User Metrics (Churn, Farming, Integrity)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_id"No Default Value''
Stringaccount_statusActive
Stringaccount_sub_typePaid
Floataccount_sub_valueNo Default Value
Dateaccount_sub_expires_timestamp(Month From Subscription Date)

Sample Use

  • Java

//Log a change of subscription
public void aKApi.putSubChange(timestamp, account_id, account_status, account_sub_type, account_sub_value, account_sub_expires_timestamp);

  • JavaScript

//Log a change of subscription
aKApi.putSubChange(timestamp, account_id, account_status, account_sub_type, account_sub_value, account_sub_expires_timestamp);

  • PHP

//Log a change of subscription
$aKApi->putSubChange(timestamp, account_id, account_status, account_sub_type, account_sub_value, account_sub_expires_timestamp);

  • JSON

//Log a change of subscription

        {
                "timestamp":"2013-11-10T06:00:00.000Z",
                "data":{
                        "type":3,
                        "account_id":"cool_guy@example.com",
                        "account_status":"Active",
                        "account_sub_type":"Paid",
                        "account_sub_value":10,
                        "account_sub_expires_timestamp":"2016-02-01T06:00:00.000Z"
                }
        }

NOTE: All parameters are required in JSON, except "account_sub_value" which is optional.

Back to Top


Currency Transaction (Event ID#18)

Logs a Currency Transaction event. Covers all types of transaction in the game or any other environment where real world money was used. Designed To Handle Most Currency Transactions. More Complicated Transactions Can Be Done Within Event #37.

This event records information regarding transactions in the game or other environments where real world money is used. To log currency transactions, you need to pass the account and character IDs, the transaction and currency types, as well as the timestamp. Optionally, you may pass the shard ID, the virtual currency label, the currency value, the virtual currency count, and the transaction description.

One common scenario is when a user purchases virtual currency by spending real currency. In this case, you should send this event twice. Once with a TRANSACTION TYPE of 0 and a CURRENCY TYPE of 0 (the user is spending real currency), and then again with a TRANSACTION TYPE of 1 and a CURRENCY TYPE of 1, along with the appropriate VIRTUAL CURRENCY COUNT and LABEL (the user is acquiring virtual currency).

Please note that you should only use this event when the Item Transaction (#17) or Store Buy Item (#37) events aren't appropriate. Store Buy Item (#37) should be used in most cases of any type of currency or virtual currency transactions. If currency is being spent to acquire something, it is preferable to use those events so that the purchase can be associated with the item. Do not send the Currency Transaction event in tandem with those events, because the currency transfer will be double counted on your dashboard.

Impacted UI Features

  • KPI
  • User Metrics (Churn)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringcharacter_idaccount_id
Longshard_id0
Integertransaction_typeNo Default Value*
Integercurrency_typeNo Default Value**
Stringvirtual_currency_labelIf CURRENCY_TYPE=1 then required; else null.
Floatcurrency_valueNo Default Value
Stringtransaction_descTruncate if >200
Integervirtual_currency_countNull

*Transaction Type must be 0 or 1, where 0 equals 'Spent' and 1 equals 'Acquired'.
**Currency Type must be 0 or 1, where 0 equals 'Real' and 1 equals 'Virtual Currency'.

Sample Use

  • Java

//Log a currency transaction
public void aKApi.logCurrencyTransaction(timestamp, account_id, character_id, shard_id, transaction_type, currency_type, virtual_currency_label, currency_value, transaction_desc, virtual_currency_count);

  • JavaScript

//Log a currency transaction
aKApi.logCurrencyTransaction(timestamp, account_id, character_id, shard_id, transaction_type, currency_type, virtual_currency_label, currency_value, transaction_desc, virtual_currency_count);

  • PHP

//Log a currency transaction
$aKApi->logCurrencyTransaction(timestamp, account_id, character_id, shard_id, transaction_type, currency_type, virtual_currency_label, currency_value, transaction_desc, virtual_currency_count);

  • JSON

//Log a currency transaction

        {
                "timestamp":"2013-11-14T18:10:14.808Z",
                "data":{
                        "type":18,
                        "account_id":"cool_guy@example.com",
                        "character_id":"wizard",
                        "shard_id":42,
                        "transaction_type":0,
                        "currency_type":0,
                        "virtual_currency_label":"mucha",
                        "currency_value":3.45,
                        "transaction_desc":"spend 3.45USD",
                        "virtual_currency_count:1
                }
        }

NOTE: All parameters are required in JSON, except "shard_id", "virtual_currency_label", "currency_value", "transaction_desc", and "virtual_currency_count" which are optional.

Back to Top


Traffic Source (Event ID#59)

This event records information regarding where your traffic is coming from, whether it’s from Facebook, an Email Campaign, or Direct Marketing. To log traffic source, you need to pass the account ID, traffic source, and traffic source type, along with the timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringaccount_idNo Default Value
Stringtraffic_sourcecampaign_name | sub_site | publisher_name | sub_publisher (See Appendix for more types
Longshard_id0
Stringtraffic_source_typepublisher_name (See Appendix for more types

|| String || TRAFFIC SOURCE || Other (See Appendix for more types || || String || TRAFFIC SOURCE TYPE || Unknown (See Appendix for more types || Sample Use

  • Java

//Log that a traffic source event occurred
public void aKApi.logTrafficSource(timestamp, account_id, traffic_source, shard_id, traffic_source_type) ;

  • JavaScript

//Log that a traffic source event occurred
aKApi.logTrafficSource(timestamp, account_id, traffic_source, shard_id, traffic_source_type) ;

  • PHP

//Log that a traffic source event occurred
$aKApi->logTrafficSource(timestamp, account_id, traffic_source, shard_id, traffic_source_type) ;

  • JSON

//Log that a traffic source event occurred

        {
                "timestamp":"2013-11-15T19:07:30.221Z",
                "data":{
                        "type":59,
                        "account_id":"cool_guy@example.com",
                        "traffic_source":"campaign_name | sub_site | publisher_name | sub_publisher",
                        "shard_id":0,
                        "traffic_source_type":"publisher_name"
                }
        }

{ "timestamp":"2013-11-15T19:07:30.221Z",

                "data":{

"type":59, "account_id":"cool_guy@example.com", "traffic_source":"abcTrafficSource", "shard_id":42.42, "traffic_source_type":"traffic_source_type" } }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Social Events


Social Interactions (Event ID#6)

This event records social events involving two people and includes all social events that are not covered as Group (Entry/Exit) Events or Friend (Addition/Deletion) Events. To log an in-app social event, you need to pass the sender account and character IDs; the receiver account and character IDs; the character levels of both users; the social event name and type; and the timestamp. Optionally, you may pass the shard ID.

Impacted UI Features

  • KPI
  • System Metrics (Social)
  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Longsender_character_levelIf Generic Character then Account Level; If no concept of levels then 0.
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id
Longreceiver_character_levelIf Generic Character then Account Level; If no concept of levels then 0.
Longshard_id0
Stringsocial_event_name"No Default Value''
Stringsocial_event_typeOther (See Appendix for more types)

Sample Use

  • Java

//Log an in-app social event
public void aKApi.logSocialEvent(timestamp, sender_account_id, sender_character_id, sender_character_level, receiver_account_id, receiver_character_id, receiver_character_level, shard_id, social_event_name, social_event_type);

  • JavaScript

//Log an in-app social event
aKApi.logSocialEvent(timestamp, sender_account_id, sender_character_id, sender_character_level, receiver_account_id, receiver_character_id, receiver_character_level, shard_id, social_event_name, social_event_type);

  • PHP

//Log an in-app social event
$aKApi->logSocialEvent(timestamp, sender_account_id, sender_character_id, sender_character_level, receiver_account_id, receiver_character_id, receiver_character_level, shard_id, social_event_name, social_event_type);

  • JSON

//Log an in-app social event

        {
                "timestamp":"2013-11-14T14:28:54.832Z",
                "data":{
                        "type":6,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"sharer",
                        "sender_character_level":1,
                        "receiver_account_id":"cool_guy1@example.com",
                        "receiver_character_id":"advertiser",
                        "receiver_character_level":1,
                        "shard_id":42,
                        "social_event_name":"rebate_share",
                        "social_event_type":"share"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Off-Game Interaction (OGI) Sender (Event ID#7)

An off-game-interaction refers to an interaction between a player inside the game environment and a person outside the game environment. To log the start of a social interaction outside of the application, you need to pass the sender account and character IDs; the receiver account and character IDs; the interaction category and location; and the event timestamp. Optionally, you may pass the shard ID.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value*
Stringreceiver_character_idreceiver_account_id
Longshard_id0
Stringogi_locationOther
Stringogi_categoryNo Default Value

*Receiver Account ID can be an ID (e.g. Facebook or Email).

Sample Use

  • Java

//Log the start of an off-game-interaction
public void aKApi.logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category);

  • JavaScript

//Log the start of an off-game-interaction
aKApi.logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category);

  • PHP

//Log the start of an off-game-interaction
$aKApi->logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category);

  • JSON

//Log the start of an off-game-interaction

        {
                "timestamp":"2013-11-14T14:48:56.718Z",
                "data":{
                        "type":7,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"mage",
                        "shard_id":42,
                        "ogi_location":"https://www.facebook.com/wall/42",
                        "ogi_category":"wall post"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Off-Game-Interaction (OGI) Receiver (Event ID#8)

This event records information regarding how the receiver of an off-game-interaction acted in response. To log the receiver's response to a social interaction outside of the application, you need to pass the sender account and character IDs, along with the receiver account and character IDs, shard ID, and event timestamp. As well, you'll need to pass the interaction category, location, and receiver response. Optionally, you may pass the shard ID.

For related information, see Off-Game-Interaction Sender.

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value*
Stringreceiver_character_idreceiver_account_id
Longshard_id0
Stringogi_locationOther
Stringogi_categoryNo Default Value
Stringogi_receiver_actionOther

*Receiver Account ID can be an ID (e.g. Facebook or Email).

Sample Use

  • Java

//Log the start of an off-game-interaction
public void aKApi.logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category, ogi_receiver_action);

  • JavaScript

//Log the start of an off-game-interaction
aKApi.logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category, ogi_receiver_action);

  • PHP

//Log the start of an off-game-interaction
$aKApi->logOgiSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, ogi_location, ogi_category, ogi_receiver_action);

  • JSON

// Log the end of and response to an off-game-interaction

        {
                "timestamp":"2013-11-14T15:00:53.806Z",
               "data":{
                        "type":8,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"mage",
                        "shard_id":42,
                        "ogi_category":"wall post",
                        "ogi_location":"https://www.facebook.com/wall/42",
                        "ogi_receiver_action":"other"
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" which is optional.

Back to Top


Message (Event ID#20)

This event records in-game messages between players for multiple channels of communication such as in-game chat, in-game mail, or a message broadcast to a group. To log an in-game message, you need to pass the sender account and character IDs; the receiver account and character IDs; the channel label; the message character count; and the timestamp. Optionally, you may pass the shard ID and the message description.

Impacted UI Features

  • System Metrics (Levels)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id
Longshard_id0
Stringmessage_ch_labelOther (See Appendix for more types)
Stringmessage_descNull
Longmessage_char_count1

Sample Use

  • Java

//Log an in-game message
public void aKApi.logMessage(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, message_ch_label, message_desc, message_char_count);

  • JavaScript

//Log an in-game message
aKApi.logMessage(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, message_ch_label, message_desc, message_char_count);

  • PHP

//Log an in-game message
$aKApi->logMessage(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, shard_id, message_ch_label, message_desc, message_char_count);

  • JSON

//Log an in-game message

        {
                "timestamp":"2013-11-14T18:46:02.842Z",
                "data":{
                        "type":20,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard",
                        "receiver_account_id":"cool_guy@example.com",
                        "receiver_character_id":"Wizard",
                        "shard_id":0,
                        "message_ch_label":"Group:Pre-Defined",
                        "message_desc":"A guild chat message",
                        "message_char_count":140
                }
        }

NOTE: All parameters are required in JSON, except "shard_id" and "message_desc" which are optional.

Back to Top


Recruitment Send (Event ID#33)

For games that allow players to invite other players to join them in finishing certain tasks or activities, this event records information regarding the recruitment request. To log a recruitment request, you need to pass the sender account and character IDs; the receiver account and character IDs; the recruitment type; and timestamp.

Impacted UI Features

  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id
Stringrecruitment_typeOther (See Appendix for more types)

Sample Use

  • Java

//Log a recruitment request
public void aKApi.recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_type);

  • JavaScript

//Log a recruitment request
aKApi.recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_type);

  • PHP

//Log a recruitment request
$aKApi->recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_type);

  • JSON

//Log a recruitment request

        {
                "timestamp":"2013-11-15T14:37:55.545Z",
                "data":{
                        "type":33,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"Wizard",
                        "recruitment_type":"mobile ad"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Recruitment Receive Action (Event ID#34)

This event records information regarding a player's response to a recruitment request, for example, was the request accepted or declined. To log a recruitment request response, you need to pass the sender account and character IDs; the receiver account and character IDs; the recruitment type and outcome; and the timestamp.

For related information, see Recruitment Send.

Impacted UI Features

  • Basic Package (Summary)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id
Stringrecruitment_typeOther (See Appendix for more types)
Stringrecruitment_outcome*Rejected
  • Recruitment Outcome default is 'Rejected', alternate options also include 'Accepted'.

Sample Use

  • Java

//Log a recruitment request
public void aKApi.recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_outcome);

  • JavaScript

//Log a recruitment request
aKApi.recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_outcome);

  • PHP

//Log a recruitment request
$aKApi->recruitmentSend(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id, recruitment_outcome);

  • JSON

//Log a recruitment request response

        {
                "timestamp":"2013-11-15T14:47:14.579Z",
                "data":{
                        "type":34,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard", 
                        "receiver_account_id":"small_cat@example.com", 
                        "receiver_character_id":"Wizard", 
                        "recruitment_type":"mobile ad", 
                        "recruitment_outcome":"Accepted"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Friend Addition (Event ID#43)

This event records information regarding a player adding another player as a friend, despite whether the friendship is reciprocated. To log a friend addition, you need to pass the sender account and character IDs; the receiver account and character IDs; and the timestamp.

Please note that this is a one-way, "follow" type of addition. If Bob is accepting a friend request from Alice, and they will subsequently appear on each other's friends list, then two events should be sent. One with Alice as the sender and Bob as the recipient, and another with Bob as the sender and Alice as the recipient. If Alice is simply following Bob without any action on his part, then you only need to send a single event with Alice as the sender and Bob as the recipient.

Impacted UI Features

  • System Metrics (Levels)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id

Sample Use

  • Java

//Log a friend addition
public void aKApi.logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • JavaScript

//Log a friend addition
aKApi.logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • PHP

//Log a friend addition
$aKApi->logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • JSON

//Log a friend addition

        {
                "timestamp":"2013-11-15T17:35:00.091Z",
                "data":{
                        "type":43,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"Wizard"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top


Friend Deletion (Event ID#44)

This event records information regarding the end of an in-game friendship. To log a friend deletion, you need to pass the sender account and character IDs; the receiver account and character IDs; along with the timestamp.

For related information, see Friend Addition.

Please note that this is a one-way, "unfollow" type of deletion. If Alice and Bob are currently in each other's friends list, and a removal from one party will cause them to be dropped from both lists, then you should send two deletion events. One with Alice as the sender and Bob as the recipient, and another with Bob as the sender and Alice as the recipient.

Impacted UI Features

  • System Metrics (Levels)

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
Stringsender_account_idNo Default Value
Stringsender_character_idsender_account_id
Stringreceiver_account_idNo Default Value
Stringreceiver_character_idreceiver_account_id

Sample Use

  • Java

//Log a friend addition
public void aKApi.logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • JavaScript

//Log a friend addition
aKApi.logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • PHP

//Log a friend addition
$aKApi->logFriendAdd(timestamp, sender_account_id, sender_character_id, receiver_account_id, receiver_character_id);

  • JSON

//Log a friend deletion

        {
                "timestamp":"2013-11-15T17:40:17.868Z",
                "data":{
                        "type":44,
                        "sender_account_id":"cool_guy@example.com",
                        "sender_character_id":"Wizard",
                        "receiver_account_id":"small_cat@example.com",
                        "receiver_character_id":"Wizard"
                }
        }

NOTE: "sender_account_id", and "receiver_account_id" are required, while all other parameters are optional.

Back to Top


Custom Events

Custom events include those events that relate to custom actions and CRM actions. As a Ninja Metrics customer, you have the freedom to define custom events in any way that you want, given the fields described under the Custom Slot Action and Custom Action events below. Details on how to execute calls to log custom events can be found below for each corresponding event.

Custom Slot (Event ID#54)

This event can be defined by your organization and records information regarding events that are not described in any of the other events and do not relate to actions in the game. To log a custom action event, you need to pass the account and character IDs, the custom action, the action type, the action value, and the timestamp.

Impacted UI Features

  • KPI

Parameters

TypeParameterDefault Value
Datetimestamp(Current Time)
StringtimestampNo Default Value
Stringcharacter_idtimestamp
Stringcustom_actionNo Default Value
Stringcustom_action_typeNo Default Value
String (max 400)custom_action_valueNA

Sample Use

  • Java

//Log a custom action event
public void aKApi.logCustomAction(timestamp, timestamp, character_id, custom_action, custom_action_type, custom_action_value);

  • JavaScript

//Log a custom action event
aKApi.logCustomAction(timestamp, timestamp, character_id, custom_action, custom_action_type, custom_action_value);

  • PHP

//Log a custom action event
$aKApi->logCustomAction(timestamp, timestamp, character_id, custom_action, custom_action_type, custom_action_value);

  • JSON

//Log a custom action event

        {
                "timestamp":"2013-11-15T18:35:36.006Z",
                "data":{
                        "type":54,
                        "account_id":"cool_guy@example.com",
                        "character_id":"Wizard",
                        "custom_action":"custom_action",
                        "custom_action_type":"custom_action_type",
                        "custom_action_value":"custom_action_value"
                }
        }

NOTE: All parameters are required in JSON.

Back to Top