Newgrounds.io

https://www.newgrounds.io/help/
Admin
Newgrounds.io is a platform-agnostic API built for indie game developers to implement features like...
Tokens:6,773
Snippets:88
Trust Score:6.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### App.startSession

Source: https://www.newgrounds.io/help//components

Starts a new session for the application.

```APIDOC
## App.startSession

### Description
Starts a new session for the application.

### Parameters
- **force** (boolean) - Optional - If true, will create a new session even if the user already has an existing one.

### Response
- **session** (Session Object) - The new session details.
```

--------------------------------

### Gateway.getVersion Request and Response

Source: https://www.newgrounds.io/help//communicating-with-the-server

Example of a single component call to retrieve the gateway version.

```json
{
    "app_id": "test",
    "call": {
        "component": "Gateway.getVersion"
    }
}
```

```json
{
    "success": true,
    "app_id": "test",
    "result": {
        "component": "Gateway.getVersion",
        "data": {
            "success": true,
            "version": "3.0.0"
        }
    }
}
```

--------------------------------

### Example JSON Request Object

Source: https://www.newgrounds.io/help//communicating-with-the-server

A sample JSON-encoded request object used to call the Gateway.getDatetime component.

```json
{ "app_id": "test", "debug": true, "execute": { "component": "Gateway.getDatetime", "parameters": {}, "echo": "Hello World!" } }
```

--------------------------------

### Constructing a Gateway Request Object

Source: https://www.newgrounds.io/help//communicating-with-the-server

Examples of JSON structures for standard and secure API requests to the Newgrounds gateway.

```json
{
    "component": "Gateway.getDatetime",
    "parameters": {},
    "echo": "Hello World!"
}
```

```json
{
    "app_id": "test",
    "debug": true,
    "execute": {
        "component": "Gateway.getDatetime",
        "parameters": {},
        "echo": "Hello World!"
    }
}
```

```json
{
    "app_id": "test",
    "debug": true,
    "execute": {
        "secure": "r9847m9onppkOTDTcdywJhTMsAKb6d/ixYwhPNBr1q/SCWpkrxlj7nR4P+s72JjuI3vZaQJ+Dm8KewELe14zNJ22AHEnsrBSJhez7frHEghuHFpsV0hD5b/GA/3ktWmI"
    }
}
```

--------------------------------

### Multitasking API Request and Response

Source: https://www.newgrounds.io/help//communicating-with-the-server

Example of batching multiple components into a single request using an array in the execute property.

```json
{
    "app_id": "test",
    "execute": [
        {
            "component": "Gateway.getVersion"
        },{
            "component": "Gateway.getDatetime"
        }
    ]
}
```

```json
{
    "success": true,
    "app_id": "test",
    "result": [
        {
            "component": "Gateway.getVersion",
            "data": {
                "success": true,
                "version": "3.0.0"
            }
        },
        {
            "component": "Gateway.getDatetime",
            "data": {
                "success": true,
                "datetime": "2016-07-29T17:37:24-04:00"
            }
        }
    ]
}
```

--------------------------------

### Gateway.getDatetime Request and Response

Source: https://www.newgrounds.io/help//communicating-with-the-server

Example of a single component call to retrieve the current server datetime.

```json
{
    "app_id": "test",
    "call": {
        "component": "Gateway.getDatetime"
    }
}
```

```json
{
    "success": true,
    "app_id": "test",
    "result": {
        "component": "Gateway.getDatetime",
        "data": {
            "success": true,
            "datetime": "2016-07-29T17:37:24-04:00"
        }
    }
}
```

--------------------------------

### App.getCurrentVersion

Source: https://www.newgrounds.io/help//components

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

```APIDOC
## App.getCurrentVersion

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

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

### Response
- **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.
```

--------------------------------

### Loader.loadNewgrounds

Source: https://www.newgrounds.io/help//components

Loads Newgrounds and logs the referral.

