- Package: com.newgrounds
- Class: API
The main interface for the Newgrounds API.
Methods
These are the methods of API.
addEventListener
public static function addEventListener(eventType:String, listener:Function, priority:int, useWeakReference:Boolean):void
Registers an event listener object with the API so that the listeners receives notification of an event.
- Parameters
- eventType:String
- The type of the event. Should match an event type in APIEvent.
- listener:Function
- The listener function that processes the event. The function must accept an event object as its only parameter.
- priority:int
- The priority level of the event listener. The higher the number, the higher the priority. All listeners with priorty n are processed before listeners of priority n-1.
- useWeakReference:Boolean
- Determines whether the reference to the listener is strong or weak. A strong reference prevents your listener from being garbage-collected.
connect
public static function connect(root:DisplayObject, apiId:String, encryptionKey:String, movieVersion:String):void
Initializes the Newgrounds API and starts a connection to the Newgrounds server. This should be called before any other API methods or properties.
After calling connect, the API will fire an API_CONNECTED event. If version control is enabled for the game and a new version is available, event.data.newVersion will be true.
- Parameters
- root:DisplayObject
- The root DisplayObject.
- apiId:String
- The API ID for this movie, as shown on the API settings page.
- encryptionKey:String
- The encryption key for this movie, as shown on the API settings page.
- movieVersion:String
createSaveFile
public static function createSaveFile(groupName:String):SaveFile
Creates a new save file.
- Parameters
- groupName:String
- The name of the save group to which this file will belong.
- Returns
- SaveFile
- The newly created SaveFile, or null if an error occurred.
createSaveQueryByDate
public static function createSaveQueryByDate(groupName:String, sortDescending:Boolean):SaveQuery
Creates a save query that will list files sorted by date.
- Parameters
- groupName:String
- The name of the save group to query.
- sortDescending:Boolean
- If true, newer files will be listed first. Otherwise, older files will be listed first.
- Returns
- SaveQuery
createSaveQueryByName
public static function createSaveQueryByName(groupName:String, filename:String, exactMatch:Boolean, sortDescending:Boolean):SaveQuery
Creates a save query that will search for save files by name.
- Parameters
- groupName:String
- The name of the save group to query.
- filename:String
- The name to search for.
- exactMatch:Boolean
- If true, the query only list files that have the exact name. Otherwise, the query lists files that contain the name.
- sortDescending:Boolean
- If false, files will be listed in alphabetical order.
- Returns
- SaveQuery
createSaveQueryByRating
public static function createSaveQueryByRating(groupName:String, ratingName:String, sortDescending:Boolean):SaveQuery
Creates a new save query that will list files sorted by rating.
- Parameters
- groupName:String
- The name of the save group to query.
- ratingName:String
- The rating to sort by.
- sortDescending:Boolean
- If true, the highest rating submissions will be listed first.
- Returns
- SaveQuery
createSaveQuery
public static function createSaveQuery(groupName:String):SaveQuery
Creates a new save query.
- Parameters
- groupName:String
- The name of the save group to query.
- Returns
- SaveQuery
- The newly created save query, or null if an error occurred.
disconnect
public static function disconnect():void
Disconnects from the Newgrounds API.
getMedal
public static function getMedal(medalName:String):Medal
Returns the medal with the specified name. Returns null if no medal with that name exists for this game, or the API is disconnected.
- Parameters
- medalName:String
- Returns
- Medal
- The Medal object with the specified name.
getSaveGroup
public static function getSaveGroup(groupName:String):SaveGroup
Returns the save group with the specified name. Returns null if no save group with that name exists, or the API is disconnected.
- Parameters
- groupName:String
- Returns
- SaveGroup
- The SaveGroup object with the matching name, or null if the save group is not found.
getScoreBoard
public static function getScoreBoard(scoreBoardName:String):ScoreBoard
Returns the score board with the specified name. Returns null if no score board with that name exists for this game, or the API is disconnected.
- Parameters
- scoreBoardName:String
- Returns
- ScoreBoard
- The ScoreBoard object with the matching name.
loadCustomLink
public static function loadCustomLink(linkName:String):void
Loads a custom website in a new browser window. You can manage your custom websites on your API Settings page.
- Parameters
- linkName:String
- The name of the custom website to be loaded. This should match the name of a link on your API Settings page.
loadLocal
public static function loadLocal(saveId:String):Object
Loads data that was saved locally to this computer with saveLocal.
- Parameters
- saveId:String
- The id of the data to load.
- Returns
- Object
- The loaded data. Returns null if the data does not exist or could not be loaded.
loadMySite
public static function loadMySite():void
Loads your personal website in a new browser window. You can specify the URL for your site on your API Settings page.
loadNewgrounds
public static function loadNewgrounds():void
Loads newgrounds.com in a new browser window.
loadOfficialVersion
public static function loadOfficialVersion():void
Loads the official version of this game in a new browser window. The URL for the official version can be set on your API Settings pages.
loadSaveFile
public static function loadSaveFile(saveId:uint, loadContents:Boolean):void
Loads a save file with the specified save ID.
- Parameters
- saveId:uint
- The ID of the file to load.
- loadContents:Boolean
- If true, the file contents will be loaded. Otherwise, only the file metadata will be loaded.
loadScores
public static function loadScores(scoreBoardName:String, period:String, firstResult:uint, numResults:uint, tag:String):ScoreBoard
Loads a list of scores from a score board. The API will fire a SCORES_LOADED event when the scores have loaded, or an error occurs.
- Parameters
- scoreBoardName:String
- The name of the score board that will load scores.
- period:String
- The timeframe for which to load scores. Defaults to listing the best scores of all-time, ScoreBoard.ALL_TIME.
- firstResult:uint
- The rank of the first result to load. Scores start from rank 1.
- numResults:uint
- The number of scores to load.
- tag:String
- Filter scores based on their tag. If tag is null, all scores will be listed. Otherwise, only scores with the matching tag will be listed.
- Returns
- ScoreBoard
- The ScoreBoard object with the matching name.
logCustomEvent
public static function logCustomEvent(eventName:String):void
Logs a custom event with the API. This method can be used for stat tracking and custom metrics in your game. You can view these stats on your API settings page.
- Parameters
- eventName:String
- The name of the custom event to log.
postScore
public static function postScore(scoreBoardName:String, numericScore:Number, tag:String):void
Submits a score to a score board. The API will fire a SCORE_POSTED event if the score was posted, or if there was an error. The player must be logged-in and playing on Newgrounds to submit a score. Only the player's best score is posted to the score board.
- Parameters
- scoreBoardName:String
- The name of the score board.
- numericScore:Number
- The player's score.
- tag:String
removeEventListener
public static function removeEventListener(eventType:String, listener:Function):void
Removes a listener from the API. If there is no matching listener registered, a call to this method has no effect.
- Parameters
- eventType:String
- The type of the event.
- listener:Function
- The listener object to remove.
saveLocal
public static function saveLocal(saveId:String, saveData:Object):Boolean
Saves data locally to this computer. To save data to a Newgrounds account, use SaveFile.
- Parameters
- saveId:String
- An identifier for this data.
- saveData:Object
- The data to save.
- Returns
- Boolean
- Returns true if the data was saved, false otherwise.
stopPendingCommands
public static function stopPendingCommands():void
Stops any pending API commands.
unlockMedal
public static function unlockMedal(medalName:String):void
Unlocks a medal. Medal names are case sensitive. The API will fire a MEDAL_UNLOCKED event on success or failure. If a user is logged-in and playing on Newgrounds, the medal will unlock on their account and be visible in their profile. If a user is not on Newgrounds or not logged-in, then the medal unlock will be stored locally on their computer.
- Parameters
- medalName:String
- The name of the medal to unlock.
Properties
These are the properties of API.
adsApproved
public static var adsApproved:Boolean;
Specifies whether ads have been approved for this game.
apiId
public static var apiId:String;
The API ID of the movie. The API ID is set when connect is called.
connected
public static var connected:Boolean;
Returns true if the API has connected successfully.
debugMode
public static var debugMode:String;
The debug mode of the movie. The debug mode allows you to easily test different use cases during development. If debugMode is set to RELEASE_MODE, then the API operates normally. If debugMode is set to DEBUG_MODE_LOGGED_IN, then the API operates as if a logged-in user was viewing the movie on Newgrounds. If a game is played on the web, debugMode will automatically turn off and revert to RELEASE_MODE. However, it is still a good practice to set debugMode to RELEASE_MODE before making your game publically available.
hasUserSession
public static var hasUserSession:Boolean;
Specifies whether the user is logged in.
hostDomain
public static var hostDomain:String;
The domain that is hosting the file.
hostURL
public static var hostURL:String;
The full URL to this file.
isNetworkHost
public static var isNetworkHost:Boolean;
isNetworkHost is true if the movie is hosted on the web, or false if the movie is running locally.
isNewgrounds
public static var isNewgrounds:Boolean;
Specifies whether the game is hosted on Newgrounds.
medals
public static var medals:Array;
Returns a list of the medals for this game. Returns an empty array if there are no medals, or the API has not connected.
publisherId
public static var publisherId:uint;
The publisher ID of the site that is hosting this game. If the game is hosted by an unknown publisher or running locally, publisherId is 0. If the game is hosted by Newgrounds, publisherId is 1.
saveGroups
public static var saveGroups:Array;
Returns a list of save groups for this game. Returns an empty array if this game has no save groups, or the API has not connected.
scoreBoards
public static var scoreBoards:Array;
Returns a list of scoreboards for this game. Returns an empty array if this game has no scoreboards, or the API has not connected.
sessionId
public static var sessionId:String;
The session ID of the user playing the game. If the user is not logged-in, session ID is 0.
userId
public static var userId:uint;
The ID of the user.
username
public static var username:String;
The username of the user.
Constants
These are the constants of API.
DEBUG_MODE_HOST_BLOCKED
public static const DEBUG_MODE_HOST_BLOCKED:String = "debugModeHostBlocked";
The DEBUG_MODE_NEW_VERSION debug setting will cause the API to operate as if sitelocking is enabled, and the file is hosted on a blocked domain. The API_CONNECTED event will fail with a HOST_BLOCKED error.
DEBUG_MODE_LOGGED_IN
public static const DEBUG_MODE_LOGGED_IN:String = "debugModeLoggedIn";
The DEBUG_MODE_LOGGED_OUT debug setting will cause the API to operate as if the user was on Newgrounds while logged-in.
DEBUG_MODE_LOGGED_OUT
public static const DEBUG_MODE_LOGGED_OUT:String = "debugModeLoggedOut";
The DEBUG_MODE_LOGGED_OUT debug setting will cause the API to operate as if the user was on Newgrounds, but not logged-in.
DEBUG_MODE_NEW_VERSION
public static const DEBUG_MODE_NEW_VERSION:String = "debugModeNewVersion";
The DEBUG_MODE_NEW_VERSION debug setting will cause the API to operate as if there is a new version of the movie available. The API_CONNECTED will have the newVersion flag set.
RELEASE_MODE
public static const RELEASE_MODE:String = "releaseMode";
The RELEASE_MODE debug setting will cause the API to operate normally, without any debug functionality.
VERSION
public static const VERSION:String = "3.0.4.3 beta AS3";
Specifies the version of the Newgrounds API. 11