PackageTop Level
Classpublic class AGI
InheritanceAGI Inheritance flash.display.Sprite

Armor Games Interface (AGI) - Developed By Armor Games Inc.

The AGI is a loaded swf API that allows you to submit game highscores, share game related data between players, and even save game data globally or for individual users.

There are 3 main systems attached to the AGI: Highscore Sysyem, Game Share System, and Game Save System.

1. The Highscore System is used for submitting to and retrieving from a global scoreboard where players can compete for the top score in your game.

2. The Game Share System can be used as a way of allowing players to share game related content to their friends by means of using short url links or even a browsing through the list of shares submitted by other players.

3. The Game Save System can be used as a global save system where a player can access his or her saves across any browser and any computer. Features include saving data to public space that your game can access at any time regardless of player.

The AGI has the capabilities of displaying highscores or game shares within the game itself. This display aspect of the AGI is called the Armor Games User Interface (AGUI). It encompasses all aspects of submitting scores, viewing top scores, sharing game data, viewing game shares, and more. It is highly recommended that you use AGUI in your game as all of the hard work is done for you. The AGUI can be used through any of the show...() functions.

The AGI uses a developer key and game key to authenticate. If you do not have a developer key or game key please contact daniel [at] armorgames.com. If you have any questions/concerns about the AGI, please contact joey [at] armorgames.com.

For working fla examples of the highscore system, download some examples here: AGI-Highscore-Examples.zip. For working fla examples of the game share system, download some examples here: AGI-Game-Share-Examples.zip.

View the examples

See also

Getting the AGI up and running
Initializing the AGUI
Login System using AGUI
Highscore System using AGUI
Game Share System using AGUI
Game Save System


Public Methods
 MethodDefined By
  
closeAGUI():void
Closes the AGUI if it is currently open.
AGI
  
containsProfanity(str:String, callback:Function):void
This uses the Armor Games bad word filter to determine if a String contains profanity or not.
AGI
  
decPublicData(key:String, amount:int = 1, callback:Function = null):void
Decrements Number game save data stored publicly on the server.
AGI
  
decUserData(key:String, amount:int = 1, callback:Function = null):void
Decrements Numbered game save data associated with a user.
AGI
  
deletePublicData(key:String = null, callback:Function = null):void
Deletes game save data stores publicly on the server.
AGI
  
deleteUserData(key:String = null, callback:Function = null):void
Deletes game save data associated with a user.
AGI
  
filterProfanity(str:String, callback:Function):void
This uses the Armor Games bad word filter to filter out the bad words in a String.
AGI
  
Returns the version number of the AGUI.
AGI
  
getUserData():Object
Returns an Object containing properties about the user.
AGI
  
getUserName():String
Returns the name of the current user.
AGI
  
getVersion():String
Returns the version number of the AGI.
AGI
  
This method will hide the Login Status button from view.
AGI
  
incGameShareView(shareId:String):void
Increments the the view/play count of the game share given a Share ID.
AGI
  
incPublicData(key:String, amount:int = 1, callback:Function = null):void
Increments Number game save data stored publicly on the server.
AGI
  
incUserData(key:String, amount:int = 1, callback:Function = null):void
Increments Numbered game save data associated with a user.
AGI
  
init(devKey:String, gameKey:String, onError:Function = null, debug:Boolean = false):void
Intializes the AGI with a unique developer key and game key.
AGI
  
initAGUI(initParams:Object):void
This method allows you to customize the AGUI with initial properties.
AGI
  
isAGUIVisible():Boolean
Returns whether or not the AGUI is currently being displayed.
AGI
  
isComingFromShareURL(callback:Function):void
Retrieves the game share from the server if coming from a shared url.
AGI
  
isConnected():Boolean
Returns whether or not the AGI is connected to the server.
AGI
  
isLoggedIn():Boolean
Returns whether or not the user is logged into the AGI.
AGI
  
likeGameShare(shareId:String):void
Allows a player to like a particular game share.
AGI
  
logout(callback:Function = null):void
Logs the user out of the AGI.
AGI
  
retrieveFriendGameShares(callback:Function, listMetric:String = shares, pageNumber:int = 1):void
Retrieves the game shares made or liked by friends of thie player.
AGI
  
retrieveFriendScores(callback:Function, scoreType:String = null, sortDescending:Boolean = true, pageNumber:int = 1):void
Retrieves a list of the user's friends highscores on the server.
AGI
  
retrieveGameShare(shareId:String, callback:Function):void
Retrieves a game share from the server.
AGI
  
retrieveGameShares(timeFrame:String, listMetric:String, callback:Function, pageNumber:int = 1):void
Retrieves the games shares within a time frame as well as a list metric.
AGI
  
retrieveLatestGameShares(callback:Function, pageNumber:int = 1):void
Retrieves the latest games shares submitted.
AGI
  
retrievePublicData(callback:Function, key:String = null):void
Retrieves game save data stored publicly on the server.
AGI
  
retrievePublicScores(callback:Function, scoreType:String = null, timeFrame:String = alltime, sortDescending:Boolean = true, pageNumber:int = 1, getRank:Boolean = false):void
Retrieves a list of public highscores on the server.
AGI
  
retrieveRandomGameShare(callback:Function):void
Retrieves a random game share from the server.
AGI
  
retrieveStaffPickedGameShares(callback:Function, pageNumber:int = 1):void
Retrieves the staff picked games shares.
AGI
  
retrieveUserData(callback:Function, key:String = null):void
Retrieves game save data associated with a user.
AGI
  
retrieveUserGameShares(callback:Function, listMetric:String = shares, pageNumber:int = 1):void
Retrieves the game shares made or liked by this player.
AGI
  
retrieveUserScores(callback:Function, scoreType:String = null, sortDescending:Boolean = true, pageNumber:int = 1):void
Retrieves a list of the users highscores on the server.
AGI
  
setDebugOutputCallback(callback:Function):void
This method exists solely for the purpose of testing within the browser when the trace output panel is unavailable.
AGI
  
showGameShareList(shareClickCallback:Function = null, parentObj:* = null):void
Brings up the a list of the top game shares on the server and allows the player navigate through them.
AGI
  
showGameShareNavi(x:Number, y:Number, randomShareClickCallback:Function = null, parentObj:* = null):void
Brings up the game share naviagtional element (Navi) using the AGUI.
AGI
  
showGameShareSubmit(data:String, shareName:String, thumbnail:DisplayObject = null, shareClickCallback:Function = null, parentObj:* = null):void
Brings up the submit panel that shows the thumbnail passed in and allows the player to submit their game share to the server.
AGI
  
showLogin(callback:Function = null, parentObj:* = null):void
Brings up the AGUI login panel where the player can login to his or her account.
AGI
  
showLoginStatus(x:Number = 0, y:Number = 0, loginCallback:Function = null, parentObj:* = null):void
Shows the Login Status button on screen.
AGI
  
showScoreboardList(scoreTypes:Array = null, defaultScoreType:String = null, parentObj:* = null):void
Brings up a Scoreboard that shows the top scores on the server for the client game using the AGUI.
AGI
  
showScoreboardSubmit(score:uint, playerName:String = null, scoreType:String = null, scoreTypes:Array = null, parentObj:* = null):void
Brings up a submit panel that shows the player his/her score and allows them to submit it to the server using the AGUI.
AGI
  
showUserProfile(loginCallback:Function = null, parentObj:* = null):void
Brings up the AGUI user profile page where the player can view their own profile.
AGI
  
submitGameShare(name:String, data:String, callback:Function = null, thumbnail:* = null):void
Submits game share to the server.
AGI
  
