Note: This document refers to gateway for version 2 of the API. For version 3 see Newgrounds.io.

The Developer Gateway is the bridge for all of our developer API Tools. This is where your projects can record statistics, check licences, record custom events and referrals, unlock medals, etc...

Many of the object values used by this gateway have been around since Newgrounds was exclusive to Flash games. Compiled Flash projects are called movies, so a lot of values will contain the word movie. There are also several inconsistencies in property names (sometimes username is used, other times user_name is used) you will need to be aware of. We apologize for any confusion this may cause.

Communication Protocols

The Developer Gateway takes POST requests over an HTTP connection and responds with JSON encoded objects.

The Developer Gateway is located at http://www.ngads.com/gateway_v2.php

Every request must have a valid command_id and tracker_id.

Some requests may require a publisher_id, user_name, user_id and/or a session_id. These are typically passed to a game dynamically via a request string (in the case of Flash games, these IDs are passed as FlashVars).

These values are as follows:

• NewgroundsAPI_SessionID - A random string that expires after 6 hours of inactivity.
• NewgroundsAPI_UserName - The name of the current player.
• NewgroundsAPI_UserID - The numeric user ID of the current player.
• NewgroundsAPI_PublisherID - The ID of the publisher hosting the game (usually 1 for Newgrounds).

Note: If you are using Flash, you should use the Flash API libraries available in the API Tools area of any game project.

Error Handling

All gateway responses will contain a 'success' parameter. If this value is 0, the API command failed.

All error objects contain the following properties:

• success = 0
• error_code - A code indicating what type of error was thrown (see below)
• command_id - The name of the command that failed
• error_msg - A message with additional details about the error

Error Codes

• 0 = UNKNOWN ERROR
• 1 = INVALID API ID
• 2 = MISSING PARAM
• 3 = INVALID STAT ID
• 4 = INVALID COMMAND ID
• 5 = FLASH ADS NOT APPROVED
• 6 = PERMISSION DENIED
• 7 = IDENTIFICATION REQUIRED
• 8 = INVALID EMAIL ADDRESS
• 9 = BANNED USER
• 10 = SESSION EXPIRED
• 11 = INVALID SCORE
• 12 = INVALID MEDAL
• 13 = FILE NOT FOUND
• 14 = INVALID FOLDER
• 15 = SITE ID REQUIRED
• 16 = UPLOAD IN PROGRESS
• 17 = USER CANCELLED
• 18 = CONFIRM REQUEST
• 19 = ILLEGAL REQUEST
• 20 = CONNECTION FAILED
• 21 = QUERY INCOMPLETE
• 22 = SAVE FILE ERROR
• 23 = INVALID VALUE
• 24 = SERVER ERROR

Commands

Below is a list of the available API commands. POST Values are the parameters you need to POST to the gateway. Return Object will be a JSON encoded object with specific properties.

For advanced response handling and debugging, you can POST a value named 'meta' with any command, and it will be sent back in the response object.

checkFilePrivs

Checks to see if a user has already created a file with the same filename, and if so, whether it can be overwritten or not.

Use this command before calling saveFile for cases where you would like to prompt the user about whether they want to replace an existing file.

POST Values

• command_id = checkFilePrivs
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game
• user_id - The user ID of the current player
• group - The ID of the save group the file belongs to
• filename - The name of the file to check

Return Object

• command_id = checkFilePrivs
• exists - True if the file exists
• can_write - true/false
• duplicate_id - if a file with the posted filename exists, this is its ID
• success = 1

connectMovie

Connecting to the gateway will record a view in your statistics and return any meta-data used by your game.

POST Values

• command_id = connectMovie
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game (optional)
• user_id - The user ID of the current player (optional)
• host - The domain currently hosting the game, ie: www.somesite.com
• preload - Set to 1 to automatically pre-load meta-data in this command (optional). See preloadSettings below.
• movie_version- The version id of the game being played (gets compared against current version)
• skip_ads - Set this to 1 if you do not want to use flash ads (or are not using flash at all).

Return Object

• command_id = connectMovie
• movie_name - The title of your game
• ad_url - The URL of a flash ad (flash games only).
• movie_version - The latest version of this game available (if posted version is out of date)
• movie_url - The URL to latest version of this game available (if posted version is out of date)
• time - A Unix timestamp indicating the local Newgrounds time
• success = 1

deleteSaveFile

Used to delete a user created file (if the calling user has sufficient permissions).

