Newgrounds.com — Everything, By Everyone.

Newgrounds uses a session-based system to verify user sessions in our Flash API. These sessions can also be validated by approved publishers.

Page Contents

• Acquiring the User's Session
• Validating the Session
• Testing Authentication
• Custom Parameters
• External URLs

Acquiring the User's Session

Return to Top ^When your game is submitted to newgrounds, 3 variables are passed along.

In a Flash game, these are passed via Flashvars, while HTML5 and iFrame games get these variables passed in a request string.

The three variables are:

• NewgroundsAPI_SessionID - A random string that expires after 6 hours of inactivity.
• NewgroundsAPI_UserName - The users registered name.''
• NewgroundsAPI_UserID - The users numeric ID.''

If these variables are not set, the user is not currently signed in.

There is also a NewgroundsAPI_CustomParams variable available (see 'Custom Parameters' below).

Validating the Session

Return to Top ^To validate the user's session, you will need a secret key. This key is used to identify that you are an approved publisher. Once you have been given a secret key, you can post the following information to our authentication script (located at http://www.ngads.com/user_auth.php)

• session_id - The session ID as set in the NewgroundsAPI_SessionID value.
• user_name - The users name as set in the NewgroundsAPI_UserName value.''
• secret - Your secret key.

The output of this script will be a JSON encoded object. This string will contain a 'success' variable that will be set to true or false depending on the validation results.

If the session is valid, the JSON object will also contain the user's 'user_name' and 'user_id'.

Testing Authentication

Return to Top ^For testing purposes, we have created a user name and session id that never expire.

The user name is: API-Debugger
The session id is: D3bu64p1U53R

We have also provided a simple HTML form you can use to test the authentication output at http://uploads.ungrounded.net/testauth.html

Custom Parameters

Return to Top ^Some games will need to be able to direct-link users with some predefined parameters. This can be used for tracking statistics, inviting players to a specific gaming session, and so on.

These parameters can be encoded in any format (we recommend JSON), and passed via the NewgroundsAPI_CustomParams request variable.

Your encoded varaibles should be escaped (use escape() in javascript or rawurlencode() in php) to ensure they work correctly.

Example:

If your game is published at http://www.newgrounds.com/portal/view/123456 and you wanted to pass the following parameters with JSON:

• game_id = "abcdefg"

Your JSON string would look like this: {"game_id":"abcdefg"}

You would URL encode the above JSON string and pass it to your game like using the following URL:

http://www.newgrounds.com/portal/view/604294?NewgroundsAPI_CustomParams=%7B%22game_id%22%3A%22abcdefg%22%7D

External URLs

Return to Top ^For developers using our External URL option (this is an invite only option), you can customize how the session variables are passed using a double square bracket markup.

For example, you could set your External URL to this:

http://www.somesite.com/game.php?user_name=[[NewgroundsAPI_UserName]]&user_id=[[NewgroundsAPI_UserID]]&session_id=[[NewgroundsAPI_SessionID]]

This would render the URL to something like:

http://www.somesite.com/game.php?user_name=API-Debugger&user_id=10&session_id=D3bu64p1U53R

If you are using custom parameters, you can also use the [[NewgroundsAPI_CustomParams]] variable.