submitPublicData(key:String, data:*, callback:Function = null):void
Submits game save data to a public space.
AGI
  
submitPublicDataObject(obj:Object, callback:Function = null):void
Submits game save data to a public space in Object form.
AGI
  
submitScore(playerName:String, score:uint, scoreType:String = null, callback:Function = null, sortListDescending:Boolean = true):void
Submits a player score to the server.
AGI
  
submitUserData(key:String, data:*, callback:Function = null):void
Submits game save data associated with a user.
AGI
  
submitUserDataObject(obj:Object, callback:Function = null):void
Submits game save data associated with a user in Object form.
AGI
  
unlikeGameShare(shareId:String):void
Removes a game share from the users likes list.
AGI
Method Detail
closeAGUI()method
public function closeAGUI():void

Closes the AGUI if it is currently open.

See also

containsProfanity()method 
public function containsProfanity(str:String, callback:Function):void

This uses the Armor Games bad word filter to determine if a String contains profanity or not.

Parameters

str:String — The String to test.
 
callback:Function — A callback to determine if the String contains profanity or not.

See also


Example
This example shows how to use the callback.
 agi.containsProfanity( "Really Bad Words", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         // True if the String contained profanity
         trace( data.contains );
     }
     else
     {
         trace( data.error );
     }
 } 
decPublicData()method 
public function decPublicData(key:String, amount:int = 1, callback:Function = null):void

Decrements Number game save data stored publicly on the server.

Public data is data that any client game can access regardless of user.

NOTE: Data that is a String, Array, or Object will be overwritten to the value of 1.

Parameters

key:String — The key value of the Number data you wish to decrement.
 
amount:int (default = 1) — The amount you would like to decrement the Number data by.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also

decUserData()method 
public function decUserData(key:String, amount:int = 1, callback:Function = null):void

Decrements Numbered game save data associated with a user.

NOTE: The user must be logged in in order to delete user data.

NOTE: Data that is a String, Array, or Object will be overwritten to the value of 1.

Parameters

key:String — The key value of the Number data you wish to decrement.
 
amount:int (default = 1) — The amount you would like to decrement the Number data by.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also

deletePublicData()method 
public function deletePublicData(key:String = null, callback:Function = null):void

Deletes game save data stores publicly on the server.

Public data is data that any client game can access regardless of user.

Parameters