This command is sent as a secure packet (see securePacket command)

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• seed - The random salt string (will also need to be used in the encryption process)
• secure - An encrypted object (see Encryption Process) containing the following properties:
  • command_id = deleteSaveFile
  • publisher_id - The ID of the publisher hosting the game (optional, used to mark unlocked medals)
  • session_id - The current player session ID
  • save_id - The numeric ID of the saved file

Return Object

• command_id = deleteSaveFile
• save_id - The numeric ID of the deleted file
• success = 1

getMedals

Used to load medal data for the game.

POST Values

• command_id = getMedals
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game (optional, used to mark unlocked medals)
• user_id - The user ID of the current player (optional, used to mark unlocked medals)

Return Object

• command_id = getMedals
• medals - An array of medal objects (if the game uses them) with the following properties:
  • medal_id - The numeric id of the medal
  • medal_name - The name of the medal
  • medal_value - The point value of the medal
  • medal_difficulty - 1=easy, 2=moderate, 3=challenging, 4=difficult, 5=brutal
  • medal_unlocked - true/false (if publisher_id and user_id were passed)
  • medal_icon - The URL of the icon for this medal
  • secret - 1 if this is a secret medal
  • medal_description - The description of this medal
• success = 1

loadCustomLink

This command will redirect to custom link (provided in the "Referrals & Events" page of your game project API Tools) after logging a referral stat. This command should be sent in a new browser window.

POST Values

• command_id = loadCustomLink
• tracker_id - The tracker ID of your game
• host - The domain currently hosting the game, ie: www.somesite.com
• event - The name of your custom link

loadFriendList

• command_id = loadFriendList
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game
• user_id - The ID of the user you want to get the friend list for

Return Object

• command_id = loadFriendList
• friendlist - An array of user objects, each with the following properties:
  • publisher_id - The ID of the publisher hosting the game
  • user_id - The numeric ID of this user
  • user_name - The name of this user
  • user_icon - The URL to an icon for this user
  • user_url - A user page URL for this user
• success = 1

loadMySite

This command will redirect to the "My Site" URL (provided in the "Official URLs" page of your game project API Tools) after logging a referral stat. This command should be sent in a new browser window.

POST Values

• command_id = loadMySite
• tracker_id - The tracker ID of your game
• host - The domain currently hosting the game, ie: www.somesite.com

loadNewgrounds

This command will redirect to Newgrounds after logging a referral stat. This command should be sent in a new browser window.

POST Values

• command_id = loadNewgrounds
• tracker_id - The tracker ID of your game
• host - The domain currently hosting the game, ie: www.somesite.com

loadOfficialVersion

This command will redirect to the "Official URL" URL (provided in the "Official URLs" page of your game project API Tools) after logging a referral stat. This command should be sent in a new browser window.

POST Values

• command_id = loadOfficialVersion
• tracker_id - The tracker ID of your game
• host - The domain currently hosting the game, ie: www.somesite.com

loadSaveFile

Loads details of a save file

POST Values

• command_id = loadSaveFile
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game
• save_id - The ID of the save file to load

Return Object

