Browse Sections

About Newgrounds Help & Information Creator Resources

Newgrounds Wiki: API

  • Package: com.newgrounds
  • Class: API
The main interface for the Newgrounds API.

Page Contents

Methods

These are the methods of API.

addEventListener

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

createSaveQueryByName

Return to Top ^
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

createSaveQueryByRating

Return to Top ^
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

createSaveQuery

Return to Top ^
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

Return to Top ^
public static function disconnect():void


Disconnects from the Newgrounds API.

getMedal

Return to Top ^
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
  • Returns
    • Medal
      The Medal object with the specified name.

getSaveGroup

Return to Top ^
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
  • Returns
    • SaveGroup
      The SaveGroup object with the matching name, or null if the save group is not found.

getScoreBoard

Return to Top ^
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
  • Returns
    • ScoreBoard
      The ScoreBoard object with the matching name.

loadCustomLink

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
public static function loadNewgrounds():void


Loads newgrounds.com in a new browser window.

loadOfficialVersion

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
public static function stopPendingCommands():void


Stops any pending API commands.

unlockMedal

Return to Top ^
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

Return to Top ^
public static var adsApproved:Boolean;


Specifies whether ads have been approved for this game.

apiId

Return to Top ^
public static var apiId:String;


The API ID of the movie. The API ID is set when connect is called.

connected

Return to Top ^
public static var connected:Boolean;


Returns true if the API has connected successfully.

debugMode

Return to Top ^
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

Return to Top ^
public static var hasUserSession:Boolean;


Specifies whether the user is logged in.

hostDomain

Return to Top ^
public static var hostDomain:String;


The domain that is hosting the file.

hostURL

Return to Top ^
public static var hostURL:String;


The full URL to this file.

isNetworkHost

Return to Top ^
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

Return to Top ^
public static var isNewgrounds:Boolean;


Specifies whether the game is hosted on Newgrounds.

medals

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
public static var userId:uint;


The ID of the user.

username

Return to Top ^
public static var username:String;


The username of the user.

Constants

These are the constants of API.

DEBUG_MODE_HOST_BLOCKED

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
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

Return to Top ^
public static const RELEASE_MODE:String = "releaseMode";


The RELEASE_MODE debug setting will cause the API to operate normally, without any debug functionality.

VERSION

Return to Top ^
public static const VERSION:String = "3.0.4.3 beta AS3";


Specifies the version of the Newgrounds API. 11