```APIDOC
## Loader.loadNewgrounds

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

### Parameters
- **host** (string) - Required - The domain hosting your app.
- **log_stat** (boolean) - Optional - Set this to false to skip logging this as a referral event.
- **redirect** (boolean) - Optional - Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

### Result
- **url** (string) - The URL to redirect to. (This will only be returned if the redirect param is set to false.)
```

--------------------------------

### App.getHostLicense

Source: https://www.newgrounds.io/help//components

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

```APIDOC
## App.getHostLicense

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

### Parameters
- **host** (string) - Optional - The host domain to check (ei, somesite.com).

### Response
- **host_approved** (boolean) - Indicates if the host is approved.
```

--------------------------------

### Loader.loadOfficialUrl

Source: https://www.newgrounds.io/help//components

Loads the official URL where the latest version of your app can be found.

```APIDOC
## Loader.loadOfficialUrl

### Description
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) - Required - The domain hosting your app.
- **log_stat** (boolean) - Optional - Set this to false to skip logging this as a referral event.
- **redirect** (boolean) - Optional - Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

### Result
- **url** (string) - The URL to redirect to. (This will only be returned if the redirect param is set to false.)
```

--------------------------------

### Loader.loadMoreGames

Source: https://www.newgrounds.io/help//components

Loads the Newgrounds game portal and logs the referral.

```APIDOC
## Loader.loadMoreGames

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

### Parameters
- **host** (string) - Required - The domain hosting your app.
- **log_stat** (boolean) - Optional - Set this to false to skip logging this as a referral event.
- **redirect** (boolean) - Optional - Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

### Result
- **url** (string) - The URL to redirect to. (This will only be returned if the redirect param is set to false.)
```

--------------------------------

### Loader.loadReferral

Source: https://www.newgrounds.io/help//components

Loads a custom referral URL and logs the referral.

```APIDOC
## Loader.loadReferral

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

### Parameters
- **host** (string) - Required - The domain hosting your app.
- **referral_name** (string) - Required - The name of the referral (as defined in your "Referrals & Events" settings).
- **log_stat** (boolean) - Optional - Set this to false to skip logging this as a referral event.
- **redirect** (boolean) - Optional - Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

### Result
- **url** (string) - The URL to redirect to. (This will only be returned if the redirect param is set to false.)
```

--------------------------------

### Loader.loadAuthorUrl

Source: https://www.newgrounds.io/help//components

Loads the official URL of the app's author and logs a referral.

```APIDOC
## Loader.loadAuthorUrl

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

### Parameters
- **host** (string) - Required - The domain hosting your app.
- **log_stat** (boolean) - Optional - Set this to false to skip logging this as a referral event.
- **redirect** (boolean) - Optional - Set this to false to get a JSON response containing the URL instead of doing an actual redirect.

### Result
- **url** (string) - The URL to redirect to. (This will only be returned if the redirect param is set to false.)
```

--------------------------------

### Gateway.getVersion

Source: https://www.newgrounds.io/help//components

Returns the current version of the Newgrounds.io gateway.

```APIDOC
## Gateway.getVersion

### Description
Returns the current version of the Newgrounds.io gateway.

### Result
- **version** (string) - The version number (in X.Y.Z format).
```

--------------------------------

### ScoreBoard.getBoards

Source: https://www.newgrounds.io/help//components

Returns a list of available scoreboards.

```APIDOC
## ScoreBoard.getBoards

### Description
Returns a list of available scoreboards.

### Result
- **scoreboards** (Array(ScoreBoard)) - An array of ScoreBoard objects.
```

--------------------------------

### Gateway.ping

Source: https://www.newgrounds.io/help//components

Pings the Newgrounds.io server.

```APIDOC
## Gateway.ping

### Description
Pings the Newgrounds.io server.

### Result
- **pong** (string) - Will always return a value of 'pong'
```

--------------------------------

### Gateway.getDatetime

Source: https://www.newgrounds.io/help//components

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

```APIDOC
## Gateway.getDatetime

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

### Result
- **datetime** (string) - The server's date and time in ISO 8601 format.
- **timestamp** (int) - The current UNIX timestamp on the server.
```