key:String (default = null) — The key value of the data you wish to delete. Leave null if you want to delete everything on the server.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will delete the data under the key value "myData" and listen for a callback.
 agi.deletePublicData( "myData", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Delete Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
deleteUserData()method 
public function deleteUserData(key:String = null, callback:Function = null):void

Deletes game save data associated with a user.

NOTE: The user must be logged in in order to delete user data.

Parameters

key:String (default = null) — The key value of the data you wish to delete. Leave null if you want to delete everything on the server.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will delete the data under the key value "myData" and listen for a callback.
 agi.deleteUserData( "myData", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Delete Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
filterProfanity()method 
public function filterProfanity(str:String, callback:Function):void

This uses the Armor Games bad word filter to filter out the bad words in a String.

Parameters

str:String — The String to filter.
 
callback:Function — A callback to retrieve the filtered String.

See also


Example
This example shows how to use the callback.
 agi.filterProfanity( "Really Bad Words", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         // The filtered String without bad words
         trace( data.str );
     }
     else
     {
         trace( data.error );
     }
 } 
getAGUIVersion()method 
public function getAGUIVersion():String

Returns the version number of the AGUI.

Returns
String — The version number of the AGUI.

NOTE: Will return null if the AGUI has not been loaded yet through a show...() method.

getUserData()method 
public function getUserData():Object

Returns an Object containing properties about the user.

Returns
Object — Properties include:
 username : String - Name of the user.
 avatar_url : String - URL to the users avatar image.
 profile_url : String - URL to the users profile page on armorgames.com.
 countryCode : String - Country code of the user.
 countryName : String - Country name of the user. 

NOTE: Returns null if the user is not logged in.

getUserName()method 
public function getUserName():String

Returns the name of the current user.

Returns
String — Name of the user.

NOTE: Returns null if the user is not logged in.

getVersion()method 
public function getVersion():String

Returns the version number of the AGI.

Returns
String — The version number of the AGI.
hideLoginStatus()method 
public function hideLoginStatus():void

This method will hide the Login Status button from view.

See also

incGameShareView()method 
public function incGameShareView(shareId:String):void

Increments the the view/play count of the game share given a Share ID.

Parameters

shareId:String — Share ID of the game share.

incPublicData()method 
public function incPublicData(key:String, amount:int = 1, callback:Function = null):void

Increments Number game save data stored publicly on the server.

Public data is data that any client game can access regardless of user.

NOTE: Data that is a String, Array, or Object will be overwritten to the value of 1.

Parameters

key:String — The key value of the Number data you wish to increment.
 
amount:int (default = 1) — The amount you would like to increment the Number data by.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also

incUserData()method 
public function incUserData(key:String, amount:int = 1, callback:Function = null):void

Increments Numbered game save data associated with a user.

NOTE: The user must be logged in in order to delete user data.

NOTE: Data that is a String, Array, or Object will be overwritten to the value of 1.

Parameters

key:String — The key value of the Number data you wish to increment.
 
amount:int (default = 1) — The amount you would like to increment the Number data by.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also

init()method 
public function init(devKey:String, gameKey:String, onError:Function = null, debug:Boolean = false):void

Intializes the AGI with a unique developer key and game key.

Will perform an auto login if the client game is hosted on armorgames.com and the player is logged in to the site already.

Parameters

devKey:String — The unique developer key.
 
gameKey:String — The unique game key.
 
onError:Function (default = null) — A method to handle any errors the AGI encounters.
 
debug:Boolean (default = false) — Whether or not to turn on the debug output from the AGI in the output panel. See setDebugOutputCallback() for additional debugging.

See also


Example
The onError callback receives a String parameter:
 agi.init( devKey, gameKey, handleAGIError );
 function handleAGIError( data:Object ):void
 {
     trace( data.error );
 } 
initAGUI()method 
public function initAGUI(initParams:Object):void

This method allows you to customize the AGUI with initial properties.

These properties can include a custom icon graphic, a handler for listening to when the player closes the AGUI, or even the x and y location.

These properties are not additive, so if a property is specified once, the next call will overwrite its value.

The AGUI is opened up whenever a show...() method is called (Ex: showScoreboardList()).

The AGUI is 500 x 350 pixels with a top left registration point.

When a player is viewing the Game Share List, he/she can click on a game share to play it at any time. Upon clicking a game share, the list is set to invisible and a Game Share Navigational Element (Navi) is brought on screen. To change properties of this Navi, view the example below.

Parameters

initParams:Object — An object containing optional properties to initialize the AGUI.

See also


Example
The following example sets the x and y screen coordinates of the AGUI.
 agi.initAGUI( { x:25, y:50 } ); 
The following example shows how to listen for when the AGUI is closed by the player.
 agi.initAGUI( { onClose:handleAGUIClose } );
 function handleAGUIClose():void
 {
     trace( "AGUI has been closed" );
 } 
Properties for the initParams include:
 x : Number (Default = Center Stage) - X screen coordinate to place the AGUI at.
 y : Number (Default = Center Stage) - Y screen coordinate to place the AGUI at.
 scale : Number - scaleX and scaleY of the AGUI.
 iconGraphic : DisplayObject - Custom Icon to use in the top left of the AGUI. (75 x 50 Pixels).
 onClose : Function - Method callback for when the user closes the scoreboard. (Recommended)
 onLogin : Function - Method callback for whenever the player logs in or out using the AGUI.
 onLoad : Function - Method callback for when the AGUI finishes loading.
 onError : Function - Method callback for when the AGUI fails to load.
 autoShowNavi : Boolean (Default = true) - true if the game share navigational element will auto show when a player clicks on a game share within the Game Share List.
 naviX : Number (Default = 0) - X screen coordinate of the game share navigational element.
 naviY : Number (Default = 0) - Y screen coordinate of the game share navigational element.
 disableDarkBackground : Boolean - Disables the dark background overlay that appears whenever the AGUI is displayed. Default value is false.
 
isAGUIVisible()method 
public function isAGUIVisible():Boolean

Returns whether or not the AGUI is currently being displayed.

Returns
Booleantrue if the AGUI is being displayed, false if it is not.

See also

isComingFromShareURL()method 
public function isComingFromShareURL(callback:Function):void

Retrieves the game share from the server if coming from a shared url.

Call this at the beginning of the game for best usage.

NOTE: If a game share is retrieved from the server, the views/plays of the game share is automatically incremented

To allow players to like the game share retrieved, call the showGameShareNavi() method.

Parameters

callback:Function — A method to handle retrieving the game share from the server if coming from a shared url.

See also


Example
This example shows how to check if the client game is being played from a shared URL.
 agi.isComingFromShareURL( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( "No share to retrieve" );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 data : String - Data of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
 timestamp : Number - The UTC time when the player created the game share.
 createdOn : String - A user friendly date when the player created the game share.
 funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
 staffPick : Boolean - Value is true if the game share has been staff picked.
 totalLikes : Number - Total number of likes a game share has received.
 likes : Object - Pertains to how many likes a game share has received. Properties include:
     daily : Number - Number of likes this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 totalViews : Number - Total number of views a game share has received.
 views : Object - Pertains to how many times a game share has been viewed. Properties include:
     daily : Number - Number of views this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 username : String - Name of the player that created the game share. Value is null if submitted anonymously.
 avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
 profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
 countryCode : String - Country code of the user. Value is null if submitted anonymously.
 countryName : String - Country name of the user. Value is null if submitted anonymously. 
isConnected()method 
public function isConnected():Boolean

Returns whether or not the AGI is connected to the server.

Returns
Booleantrue if the AGI is connected to the server.
isLoggedIn()method 
public function isLoggedIn():Boolean

Returns whether or not the user is logged into the AGI.

Returns
Booleantrue if the user is logged into the AGI.
likeGameShare()method 
public function likeGameShare(shareId:String):void

Allows a player to like a particular game share.

NOTE: If the player is logged in, the game share is added to their likes list.

Parameters

shareId:String — ID of the game share to like.

See also

logout()method 
public function logout(callback:Function = null):void

Logs the user out of the AGI.

NOTE: Does not use the AGUI.

Parameters

callback:Function (default = null) — A method to handle whether or not the user logged out successfully.


Example
This example logs the user out of the AGI and listens for the callback.
 agi.logout( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Successful Logout" );
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the call was successful.
 error : String - If success is false, this will give more information as to why the call failed.
 
retrieveFriendGameShares()method 
public function retrieveFriendGameShares(callback:Function, listMetric:String = shares, pageNumber:int = 1):void

Retrieves the game shares made or liked by friends of thie player.

NOTE: The player must be logged in to access friends game shares

Parameters

callback:Function — A method to handle retrieving the game shares from the server.
 
listMetric:String (default = shares) — The metric to narrow the search within. Values include: "shares" and "likes".
 
pageNumber:int (default = 1) — The page number to retrieve. 32 shares per page.

See also


Example
This example shows how to retrieve a list of game shares made by this players friends and output their names.
 agi.retrieveFriendGameShares( callback, "shares" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Game Share Name: " + item.name );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 metric : String - List metric of the game share retrieved.
 total : Number - Total number of game shares on the server.
 list : Array - Contains all the game shares in Object form for this timeFrame and metric. Each Object includes these properties:
     name : String - Name of the game share retrieved.
     share_id : String - Share ID of the game share.
     url : String - Share URL given to the game share.
     long_url : String - Longer URL to the game share.
     thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
     timestamp : Number - The UTC time when the player created the game share.
     createdOn : String - A user friendly date when the player created the game share.
     funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
     staffPick : Boolean - Value is true if the game share has been staff picked.
     totalLikes : Number - Total number of likes a game share has received.
     likes : Object - Pertains to how many likes a game share has received. Properties include:
         daily : Number - Number of likes this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     totalViews : Number - Total number of views a game share has received.
     views : Object - Pertains to how many times a game share has been viewed. Properties include:
         daily : Number - Number of views this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     username : String - Name of the player that created the game share. Value is null if submitted anonymously.
     avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
     profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
     countryCode : String - Country code of the user. Value is null if submitted anonymously.
     countryName : String - Country name of the user. Value is null if submitted anonymously. 

NOTE: The game share data property is not included in this list. This is due to keeping down the load of retrieving a list of game shares.

retrieveFriendScores()method 
public function retrieveFriendScores(callback:Function, scoreType:String = null, sortDescending:Boolean = true, pageNumber:int = 1):void

Retrieves a list of the user's friends highscores on the server. Will return a false success if the user is not logged in.

Parameters

callback:Function — A method to pass the high scores once they are retrieved from the server.
 
scoreType:String (default = null) — The type of scores to get from the server. (Ex. null, "easy", "hard").
 
sortDescending:Boolean (default = true) — Whether or not to sort the scores descending or ascending.
 
pageNumber:int (default = 1) — The page number to retrieve. 25 scores per page.

See also


Example
This example uses the callback and traces out the the list of scores for this user.
 agi.retrieveFriendScores( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Player Name: " + item.playerName + " Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
This example performs the same as above except it displays all the scores for the score type "easy".
 agi.retrieveFriendScores( callback, "easy" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Player Name: " + item.playerName + " Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not. If the user is not logged in, this value will be false.
 error : String - If success is false, this will give more information as to why the call failed.
 scoreType : String - Type of score that was requested.
 sortDesc : Boolean - Whether or not the scores are listed descending or ascending.
 total : Number - Total number of scores on the server for this scoreType and timeFrame.
 average : Number - Average score of all the scores on the server for this scoreType and timeFrame.
 page : Number - Page number that was requested.
 currentTime : Number - The UTC time of the server.
 rank : Object - Ranking of the player on the server. Properties include:
     alltime : Object
         rank : Number - Position the player ranked in on the server.
         total : Number - Total positions the player was ranked within.
 list : Array - List containing all the high score objects on the server for this scoreType and timeFrame. Each object contains these properties:
     score : Number - The score value of the player.
     playerName : String - The name of the player.
     scoreType : String - The type of score this player submitted.
     countryCode : String - A string representing the country code the user submitted their score from.
     countryName : String - Name of the country the player submitted a score in.
     relativeTime : String - A user friendly date when the player submited their score.
     time : Number - The UTC time when the player submitted their score.
     avatar_url : String - The url to where the players avatar image is located. Value is null if the player is not a registered user.
     profile_url : String - The url to the players profile page. Value is null if the player is not a registered user. 
retrieveGameShare()method 
public function retrieveGameShare(shareId:String, callback:Function):void

Retrieves a game share from the server.

Parameters

shareId:String — The share ID of the game share to receive.
 
callback:Function — A method to handle retrieving the game share from the server.

See also


Example
This example shows how to retrieve a game share from the server. myShareID in this example is the share ID of the game share being retrieved.
 agi.retrieveGameShare( myShareID, callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( "No share to retrieve" );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 data : String - Data of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
 timestamp : Number - The UTC time when the player created the game share.
 createdOn : String - A user friendly date when the player created the game share.
 funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
 staffPick : Boolean - Value is true if the game share has been staff picked.
 totalLikes : Number - Total number of likes a game share has received.
 likes : Object - Pertains to how many likes a game share has received. Properties include:
     daily : Number - Number of likes this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 totalViews : Number - Total number of views a game share has received.
 views : Object - Pertains to how many times a game share has been viewed. Properties include:
     daily : Number - Number of views this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 username : String - Name of the player that created the game share. Value is null if submitted anonymously.
 avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
 profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
 countryCode : String - Country code of the user. Value is null if submitted anonymously.
 countryName : String - Country name of the user. Value is null if submitted anonymously. 
retrieveGameShares()method 
public function retrieveGameShares(timeFrame:String, listMetric:String, callback:Function, pageNumber:int = 1):void

Retrieves the games shares within a time frame as well as a list metric.

Parameters

timeFrame:String — The time frame to retrieve game share within. Values include: "daily", "weekly", "monthly", and "alltime".
 
listMetric:String — The metric to narrow the search within. Values include: "mostrated" (Most Likes), "mostviewed" (Most Plays), and "popular" (Highest Fun factor).
 
callback:Function — A method to handle retrieving the game shares from the server.
 
pageNumber:int (default = 1) — The page number to retrieve. 32 shares per page.

See also


Example
This example shows how to retrieve a list of game shares using the time frame "alltime" and list metric of "popular" and output their names.
 agi.retrieveGameShares( "alltime", "popular", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Game Share Name: " + item.name );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 timeFrame : String - Time frame of the game shares retrieved.
 metric : String - List metric of the game share retrieved.
 page : Number - Page number that was requested.
 total : Number - Total number of game shares on the server.
 list : Array - Contains all the game shares in Object form for this timeFrame and metric. Each Object includes these properties:
     name : String - Name of the game share retrieved.
     share_id : String - Share ID of the game share.
     url : String - Share URL given to the game share.
     long_url : String - Longer URL to the game share.
     thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
     timestamp : Number - The UTC time when the player created the game share.
     createdOn : String - A user friendly date when the player created the game share.
     funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
     totalLikes : Number - Total number of likes a game share has received.
     staffPick : Boolean - Value is true if the game share has been staff picked.
     likes : Object - Pertains to how many likes a game share has received. Properties include:
         daily : Number - Number of likes this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     totalViews : Number - Total number of views a game share has received.
     views : Object - Pertains to how many times a game share has been viewed. Properties include:
         daily : Number - Number of views this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     username : String - Name of the player that created the game share. Value is null if submitted anonymously.
     avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
     profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
     countryCode : String - Country code of the user. Value is null if submitted anonymously.
     countryName : String - Country name of the user. Value is null if submitted anonymously. 

NOTE: The game share data property is not included in this list. This is due to keeping down the load of retrieving a list of game shares.

retrieveLatestGameShares()method 
public function retrieveLatestGameShares(callback:Function, pageNumber:int = 1):void

Retrieves the latest games shares submitted.

Parameters

callback:Function — A method to handle retrieving the game shares from the server.
 
pageNumber:int (default = 1) — The page number to retrieve. 32 shares per page.

See also


Example
This example shows how to retrieve the latest list of game shares and output their names.
 agi.retrieveLatestGameShares( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Game Share Name: " + item.name );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 page : Number - Page number that was requested.
 total : Number - Total number of game shares on the server.
 list : Array - Contains all the game shares in Object form for this timeFrame and metric. Each Object includes these properties:
     name : String - Name of the game share retrieved.
     share_id : String - Share ID of the game share.
     url : String - Share URL given to the game share.
     long_url : String - Longer URL to the game share.
     thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
     timestamp : Number - The UTC time when the player created the game share.
     createdOn : String - A user friendly date when the player created the game share.
     funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
     staffPick : Boolean - Value is true if the game share has been staff picked.
     totalLikes : Number - Total number of likes a game share has received.
     likes : Object - Pertains to how many likes a game share has received. Properties include:
         daily : Number - Number of likes this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     totalViews : Number - Total number of views a game share has received.
     views : Object - Pertains to how many times a game share has been viewed. Properties include:
         daily : Number - Number of views this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     username : String - Name of the player that created the game share. Value is null if submitted anonymously.
     avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
     profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
     countryCode : String - Country code of the user. Value is null if submitted anonymously.
     countryName : String - Country name of the user. Value is null if submitted anonymously. 

NOTE: The game share data property is not included in this list. This is due to keeping down the load of retrieving a list of game shares.

retrievePublicData()method 
public function retrievePublicData(callback:Function, key:String = null):void

Retrieves game save data stored publicly on the server.

Public data is data that any client game can access regardless of user.

Parameters

callback:Function — A method to handle retrieving the public data from the server.
 
key:String (default = null) — The key value of the data you wish to retrieve. Leave null if you want to retrieve everything on the server.

See also


Example
This example with retrieve data under the key value "myData" which was submitted as an Array.

NOTE: If no data exists on the server under the key name, data.data will be null.

 agi.retrievePublicData( callback, "myData" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var arr:Array = data.data;
         trace( arr );
     }
     else
     {
         trace( data.error );
     }
 } 
This example with retrieve all the data on the server in Object form. The two key values on the server are myData and myString.

NOTE: If no data exists on the server, data.data will be null.

 agi.retrievePublicData( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var obj:Object = data.data;
         trace( obj.myData );
         trace( obj.myString );
     }
     else
     {
         trace( data.error );
     }
 } 
retrievePublicScores()method 
public function retrievePublicScores(callback:Function, scoreType:String = null, timeFrame:String = alltime, sortDescending:Boolean = true, pageNumber:int = 1, getRank:Boolean = false):void

Retrieves a list of public highscores on the server.

Parameters

callback:Function — A method to pass the high scores once they are retrieved from the server.
 
scoreType:String (default = null) — The type of scores to get from the server. (Ex. null, "easy", "hard").
 
timeFrame:String (default = alltime) — The time frame of scores to get from the server. (Values: "daily", "weekly", "alltime").
 
sortDescending:Boolean (default = true) — Whether or not to sort the scores descending or ascending.
 
pageNumber:int (default = 1) — The page number to retrieve. 25 scores per page.
 
getRank:Boolean (default = false) — Determins whether or not to grab the ranking of the players top score. Only returns a value if the player is logged in.

See also


Example
This example uses the callback and traces out the the list of players and their scores.
 agi.retrievePublicScores( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Player Name: " + item.playerName + " Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
This example performs the same as above except it displays all the scores for the time frame "alltime" and for the score type "easy".
 agi.retrievePublicScores( callback, "easy", "alltime" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Player Name: " + item.playerName + " Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not.
 error : String - If success is false, this will give more information as to why the call failed.
 scoreType : String - Type of score that was requested.
 timeFrame : String - Time frame that was requested.
 sortDesc : Boolean - Whether or not the scores are listed descending or ascending.
 total : Number - Total number of scores on the server for this scoreType and timeFrame.
 average : Number - Average score of all the scores on the server for this scoreType and timeFrame.
 page : Number - Page number that was requested.
 currentTime : Number - The UTC time of the server.
 rank : Object - Ranking of the player on the server. Only the property that matches the time frame requested will be valid. Properties include:
     daily : Object
         rank : Number - Position the player ranked in on the server.
         total : Number - Total positions the player was ranked within.
     weekly : Object
         rank : Number - (Same as above).
         total : Number - (Same as above).
     alltime : Object
         rank : Number - (Same as above).
         total : Number - (Same as above).
 list : Array - List containing all the high score objects on the server for this scoreType and timeFrame. Each object contains these properties:
     score : Number - The score value of the player.
     playerName : String - The name of the player.
     scoreType : String - The type of score this player submitted.
     countryCode : String - A string representing the country code the user submitted their score from.
     countryName : String - Name of the country the player submitted a score in.
     relativeTime : String - A user friendly date when the player submited their score.
     time : Number - The UTC time when the player submitted their score.
     avatar_url : String - The url to where the players avatar image is located. Value is null if the player is not a registered user.
     profile_url : String - The url to the players profile page. Value is null if the player is not a registered user. 
retrieveRandomGameShare()method 
public function retrieveRandomGameShare(callback:Function):void

Retrieves a random game share from the server.

Parameters

callback:Function — A method to handle retrieving the random game share from the server.


Example
This example shows how to retrieve a random game share from the server and display it's name and data.
 agi.retrieveRandomGameShare( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( "No share to retrieve" );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 data : String - Data of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
 timestamp : Number - The UTC time when the player created the game share.
 createdOn : String - A user friendly date when the player created the game share.
 funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
 staffPick : Boolean - Value is true if the game share has been staff picked.
 totalLikes : Number - Total number of likes a game share has received.
 likes : Object - Pertains to how many likes a game share has received. Properties include:
     daily : Number - Number of likes this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 totalViews : Number - Total number of views a game share has received.
 views : Object - Pertains to how many times a game share has been viewed. Properties include:
     daily : Number - Number of views this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 username : String - Name of the player that created the game share. Value is null if submitted anonymously.
 avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
 profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
 countryCode : String - Country code of the user. Value is null if submitted anonymously.
 countryName : String - Country name of the user. Value is null if submitted anonymously. 
retrieveStaffPickedGameShares()method 
public function retrieveStaffPickedGameShares(callback:Function, pageNumber:int = 1):void

Retrieves the staff picked games shares.

Parameters

callback:Function — A method to handle retrieving the game shares from the server.
 
pageNumber:int (default = 1) — The page number to retrieve. 32 shares per page.

See also


Example
This example shows how to retrieve the staff picked list of game shares and output their names.
 agi.retrieveStaffPickedGameShares( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Game Share Name: " + item.name );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 total : Number - Total number of game shares on the server.
 list : Array - Contains all the game shares in Object form for this timeFrame and metric. Each Object includes these properties:
     name : String - Name of the game share retrieved.
     share_id : String - Share ID of the game share.
     url : String - Share URL given to the game share.
     long_url : String - Longer URL to the game share.
     thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
     timestamp : Number - The UTC time when the player created the game share.
     createdOn : String - A user friendly date when the player created the game share.
     funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
     staffPick : Boolean - Value is true if the game share has been staff picked.
     totalLikes : Number - Total number of likes a game share has received.
     likes : Object - Pertains to how many likes a game share has received. Properties include:
         daily : Number - Number of likes this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     totalViews : Number - Total number of views a game share has received.
     views : Object - Pertains to how many times a game share has been viewed. Properties include:
         daily : Number - Number of views this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     username : String - Name of the player that created the game share. Value is null if submitted anonymously.
     avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
     profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
     countryCode : String - Country code of the user. Value is null if submitted anonymously.
     countryName : String - Country name of the user. Value is null if submitted anonymously. 

NOTE: The game share data property is not included in this list. This is due to keeping down the load of retrieving a list of game shares.

retrieveUserData()method 
public function retrieveUserData(callback:Function, key:String = null):void

Retrieves game save data associated with a user.

NOTE: The user must be logged in in order to retrieve user data.

Parameters

callback:Function — A method to handle retrieving the public data from the server.
 
key:String (default = null) — The key value of the data you wish to retrieve. Leave null if you want to retrieve everything on the server.

See also


Example
This example with retrieve data under the key value "myData" which was submitted as an Array.
 agi.retrieveUserData( callback, "myData" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var arr:Array = data.data;
         trace( arr );
     }
     else
     {
         trace( data.error );
     }
 } 
NOTE: If no data exists on the server under the key name, data.data will be null.
This example with retrieve all the data on the server in Object form. The two key values on the server are myData and myString.
 agi.retrieveUserData( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var obj:Object = data.data;
         trace( obj.myData );
         trace( obj.myString );
     }
     else
     {
         trace( data.error );
     }
 } 
NOTE: If no data exists on the server, data.data will be null.
retrieveUserGameShares()method 
public function retrieveUserGameShares(callback:Function, listMetric:String = shares, pageNumber:int = 1):void

Retrieves the game shares made or liked by this player.

NOTE: The player must be logged in to access user game shares

Parameters

callback:Function — A method to handle retrieving the game shares from the server.
 
listMetric:String (default = shares) — The metric to narrow the search within. Values include: "shares" and "likes".
 
pageNumber:int (default = 1) — The page number to retrieve. 32 shares per page.

See also


Example
This example shows how to retrieve a list of game shares made by this player and output their names.
 agi.retrieveUserGameShares( callback, "shares" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Game Share Name: " + item.name );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 metric : String - List metric of the game share retrieved.
 total : Number - Total number of game shares on the server.
 averageFunFactor : Number - A value between 0 and 100 that represents the average fun factor across all game shares by this user (Only valid if listMetric = "shares").
 totalViews : Number - Total number of plays/views across all games shares by this user (Only valid if listMetric = "shares").
 totalLikes : Number - Total number of likes across all game shares by this user (Only valid if listMetric = "shares").
 totalStaffPicks : Number - Total number of game shares are staff picked from this user (Only valid if listMetric = "shares").
 list : Array - Contains all the game shares in Object form for this timeFrame and metric. Each Object includes these properties:
     name : String - Name of the game share retrieved.
     share_id : String - Share ID of the game share.
     url : String - Share URL given to the game share.
     long_url : String - Longer URL to the game share.
     thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
     timestamp : Number - The UTC time when the player created the game share.
     createdOn : String - A user friendly date when the player created the game share.
     funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
     staffPick : Boolean - Value is true if the game share has been staff picked.
     totalLikes : Number - Total number of likes a game share has received.
     likes : Object - Pertains to how many likes a game share has received. Properties include:
         daily : Number - Number of likes this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     totalViews : Number - Total number of views a game share has received.
     views : Object - Pertains to how many times a game share has been viewed. Properties include:
         daily : Number - Number of views this game share received.
         weekly : Number - (Same as above).
         monthly : Number - (Same as above).
         alltime : Number - (Same as above).
     username : String - Name of the player that created the game share. Value is null if submitted anonymously.
     avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
     profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
     countryCode : String - Country code of the user. Value is null if submitted anonymously.
     countryName : String - Country name of the user. Value is null if submitted anonymously. 

NOTE: The game share data property is not included in this list. This is due to keeping down the load of retrieving a list of game shares.

retrieveUserScores()method 
public function retrieveUserScores(callback:Function, scoreType:String = null, sortDescending:Boolean = true, pageNumber:int = 1):void

Retrieves a list of the users highscores on the server. Will return a false success if the user is not logged in.

Parameters

callback:Function — A method to pass the high scores once they are retrieved from the server.
 
scoreType:String (default = null) — The type of scores to get from the server. (Ex. null, "easy", "hard").
 
sortDescending:Boolean (default = true) — Whether or not to sort the scores descending or ascending.
 
pageNumber:int (default = 1) — The page number to retrieve. 25 scores per page.

See also


Example
This example uses the callback and traces out the the list of scores for this user.
 agi.retrieveUserScores( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
This example performs the same as above except it displays all the scores for the score type "easy".
 agi.retrieveUserScores( callback, "easy" );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         var item:Object;
         for(var i:int = 0; i < data.list.length; i++)
         {
             item = data.list[i];
             trace( "Score: " + item.score );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not. If the user is not logged in, this value will be false.
 error : String - If success is false, this will give more information as to why the call failed.
 scoreType : String - Type of score that was requested.
 sortDesc : Boolean - Whether or not the scores are listed descending or ascending.
 total : Number - Total number of scores on the server for this scoreType and timeFrame.
 average : Number - Average score of all the scores on the server for this scoreType and timeFrame.
 page : Number - Page number that was requested.
 currentTime : Number - The UTC time of the server.
 topScore : Number - The top score of the user.
 rank : Object - Ranking of the player on the server. Properties include:
     alltime : Object
         rank : Number - Position the player ranked in on the server.
         total : Number - Total positions the player was ranked within.
 list : Array - List containing all the high score objects on the server for this scoreType and timeFrame. Each object contains these properties:
     score : Number - The score value of the player.
     playerName : String - The name of the player.
     scoreType : String - The type of score this player submitted.
     countryCode : String - A string representing the country code the user submitted their score from.
     countryName : String - Name of the country the player submitted a score in.
     relativeTime : String - A user friendly date when the player submited their score.
     time : Number - The UTC time when the player submitted their score.
     avatar_url : String - The url to where the players avatar image is located. Value is null if the player is not a registered user.
     profile_url : String - The url to the players profile page. Value is null if the player is not a registered user. 
setDebugOutputCallback()method 
public function setDebugOutputCallback(callback:Function):void

This method exists solely for the purpose of testing within the browser when the trace output panel is unavailable. All debug output will be sent to this callback method allowing the developer to define where and how to display it (on screen). By default, debug mode is turned off for the AGI and must be turned on through the init() method for the callback to report more useful debug information.

Parameters

callback:Function — A method to handle the debug output

See also


Example
This example uses the callback to output to a generic text field that is assumed to be on screen already (debug_txt).
 agi.setDebugOutputCallback( callback );
 function callback( msg:String ):void
 {
     debug_txt.appendText( msg + "\n" );
 } 
showGameShareList()method 
public function showGameShareList(shareClickCallback:Function = null, parentObj:* = null):void

Brings up the a list of the top game shares on the server and allows the player navigate through them.

When a player is viewing the Game Share List, he/she can click on a game share to play it at any time. Upon clicking a game share, the list is set to invisible and a Game Share Navigational Element (Navi) is brought on screen. To change properties of this Navi, view the initAGUI() method.

Parameters

shareClickCallback:Function (default = null) — A method to handle when a user clicks on a game share.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGUI as a child in.

See also


Example
The following example shows the game share list and listens for a share to be clicked on by the player using the AGUI.
 agi.showGameShareList( handleShareClick );
 function handleShareClick( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 data : String - Data of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
 timestamp : Number - The UTC time when the player created the game share.
 createdOn : String - A user friendly date when the player created the game share.
 funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
 totalLikes : Number - Total number of likes a game share has received.
 likes : Object - Pertains to how many likes a game share has received. Properties include:
     daily : Number - Number of likes this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 totalViews : Number - Total number of views a game share has received.
 views : Object - Pertains to how many times a game share has been viewed. Properties include:
     daily : Number - Number of views this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 username : String - Name of the player that created the game share. Value is null if submitted anonymously.
 avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
 profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
 countryCode : String - Country code of the user. Value is null if submitted anonymously.
 countryName : String - Country name of the user. Value is null if submitted anonymously. 
showGameShareNavi()method 
public function showGameShareNavi(x:Number, y:Number, randomShareClickCallback:Function = null, parentObj:* = null):void

Brings up the game share naviagtional element (Navi) using the AGUI.

NOTE: Show this tool after you have retrieved a game share using the isComingFromShareURL() method.

Parameters

x:Number (default = NaN) — X screen coordinate to place the game share navi at.
 
y:Number (default = NaN) — Y screen coordinate to place the game share navi at.
 
randomShareClickCallback:Function (default = null) — A method to handle when a user clicks on the random game share button.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGUI as a child in.

See also

showGameShareSubmit()method 
public function showGameShareSubmit(data:String, shareName:String, thumbnail:DisplayObject = null, shareClickCallback:Function = null, parentObj:* = null):void

Brings up the submit panel that shows the thumbnail passed in and allows the player to submit their game share to the server.

After the players game share is submitted successfully, the player can then view the top games share submitted within the game share list.

When a player is viewing the Game Share List, he/she can click on a game share to play it at any time. Upon clicking a game share, the list is set to invisible and a Game Share Navigational Element (Navi) is brought on screen. To change properties of this Navi, view the initAGUI() method.

Parameters

data:String — The data to submit to the game share server.
 
shareName:String — The name to auto fill in the input field of the submit page.
 
thumbnail:DisplayObject (default = null) — An icon or thumbnail picture given to the data you are sharing.
 
shareClickCallback:Function (default = null) — A method to handle when a user clicks on a game share within the game share list.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGUI as a child in.

See also


Example
The following example submits a game share and listens for a share to be clicked on by the player when viewing the game share list in the AGUI.
 agi.showGameShareSubmit( "My Game Share Data", null, myThumbnail, handleShareClick );
 function handleShareClick( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the client game is being played from a shared URL.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 data : String - Data of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels).
 timestamp : Number - The UTC time when the player created the game share.
 createdOn : String - A user friendly date when the player created the game share.
 funFactor : Number - A value between 0 and 100 that represents how fun a game share is.
 totalLikes : Number - Total number of likes a game share has received.
 likes : Object - Pertains to how many likes a game share has received. Properties include:
     daily : Number - Number of likes this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 totalViews : Number - Total number of views a game share has received.
 views : Object - Pertains to how many times a game share has been viewed. Properties include:
     daily : Number - Number of views this game share received.
     weekly : Number - (Same as above).
     monthly : Number - (Same as above).
     alltime : Number - (Same as above).
 username : String - Name of the player that created the game share. Value is null if submitted anonymously.
 avatar_url : String - URL to the users avatar image. Value is null if submitted anonymously.
 profile_url : String - URL to the users profile page on armorgames.com. Value is null if submitted anonymously.
 countryCode : String - Country code of the user. Value is null if submitted anonymously.
 countryName : String - Country name of the user. Value is null if submitted anonymously. 
showLogin()method 
public function showLogin(callback:Function = null, parentObj:* = null):void

Brings up the AGUI login panel where the player can login to his or her account.

If the player is already logged in, the panel will show his/her profile page instead. There the player can either logout or continue.

If you want to show the player his/her login status, check out the showLoginStatus() method.

Parameters

callback:Function (default = null) — A callback to listen for login/logout of the player.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGI as a child in.

See also


Example
The following example will bring up the AGUI login panel and listen for when the player logs in or out.
 agi.showLogin( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         if( data.loggedIn )
         {
             trace( data.username );
         }
         else
         {
             trace( "Player logged out" );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not.
 error : String - If success is false, this will give more information as to why the call failed.
 loggedIn : Boolean - True if the player logged in, false if the player logged out.
 username : String - Name of the user.
 avatar_url : String - URL to the users avatar image.
 profile_url : String - URL to the users profile page on armorgames.com.
 countryCode : String - Country code of the user.
 countryName : String - Country name of the user. 
showLoginStatus()method 
public function showLoginStatus(x:Number = 0, y:Number = 0, loginCallback:Function = null, parentObj:* = null):void

Shows the Login Status button on screen.

The Login Status button can be used to visually show the player whether or not he/she is logged in to the AGI.

It also allows the player to login/logout of the AGI directly just by clicking on the button.

The button is 160 x 30 pixels.

Parameters

x:Number (default = 0) — X screen coordinate to place the button at.
 
y:Number (default = 0) — Y screen coordinate to place the button at.
 
loginCallback:Function (default = null) — A callback to listen for login/logout initiated by the player.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGI as a child in.

See also


Example
The following example shows how to listen for a login/logout initiated by the player.
 agi.showLoginStatus( 0, 0, callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         if( data.loggedIn )
         {
             trace( data.username );
         }
         else
         {
             trace( "Player logged out" );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not.
 error : String - If success is false, this will give more information as to why the call failed.
 loggedIn : Boolean - True if the player logged in, false if the player logged out.
 username : String - Name of the user.
 avatar_url : String - URL to the users avatar image.
 profile_url : String - URL to the users profile page on armorgames.com.
 countryCode : String - Country code of the user.
 countryName : String - Country name of the user. 
showScoreboardList()method 
public function showScoreboardList(scoreTypes:Array = null, defaultScoreType:String = null, parentObj:* = null):void

Brings up a Scoreboard that shows the top scores on the server for the client game using the AGUI.

The scoreTypes parameter is used to display only the score types you want the AGUI to display. It can also be used to order the scores in ascending/descending order and/or format the scores to be viewed in "time" or "cash" formatting. NOTE: "time" formatting is in seconds, not milliseconds.

By default, the scoreTypes parameter is null, which means all score types submitted will be displayed using default values.

The defaultScoreType parameter is used to set the default score type to display when viewing the top scores.

Parameters

scoreTypes:Array (default = null) — An array of Objects that format how the each score type is displayed within the AGUI Scoreboard.
 
defaultScoreType:String (default = null) — The score type to open by default when the list is opened.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGUI as a child in.

See also


Example
The following example will bring up the scoreboard list using default display values.
 agi.showScoreboardList(); 
This example shows how to display the list of scores under a default (null) score type in "time" formatting in ascending order.
 agi.showScoreboardList( [ { format:"time", descending:false } ] ); 
This example shows how to format the display of each score type within the list and open the "easy" scores first.

It shows two score types: "easy" and "hard" and formats how each are displayed.

 var easyType:Object = new Object();
 easyType.type = "easy";
 easyType.format = "none";
 easyType.descending = false;
 
 var hardType:Object = new Object();
 hardType.type = "hard";
 hardType.format = "custom";
 hardType.customFormatCallback = myFormat;
 hardType.descending = true;
 
 function myFormat( score:Number ):String
 {
     return score + " Ft";
 }
 
 var scoreTypes:Array = new Array();
 scoreTypes.push( easyType );
 scoreTypes.push( hardType );
 
 agi.showScoreboardList( scoreTypes, "easy" ); 
The scoreTypes parameter must be an Array of Objects. Each object can contain any one of these properties:
 type : String (Default = null) - Name of the score type.
 descending : Boolean (Default = true) - Whether or not to display scores in descending or ascending order.
 format : String (Default = "none") - A string representing how to display the scores. (Values: "time", "cash", "custom", "none").
 customFormatCallback : Function - A method the AGUI scoreboard can use to custom format the display of each score value (format must be "custom"). Method must take in a Number as a parameter and return a String.
 
showScoreboardSubmit()method 
public function showScoreboardSubmit(score:uint, playerName:String = null, scoreType:String = null, scoreTypes:Array = null, parentObj:* = null):void

Brings up a submit panel that shows the player his/her score and allows them to submit it to the server using the AGUI.

After the players score is submitted successfully, the player can then view their ranking amongst top scores using the scoreboard list in the AGUI.

For this method, the scoreType parameter is used to group scores into categories. This is developer created group that can be applied to any score. For example, a game might have "easy" and "hard" modes and would need top scores for each mode.

By default, the scoreType is null which assumes no score types for this game. If you only have one score type, leave this parameter null.

The scoreTypes parameter is used to display only the score types you want the AGUI to display. It can also be used to order the scores in ascending/descending order and/or format the scores to be viewed in "time" or "cash" formatting. NOTE: "time" formatting is in seconds, not milliseconds.

By default, the scoreTypes parameter is null, which means all score types submitted will be displayed using default values.

Parameters

score:uint — Positive integer score of the player
 
playerName:String (default = null) — Name of the player to fill in the input field.
 
scoreType:String (default = null) — Type of score to submit.
 
scoreTypes:Array (default = null) — An array of Objects that format how the each score type is displayed within the AGUI Scoreboard.
 
parentObj:* (default = null) — DisplayObjectContainer to place the AGI as a child in.

See also


Example
The following example shows how to submit a score of 100.
 agi.showScoreboardSubmit( 100 ); 
This example shows how to submit a score of 100 and to display it in "time" formatting in ascending order.
 agi.showScoreboardSubmit( 100, null, null, [ { format:"time", descending:false } ] ); 
This example shows how to submit a score of 100 using a scoreType of "easy".

The example code also shows how to format multiple scoreTypes.

 var easyType:Object = new Object();
 easyType.type = "easy";
 easyType.format = "none";
 easyType.descending = false;
 
 var hardType:Object = new Object();
 hardType.type = "hard";
 hardType.format = "custom";
 hardType.customFormatCallback = myFormat;
 hardType.descending = true;
 
 function myFormat( score:Number ):String
 {
     return score + " Ft";
 }
 
 var scoreTypes:Array = new Array();
 scoreTypes.push( easyType );
 scoreTypes.push( hardType );
 
 agi.showScoreboardSubmit( 100, null, "easy", scoreTypes ); 
The scoreTypes parameter must be an Array of Objects. Each object can contain any one of these properties:
 type : String (Default = null) - Name of the score type.
 descending : Boolean (Default = true) - Whether or not to display scores in descending or ascending order.
 format : String (Default = "none") - A string representing how to display the scores. (Values: "time", "cash", "custom", "none").
 customFormatCallback : Function - A method the AGUI scoreboard can use to custom format the display of each score value (format must be "custom"). Method must take in a Number as a parameter and return a String.
 
showUserProfile()method 
public function showUserProfile(loginCallback:Function = null, parentObj:* = null):void

Brings up the AGUI user profile page where the player can view their own profile.

If the player is not logged in already, the login panel will open up first and after successful login take them to their profile.

If you want to show the player his/her login status, check out the showLoginStatus() method.

Parameters

loginCallback:Function (default = null)
 
parentObj:* (default = null)

See also


Example
The following example will bring up the AGUI user profile panel and listen for when the player logs in or out.
 agi.showUserProfile( callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         if( data.loggedIn )
         {
             trace( data.username );
         }
         else
         {
             trace( "Player logged out" );
         }
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether the call was successful or not.
 error : String - If success is false, this will give more information as to why the call failed.
 loggedIn : Boolean - True if the player logged in, false if the player logged out.
 username : String - Name of the user.
 avatar_url : String - URL to the users avatar image.
 profile_url : String - URL to the users profile page on armorgames.com.
 countryCode : String - Country code of the user.
 countryName : String - Country name of the user. 
submitGameShare()method 
public function submitGameShare(name:String, data:String, callback:Function = null, thumbnail:* = null):void

Submits game share to the server.

Parameters

name:String — Name of the data being shared
 
data:String — Actual data to share
 
callback:Function (default = null) — A method to handle retrieving the short url from the server.
 
thumbnail:* (default = null) — An icon or thumbnail picture given to the data you are sharing. (Will be scaled down to 135 x 90 pixels).


Example
This example shows how submit a game share to the server using the thumbnail myThumbnail and listens for a successful submit.
 agi.submitGameShare( "My Game Share", "My Game Share Data", callback, myThumbnail );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Game Share was submitted successfully" );
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the game share was submitted successfully.
 error : String - If success is false, this will give more information as to why the call failed.
 name : String - Name of the game share retrieved.
 share_id : String - Share ID of the game share.
 url : String - Share URL given to the game share.
 long_url : String - Longer URL to the game share.
 thumb_url : String - URL to the thumbnail image given to the game share. (135 x 90 pixels). 
submitPublicData()method 
public function submitPublicData(key:String, data:*, callback:Function = null):void

Submits game save data to a public space.

Public data is data that any client game can access regardless of user.

Parameters

key:String — A value to represent the data being stored. Used in retrieving public data.
 
data:* — The data to be stored. This value can be a Number, String, Array, or an Object.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will submit an Array to the server given a name of "myData".
 agi.submitPublicData( "myData", [1,2,3,4,5] ); 
This example will submit a String to the server given a name of "myString" and listen for a callback.
 agi.submitPublicData( "myString", "String of really cool data", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Submit Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
submitPublicDataObject()method 
public function submitPublicDataObject(obj:Object, callback:Function = null):void

Submits game save data to a public space in Object form.

Public data is data that any client game can access regardless of user.

Parameters

obj:Object — Object where each propertyName is used as a key and each propertyValue is used as data.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will submit an Object with 2 properties to the server and listen for a callback.
 agi.submitPublicDataObject( { myData:[1,2,3,4,5], myString:"String of really cool data" }, callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Submit Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
submitScore()method 
public function submitScore(playerName:String, score:uint, scoreType:String = null, callback:Function = null, sortListDescending:Boolean = true):void

Submits a player score to the server.

Parameters

playerName:String — Name of the player.
 
score:uint — A positive number of the player's score.
 
scoreType:String (default = null) — The type of score you are submitting. Leave null if only on type. (Ex. null, "easy", "hard").
 
callback:Function (default = null) — A method to handle a successful score submit or not.
 
sortListDescending:Boolean (default = true) — A boolean value that helps the backend determine how to overwrite the score value if the player's name and IP address are the same.


Example
This example shows how to submit a score using a score type.
 agi.submitScore( "John Doe", 100, "easy" ); 
Now all scores submitted under the "easy" score type will be grouped together on the server.
This example listens for a callback and then traces out the name of the player and the score that was submitted.
 agi.submitScore( "John Doe", 100, null, callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( data.playerName );
         trace( data.score );
     }
     else
     {
         trace( data.error );
     }
 } 
Properties attached to the data:Object include:
 success : Boolean - Whether or not the call was successful.
 error : String - If success is false, this will give more information as to why the call failed.
 playerName : String - Name the player submitted (Modified for explicit material if needed).
 score : Number - Score the player submitted.
 scoreType : String - Type of score the player submitted under. Value is null if nothing was passed in to the scoreType parameter.
 sortDesc : Boolean - Whether the list is sorted descending or ascending.
 beatTopScore : Boolean - Whether or not the player beat their previous top score.
 prevTopScore : Number - Previous top score the player achieved. Value is null if no previous score.
 prevTopScoreDate : String - A string representing the date the player achieved their previous top score. Value us null if no previous score.
 avatar_url : String - A url pointing to the avatar image of a registered user. (Value is null if player is not a registered user).
 rank : Object - Ranking of the player on the server. Properties include:
     daily : Object
         rank : Number - Position the player ranked in on the server.
         total : Number - Total positions the player was ranked within.
     weekly : Object
         rank : Number - (Same as above).
         total : Number - (Same as above).
     alltime : Object
         rank : Number - (Same as above).
         total : Number - (Same as above). 
submitUserData()method 
public function submitUserData(key:String, data:*, callback:Function = null):void

Submits game save data associated with a user.

NOTE: The user must be logged in in order to modify user data.

Parameters

key:String — A value to represent the data being stored. Used in retrieving public data.
 
data:* — The data to be stored. This value can be a Number, String, Array, or an Object.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will submit an Array to the server given a name of "myData".
 agi.submitUserData( "myData", [1,2,3,4,5] ); 
This example will submit a String to the server given a name of "myString" and listen for a callback.
 agi.submitUserData( "myString", "String of really cool data", callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Submit Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
submitUserDataObject()method 
public function submitUserDataObject(obj:Object, callback:Function = null):void

Submits game save data associated with a user in Object form.

NOTE: The user must be logged in in order to modify user data.

Parameters

obj:Object — Object where each propertyName is used as a key and each propertyValue is used as data.
 
callback:Function (default = null) — A callback to determine if the call was successful.

See also


Example
This example will submit an Object with 2 properties to the server and listen for a callback.
 agi.submitUserDataObject( { myData:[1,2,3,4,5], myString:"String of really cool data" }, callback );
 function callback( data:Object ):void
 {
     if( data.success )
     {
         trace( "Submit Successful" );
     }
     else
     {
         trace( data.error );
     }
 } 
unlikeGameShare()method 
public function unlikeGameShare(shareId:String):void

Removes a game share from the users likes list.

NOTE: Will fail if the user is not logged in.

Parameters

shareId:String — ID of the game share to unlike.

See also

Examples
The following example shows how to get the AGI up and running:
 import flash.system.Security;
 import flash.net.URLRequest;
 import flash.display.Loader;
 import flash.events.Event;
 
 // URL to the AGI swf.
 var agi_url:String = "http://agi.armorgames.com/assets/agi/AGI.swf";
 Security.allowDomain( agi_url );
 
 // Developer key and game key (used for AGI authentication).
 // NOTE: Use your own developer key and game key.
 var devKey:String = "00a1e7f345d3af9e747e4d09388dce13";
 var gameKey:String = "agi-example";
 
 // AGI reference
 var agi:Object;
 
 // Load the AGI
 var urlRequest:URLRequest = new URLRequest( agi_url );
 var loader:Loader = new Loader();
 loader.contentLoaderInfo.addEventListener( Event.COMPLETE, loadComplete );
 loader.load( urlRequest );
 
 // Handle AGI loaded
 function loadComplete( e:Event ):void
 {
     // Save the AGI reference
     agi = e.currentTarget.content;
 
     // Add the AGI as a child to your document class or lowest level display object (required)
     addChild( agi );
 
     // Initialize the AGI with your developer key and game key
     agi.init( devKey, gameKey );
 }
 
The following example shows how to use the Highscore System using the AGUI.
 // Submits a score of 100 using the AGUI.
 agi.showScoreboardSubmit( 100 );
 
 // Brings up the list of all the top scores in the system using the AGUI.
 agi.showScoreboardList();
 
The following example shows how to use the Game Share System using the AGUI.
 //The following example will submit the game share data myShareData going by the name of myShareName using the thumbnail myShareThumbnail using the AGUI.
 agi.showGameShareSubmit( myShareData, myShareName, myShareThumbnail, handleShareClick );
 function handleShareClick( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( data.error );
     }
 } 
 //The following example brings up the game share list using the AGUI.
 agi.showGameShareList( handleShareClick );
 function handleShareClick( data:Object ):void
 {
     if( data.success )
     {
         trace( data.name );
         trace( data.data );
     }
     else
     {
         trace( data.error );
     }
 }