Newgrounds.io Component List

Below is a comprehensive list of available components.

Components that require a session ID will be noted. The session ID should be included in the request object, not in the component itself.

Components that should be sent securely will be noted. For more information, see the Newgrounds.IO Encryption section.

All parameters are optional unless otherwise noted.

App

Used to get and validate information associated with your app, including user sessions.

App.checkSession

Checks the validity of a session id and returns the results in a Session object.

Requires a session ID.

Parameters:

This component does not take any parameters

Result:

session — Session Object

App.endSession

Ends the current session, if any.

Requires a session ID.

Parameters:

This component does not take any parameters

App.getCurrentVersion

Gets the version number of the app as defined in your "Version Control" settings.

Parameters:

version — string
The version number (in "X.Y.Z" format) of the client-side app. (default = "0.0.0")

Result:

client_deprecated — boolean
Notes whether the client-side app is using a lower version number.

current_version — string
The version number of the app as defined in your "Version Control" settings.

App.getHostLicense

Checks a client-side host domain against domains defined in your "Game Protection" settings.

Parameters:

host — string
The host domain to check (ei, somesite.com).

Result:

host_approved — boolean

App.logView

Increments "Total Views" statistic.

Parameters:

host* — string
The domain hosting your app. Examples: "www.somesite.com", "localHost"

* Required parameter

App.startSession

Starts a new session for the application.

Parameters:

force — boolean
If true, will create a new session even if the user already has an existing one.

Note: Any previous session ids will no longer be valid if this is used.

Result:

session — Session Object

CloudSave

Handles loading and saving of game states. This is intended for saving a single user's game state, not for sharing or powering multi-user worlds.

CloudSave.clearSlot

Deletes all data from a save slot. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.

Parameters:

id* — int
The slot number.

* Required parameter

Result:

slot — SaveSlot Object
A SaveSlot object.

Notes:

In debug mode the save file is left on disk. Debug mode blocks writing, not reading, so the returned SaveSlot describes the slot as it actually stands, still holding its file, rather than the empty slot a real call would have left behind.

CloudSave.loadSlot

Returns a specific saveslot object. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.

Parameters:

app_id — string
The App ID of another, approved app to load slot data from.

id* — int
The slot number.

* Required parameter

Result:

app_id — string
The App ID the loaded slot belongs to, if loaded from an external app.

slot — SaveSlot Object
A SaveSlot object.

CloudSave.loadSlots

Returns a list of saveslot objects. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.

Parameters:

app_id — string
The App ID of another, approved app to load slot data from.

Result:

app_id — string
The App ID the loaded slots belong to, if loaded from an external app.

slots — Array( SaveSlot )
An array of SaveSlot objects.

CloudSave.setData

Saves data to a save slot. Any existing data will be replaced. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.

Parameters:

data* — string
The data you want to save.

id* — int
The slot number.

* Required parameter

Result:

slot — SaveSlot Object

Notes:

In debug mode the data is validated but nothing is written to the database or to disk. Debug mode blocks writing, not reading, so the returned SaveSlot describes the slot as it actually stands: the size, timestamp and url of whatever an earlier real save left there, or an empty slot if the slot has never been saved to. It does not describe the data you just sent, so do not expect the returned size to match your payload.

Event

Handles logging of custom events.

Event.logEvent

Logs a custom event to your API stats.

Parameters:

event_name* — string
The name of your custom event as defined in your Referrals & Events settings.

host* — string
The domain hosting your app. Example: "newgrounds.com", "localHost"

* Required parameter

Result:

event_name — string

Gateway

Provides information about the gateway server.

Gateway.getDatetime

Loads the current date and time from the Newgrounds.io server.

Parameters:

This component does not take any parameters

Result:

datetime — string
The server's date and time in ISO 8601 format.

timestamp — int
The current UNIX timestamp on the server.

Gateway.getVersion

Returns the current version of the Newgrounds.io gateway.

Parameters:

This component does not take any parameters

Result:

version — string
The version number (in X.Y.Z format).

Gateway.ping

Pings the Newgrounds.io server.

Parameters:

This component does not take any parameters

Result:

pong — string
Will always return a value of 'pong'

Loader

This class handles loading various URLs and tracking referral stats.

Note: These calls do not return any JSON packets (unless the redirect param is set to false). Instead, they redirect to the appropriate URL. These calls should be executed in a browser window vs using AJAX or any other internal loaders.

Loader.loadAuthorUrl

Loads the official URL of the app's author (as defined in your "Official URLs" settings), and logs a referral to your API stats.

For apps with multiple author URLs, use Loader.loadReferral.

Parameters:

host* — string
The domain hosting your app. Example: "www.somesite.com", "localHost"

log_stat — boolean
Set this to false to skip logging this as a referral event.

redirect — boolean
Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

* Required parameter

Result:

url — string
The URL to redirect to. (This will only be returned if the redirect param is set to false.)

Loader.loadMoreGames

Loads the Newgrounds game portal, and logs the referral to your API stats.

Parameters:

host* — string
The domain hosting your app. Example: "www.somesite.com", "localHost"

log_stat — boolean
Set this to false to skip logging this as a referral event.

redirect — boolean
Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

* Required parameter

Result:

url — string
The URL to redirect to. (This will only be returned if the redirect param is set to false.)

Loader.loadNewgrounds

Loads Newgrounds, and logs the referral to your API stats.

Parameters:

host* — string
The domain hosting your app. Example: "www.somesite.com", "localHost"

log_stat — boolean
Set this to false to skip logging this as a referral event.