--------------------------------

### App.logView

Source: https://www.newgrounds.io/help//components

Increments Total Views statistic.

```APIDOC
## App.logView

### Description
Increments "Total Views" statistic.

### Parameters
- **host** (string) - Required - The domain hosting your app. Examples: "www.somesite.com", "localHost"
```

--------------------------------

### CloudSave.loadSlots

Source: https://www.newgrounds.io/help//components

Returns a list of save slot objects. Requires a session ID.

```APIDOC
## CloudSave.loadSlots

### Description
Returns a list of saveslot objects.

### Parameters
- **app_id** (string) - Optional - The App ID of another, approved app to load slot data from.

### Response
- **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.
```

--------------------------------

### Medal.getList

Source: https://www.newgrounds.io/help//components

Loads a list of Medal objects, optionally from an external app.

```APIDOC
## Medal.getList

### Description
Loads a list of Medal objects.

### Parameters
- **app_id** (string) - Optional - 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.
```

--------------------------------

### ScoreBoard.getScores

Source: https://www.newgrounds.io/help//components

Loads a list of Score objects from a scoreboard.

```APIDOC
## ScoreBoard.getScores

### Description
Loads a list of Score objects from a scoreboard. Use 'skip' and 'limit' for getting different pages.

### Parameters
- **app_id** (string) - Optional - The App ID of another, approved app to load scores from.
- **id** (int) - Required - The numeric ID of the scoreboard.
- **limit** (int) - Optional - Number of scores to include. Default = 10.
- **period** (string) - Optional - Time-frame to pull scores from (D, W, M, Y, A).
- **skip** (int) - Optional - Number of scores to skip. Default = 0.
- **social** (boolean) - Optional - If true, only social scores will be loaded.
- **tag** (string) - Optional - A tag to filter results by.
- **user** (mixed) - Optional - A user's ID or name.

### 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.
- **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) - Returns true if scores were loaded in social context.
- **user** (User Object) - The User the score list is associated with.
```

--------------------------------

### CloudSave.loadSlot

Source: https://www.newgrounds.io/help//components

Returns a specific save slot object. Requires a session ID.

```APIDOC
## CloudSave.loadSlot

### Description
Returns a specific saveslot object.

### Parameters
- **app_id** (string) - Optional - The App ID of another, approved app to load slot data from.
- **id** (int) - Required - The slot number.

### Response
- **app_id** (string) - The App ID the loaded slot belongs to, if loaded from an external app.
- **slot** (SaveSlot Object) - A SaveSlot object.
```

--------------------------------

### Define a request object with unencrypted execute

Source: https://www.newgrounds.io/help//encryption

The full request structure including app_id and session_id, which will trigger an error if encryption is enabled but not applied.

```json
{
    "app_id": "test",
    "session_id": "USER_SESSION_ID_GOES_HERE",
    "execute": {
        "component": "Medal.unlock",
        "parameters": {
            "id": 38573
        }
    }
}
```

--------------------------------

### App.endSession

Source: https://www.newgrounds.io/help//components

Ends the current session, if any.

```APIDOC
## App.endSession

### Description
Ends the current session, if any. Requires a session ID.
```

--------------------------------

### Event.logEvent

Source: https://www.newgrounds.io/help//components

Logs a custom event to your API stats.

```APIDOC
## Event.logEvent

### Description
Logs a custom event to your API stats.

### Parameters
- **event_name** (string) - Required - The name of your custom event as defined in your Referrals & Events settings.
- **host** (string) - Required - The domain hosting your app.

### Response
- **event_name** (string) - The name of the logged event.
```

--------------------------------

### App.checkSession

Source: https://www.newgrounds.io/help//components

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

```APIDOC
## App.checkSession

### Description
Checks the validity of a session ID and returns the results in a Session object. Requires a session ID.

### Result
- **session** (Session Object) - The session details.
```

--------------------------------

### Define an unencrypted execute object

Source: https://www.newgrounds.io/help//encryption

The standard structure for an API call before applying encryption.

