Acquiring the User's Session
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
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'.
Note: For debugging purposes, you can also post to http://www.ngads.com/user_lookup.php. This works without actually validating your secret or the user's session id, so you can authenticate as any user while debugging. Just remember not to publish your game with this URL!
Testing Authentication
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
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
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.