redirect — boolean
Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

* Required parameter

Result:

url — string
The URL to redirect to. (This will only be returned if the redirect param is set to false.)

Loader.loadOfficialUrl

Loads the official URL where the latest version of your app can be found (as defined in your "Official URLs" settings), and logs a referral to your API stats.

Parameters:

host* — string
The domain hosting your app. Example: "www.somesite.com", "localHost"

log_stat — boolean
Set this to false to skip logging this as a referral event.

redirect — boolean
Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

* Required parameter

Result:

url — string
The URL to redirect to. (This will only be returned if the redirect param is set to false.)

Loader.loadReferral

Loads a custom referral URL (as defined in your "Referrals & Events" settings), and logs the referral to your API stats.

Parameters:

host* — string
The domain hosting your app. Example: "www.somesite.com", "localHost"

log_stat — boolean
Set this to false to skip logging this as a referral event.

redirect — boolean
Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

referral_name* — string
The name of the referral (as defined in your "Referrals & Events" settings).

* Required parameter

Result:

url — string
The URL to redirect to. (This will only be returned if the redirect param is set to false.)

Medal

Handles loading and unlocking of medals.

Medal.getList

Loads a list of Medal objects.

Parameters:

app_id — string
The App ID of another, approved app to load medals from.

Result:

app_id — string
The App ID of any external app these medals were loaded from.

medals — Array( Medal )
An array of medal objects.

Medal.getMedalScore

Loads the user's current medal score. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.

Parameters:

This component does not take any parameters

Result:

medal_score — int
The user's medal score.

Medal.unlock

Unlocks a medal. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.
User must be logged in.
If encryption is enabled, must be sent in a secure call.

Parameters:

id* — int
The numeric ID of the medal to unlock.

* Required parameter

Result:

medal — Medal Object
The Medal that was unlocked.

medal_score — int
The user's new medal score.

ScoreBoard

Handles loading and posting of high scores and scoreboards.

ScoreBoard.getBoards

Returns a list of available scoreboards.

Parameters:

This component does not take any parameters

Result:

scoreboards — Array( ScoreBoard )
An array of ScoreBoard objects.

ScoreBoard.getScores

Loads a list of Score objects from a scoreboard. Use 'skip' and 'limit' to page through the results. When the 'user' param is set the list is that player's personal best scores, which are pruned to a small number per board and tag.

Parameters:

app_id — string
The App ID of another, approved app to load scores from.

id* — int
The numeric ID of the scoreboard.

limit — int
The number of scores to include in the list. Default = 10, maximum = 100. Higher values are truncated to 100 rather than rejected, and requesting more scores than a board holds simply returns everything available.

period — string
The time-frame to pull scores from: 'D' for today, 'W' this week, 'M' this month, 'Y' this year, or 'A' for all-time. Defaults to 'D'.

skip — int
The number of scores to skip before starting the list. Default = 0. Paging past the last available score returns an empty list, which is how you detect the end of a board.

social — boolean
If set to true, only social scores will be loaded (scores by the user and their friends). This param will be ignored if there is no valid session id and the 'user' param is absent.

tag — string
A tag to filter results by. Matching is exact and case-insensitive, so the string should be the same one passed to ScoreBoard.postScore. See postScore's tag parameter for recommended characters.

user — mixed
A user's ID or name. If 'social' is true, this user and their friends will be included. Otherwise, only scores for this user will be loaded. If this param is missing and there is a valid session id, that user will be used by default.

* Required parameter

Result:

app_id — string
The App ID of any external app these scores were loaded from.

limit — int
The query limit that was used.

period — string
The time-frame the scores belong to. See notes for acceptable values.

scoreboard — ScoreBoard Object
The ScoreBoard being queried.

scores — Array( Score )
An array of Score objects.

skip — int
The query skip that was used.

social — boolean
Will return true if scores were loaded in social context ('social' set to true and a session or 'user' were provided).

user — User Object
The User the score list is associated with (either as defined in the 'user' param, or extracted from the current session when 'social' is set to true)

Notes:

Acceptable 'period' values:
"D" = current day (default)
"W" = current week
"M" = current month
"Y" = current year
"A" = all-time

ScoreBoard.postScore

Posts a score to the specified scoreboard. Requires a session with a signed-in user attached; a session without one fails with a Login Required error.

Requires a session ID.
User must be logged in.
If encryption is enabled, must be sent in a secure call.

Parameters:

id* — int
The numeric ID of the scoreboard.

tag — string
An optional tag used to filter scores via ScoreBoard.getScores. Tags are matched as exact keys and matching is case-insensitive, so "Hard" and "hard" are the same tag. Tags are limited to 32 characters, and sticking to A-Z, a-z, 0-9 and _ . : - is recommended; other characters are accepted but may not match reliably.

value* — int
The score value, as a whole number between -2147483648 and 2147483647. Fractional values are truncated toward zero, and values outside that range are clamped to the nearest limit, so round and range-check calculated scores before posting. On an incremental scoreboard the accumulated totals are held to the same range too. Shorter periods reset on their own, but the all-time total never does, so a player who reaches 2147483647 there stays pegged at it for good.

* Required parameter

Result:

score — Score Object
The Score that was posted to the board.

scoreboard — ScoreBoard Object
The ScoreBoard that was posted to.

Notes:

If this board uses incremental scores, the score returned is the player's new running total for the current day.

In debug mode nothing is written: no score is earned, no personal bests are archived, and the board is not flagged as used. The returned Score still carries the value the post would have scored, so on an incremental board it is the running total the player would have ended up with.