```json
{
    "component": "Medal.unlock",
    "parameters": {
        "id": 38573
    }
}
```

--------------------------------

### ScoreBoard.postScore

Source: https://www.newgrounds.io/help//components

Posts a score to the specified scoreboard. Requires a session ID.

```APIDOC
## ScoreBoard.postScore

### Description
Posts a score to the specified scoreboard. Requires a session ID and that the user is logged in.

### Parameters
- **id** (int) - Required - The numeric ID of the scoreboard.
- **tag** (string) - Optional - An optional tag to filter scores.
- **value** (int) - Required - The int value of the score.

### Result
- **score** (Score Object) - The Score that was posted to the board.
- **scoreboard** (ScoreBoard Object) - The ScoreBoard that was posted to.
```

--------------------------------

### CloudSave.clearSlot

Source: https://www.newgrounds.io/help//components

Deletes all data from a specific save slot. Requires a session ID.

```APIDOC
## CloudSave.clearSlot

### Description
Deletes all data from a save slot.

### Parameters
- **id** (int) - Required - The slot number.

### Response
- **slot** (SaveSlot Object) - A SaveSlot object.
```

--------------------------------

### Parsing the Server Response Object

Source: https://www.newgrounds.io/help//communicating-with-the-server

The structure of a typical JSON response object received after a successful API call.

```json
{
    "success": true,
    "app_id": "test",
    "result": {
        "echo": "Hello World!",
        "component": "Gateway.getDatetime",
        "data": {
            "success": true,
            "datetime": "2016-07-29T16:33:55-04:00",
            "debug": true
        }
    },
    "debug": {
        "exec_time": 0.002817,
        "request": {
            "app_id": "39685:NJ1KkPGb",
            "debug": true,
            "execute": {
                "component": "Gateway.getDatetime",
                "parameters": {},
                "echo": "Hello World!"
            }
        }
    }
}
```

--------------------------------

### Define a secure request object

Source: https://www.newgrounds.io/help//encryption

The final request structure where the 'execute' object contains only the 'secure' property holding the encrypted and encoded data.

```json
{
    "app_id": "test",
    "session_id": "USER_SESSION_ID_GOES_HERE",
    "execute": {
        "secure": "xL5yiZlNXm1C+J8Z2ie3kjKSJXC89783i+sdf\/OoAVHvgTUgxrzJv+LFjM\/\/b1YDOyqGBbjclXenWWBX4oJtkN8iMDEcujcdj5lrFIwAw=="
    }
}
```

--------------------------------

### CloudSave.setData

Source: https://www.newgrounds.io/help//components

Saves data to a save slot, replacing any existing data. Requires a session ID.

```APIDOC
## CloudSave.setData

### Description
Saves data to a save slot. Any existing data will be replaced.

### Parameters
- **data** (string) - Required - The data you want to save.
- **id** (int) - Required - The slot number.

### Response
- **slot** (SaveSlot Object) - A SaveSlot object.
```

--------------------------------

### Extracting the Result Object Data

Source: https://www.newgrounds.io/help//communicating-with-the-server

The specific data property returned within a successful result object.

```json
"data": {
    "success": true,
    "datetime": "2016-07-29T16:33:55-04:00",
    "debug": true
}
```

--------------------------------

### Medal.unlock

Source: https://www.newgrounds.io/help//components

Unlocks a medal for the logged-in user. Requires a session ID.

```APIDOC
## Medal.unlock

### Description
Unlocks a medal. Requires a session ID and that the user is logged in.

### Parameters
- **id** (int) - Required - The numeric ID of the medal to unlock.

### Result
- **medal** (Medal Object) - The Medal that was unlocked.
- **medal_score** (int) - The user's new medal score.
```

--------------------------------

### Medal.getMedalScore

Source: https://www.newgrounds.io/help//components

Loads the user's current medal score. Requires a session ID.

```APIDOC
## Medal.getMedalScore

### Description
Loads the user's current medal score. Requires a session ID.

### Result
- **medal_score** (int) - The user's medal score.
```
Tokens:
Raw