• command_id = loadSaveFile
• file - A file details object containing the following properties:
  • save_id - The ID of the file
  • filename - The name of the file
  • user_id - The ID of the file author
  • user_name - The name of the file author
  • created - A unix timestamp indicating the date the file was first created
  • last_update - A unix timestamp indicating the date the file was last saved
  • views - The number of times this file has been viewed
  • status - 1=private, 2=shared, 3=unapproved, 4=approved
  • file - The relative path (from http://www.ngads.com/) to the save file
  • thumb - The relative path (from http://www.ngads.com/) to the thumbnail image
  • description - The description of the file
  • keys - An array of key objects associated with this file, each containing the following properties:
    • id - The ID of the key
    • value - The value of the key
  • ratings - An array of rating objects attached to this file, each with the following properties:
    • id - The ID of the rating
    • votes - The total number of votes cast to this rating
    • score - The score value of this rating
  • group_id - The ID of the save group this file belongs to
  • success = 1

loadScores

Loads a list of high scores.

POST Values

• command_id = loadScores
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game
• board - The ID of the score board
• period - "today" (default), "this week", "this month", "this year" or "all-time" (optional)
• num_results - The number of scores to show (optional)
• page - The page (optional). If num_results = 10 and page = 2, scores 11-20 will be loaded
• first result - The first index (optional). If num_results = 10 and first_result = 3, scores 4-13 will be loaded
• tag - Only load scores with this tag (default is an empty string)
• friends_of - A user id. Only scores posted by friends of this user will load. (optional)

Return Object

• command_id = loadScores
• board - The ID of the score board
• num_results - The number of scores that were requested
• period - "today", "this week", "this month", "this year" or "all-time"
• scores - An array of score objects, each with the following properties:
  • user_id - The ID of the user who earned this score
  • username - The name of the user who earned this score
  • value - The formatted string value of this score
  • numeric_value - The numeric value of this score
  • tag - A string that this score was tagged with
• num_scores - The actual number of scores that were found
• success = 1

logCustomEvent

This command will increment a custom event stat (defined in the "Referrals & Events" page of your game project API Tools).

POST Values

• command_id = logCustomEvent
• tracker_id - The tracker ID of your game
• host - The domain currently hosting the game, ie: www.somesite.com
• event - The name of your custom event

Return Object

• command_id = logCustomEvent
• event - The name of your custom event
• success = 1

lookupSaveFiles

Look up a list of save files. This command is used to construct a dynamic MySQL query.

It helps to be familiar with SQL when building the 'query' property.

POST Values

• command_id = lookupSaveFiles
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game
• group_id - The ID of the save group being searched
• query - A JSON encoded object of query rules containing any of the following properties:
  • num_results - The number of save files to return (default is 10)
  • page - The page to load. If num_results = 10 and page = 2, files 11-20 will be loaded
  • first_result - The index of the first result. If num_results = 10 and first_result = 4, files 5-14 will be loaded
  • randomize - "If true, a random set will be loaded and page/first_result get ignored''
  • lookup_keys - An array of key IDs to look up. If absent, key information will not be loaded (optional)
  • lookup_ratings - An array of rating IDs to look up. If absent, rating information will not be loaded (optional)
  • file_conditions - An array of condition objects, each containing the following properties: (optional)
    • field - The field ID to filter on (see Field IDs below)
    • value - The value to compare
    • operator - The operator to compare with (see operators below)
  • key_conditions - An array of key condition objects, each with the following properties: (optional)
    • key_id - The ID of the key to filter on
    • value - The value to compare
    • operator - The operator to compare with (see operators below)
  • rating_conditions - An array of rating condition objects, each with the following properties: (optional)
    • rating_id - The ID of the rating to filter on
    • column - The rating column to use: "score" or "votes" (default="score")
    • value - The value to compare
    • operator - The operator to compare with (see operators below)
  • sort_conditions - An array of sort condition objects, each with the following properties: (optional)
    • table - Data to sort on: 1=field, 2=key, 3=rating
    • field - The field, key or rating id to sort on
    • column - The column to sort on: "score" or "votes" (rating sorts only, default="score")
    • desc - If true, results will be use descending order (default = false)
  • group_by - An array of grouping objects, each containing the following properties: (optional)
    • table - Data to group on: 1=field, 2=key, 3=rating
    • field - The field, key or rating id to group on

Return Object

TODO: return object, list of operators, list of file field ids.

postScore

Posts a high score to a score board. This command is sent as a secure packet (see securePacket command)

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• seed - The random salt string (will also need to be used in the encryption process)
• secure - An encrypted object (see Encryption Process) containing the following properties:
  • command_id = postScore
  • publisher_id - The ID of the publisher hosting the game
  • session_id - The current player session ID
  • board - The id of the score board
  • value - The value of the score being posted
  • tag - An optional tag (string) you can use to filter score boards with

Return Object

• command_id = postScore
• board - The ID of the score board
• tag - The string value this score was tagged with. If not tag was set, this will be a blank string.
• value - The value of the score that was posted
• success = 1

preloadSettings

Used to pre-load all the meta-data (medals, scoreboards, etc) for the game.

POST Values

• command_id = preloadSettings
• tracker_id - The tracker ID of your game
• publisher_id - The ID of the publisher hosting the game (optional, used to load unlocked medals, etc)
• user_id - The user ID of the current player (optional, used to load unlocked medals, etc)

Return Object

• command_id = preloadSettings
• medals - An array of medal objects (if the game uses them) with the following properties:
  • medal_id - The numeric id of the medal
  • medal_name - The name of the medal
  • medal_value - The point value of the medal
  • medal_difficulty - 1=easy, 2=moderate, 3=challenging, 4=difficult, 5=brutal
  • medal_unlocked - true/false (if publisher_id and user_id were passed)
  • medal_icon - The URL of the icon for this medal
  • secret - 1 if this is a secret medal
  • medal_description - The description of this medal
• score_boards - An array of score board objects (if used) containing the following properties:
  • id - The numeric id of the score board
  • name - The name of the score board
• save_groups - An array of save group objects (if used) containing the following properties:
  • group_id - The numeric id of the save group
  • group_name - The name of the save group
  • group_type - 0=system, 1=private, 2=public, 3=moderated
  • keys - An array of any key objects associated with this save group, each with the following properties:
    • id - The numeric id of the key
    • name - The name of the key
    • type - The datatype of this key: 1=float, 2=int, 3=string, 4=boolean
  • ratings - An array of any ratings objects for this save group, each with the following properties:
    • id - The numeric ID of the rating.
    • name - The name of the rating.
    • min - The minimum possible value of this rating
    • max - The maximum possible value of this rating
    • float - True, if this rating can have float values for scores, false if scores are integers.
• success = 1

rateSaveFile

Casts a vote to a save file rating. This command is sent as a secure packet (see securePacket command)

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• seed - The random salt string (will also need to be used in the encryption process)
• secure - An encrypted object (see Encryption Process) containing the following properties:
  • command_id = rateSaveFile
  • publisher_id - The ID of the publisher hosting the game
  • session_id - The current player session ID
  • group - The id of the save group the file belongs to
  • save_id - The numeric ID of the save file
  • rating_id - The numeric ID of the rating this vote is for
  • vote - The value the user is rating this file

• command_id = rateSaveFile
• already_voted - true if already voted (absent if this is a new vote)
• votes - The total number of votes this file has had (absent if this vote is not new)
• score- The total score of the file rating (absent if this vote is not new)
• save_id - The ID of the file being voted on
• group_id - The ID of the save group the file belongs to
• rating_id - The ID of the rating that was voted on

saveFile

Saves a file to our servers from your game. This command is sent as a secure packet (see securePacket command)

There are 2 ways to pass file contents and thumbnail images. You can send them as post strings (see note below about thumbnails), or you can post them as binary files.

The more you can compress your file data, the better your load times will be.

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• seed - The random salt string (will also need to be used in the encryption process)
• secure - An encrypted object (see Encryption Process) containing the following properties:
  • command_id = saveFile
  • publisher_id - The ID of the publisher hosting the game
  • session_id - The current player session ID
  • group - The ID of the save group this file is being written to
  • save_id - The numeric id of an existing file to overwrite (optional)
  • filename - The name of this file
  • description - A description of this file (optional)
  • status - 1=private, 2=shared, 3=unapproved, 4=approved (optional)
  • keys - An array of key/value objects containing the following properties: (optional)
    • id - The numeric id of this key
    • value - The key value for this file
  • file - A binary file or text blob to be saved
  • thumbnail - A PNG file or dataURL string

Return Object

• command_id = unlockMedal
• group_id - The ID of the save group the file belongs to
• save_id - The numeric ID of the saved file
• filename - The name of the file
• file_url - The URL the file can be downloaded from
• thumbnail - The URL to your 90x90 thumbnail
• icon - The URL to a smaller 50x50 version of your thumbnail

Note: If you can not post multipart form data, thumbnails will need to be encoded as Base64 strings with some meta data.

The encoded string should look like this:

data:image/png;base64,{BASE64_ENCODED_PNG_IMAGE}

This format is based on the HTML5/JavaScript Canvas.toDataUrl() method.

To encode the actual image you will need to convert your PNG bytes to Base64.

securePacket

Used to send an encrypted command packet. Some commands must be sent securely to help prevent abuse. Please read the Encryption Process wiki for details on how these packets should be encrypted.

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• seed - The random salt string (will also need to be used in the encryption process)
• secure - An encrypted object (see Encryption Process)

unlockMedal

Posts a high score to a score board. This command is sent as a secure packet (see securePacket command)

POST Values

• command_id = securePacket
• tracker_id - The tracker ID of your game
• secure - An encrypted object (see Encryption Process) containing the following properties:
  • command_id = unlockMedal
  • publisher_id - The ID of the publisher hosting the game
  • session_id - The current player session ID
  • medal_id - The ID of the medal

Return Object

• command_id = unlockMedal
• medal_id - The ID of the medal
• medal_name - The name of the medal
• medal_value - The point value of the medal
• medal_difficulty - 1=Easy, 2=Moderate, 3=Challenging, 4=Difficult, 5=Brutal
• success = 1