Use the latest, official library at NewgroundsIO-JS
This is a client library used to interact with the Newgrounds.io server.
Grab the compiled library file at https://github.com/PsychoGoldfishNG/newgrounds.io-for-javascript-html5/tree/master/bin to self-host or use the following HTML tag to load via CDN:
<script src="https://cdn.jsdelivr.net/gh/PsychoGoldfishNG/newgrounds.io-for-javascript-html5@2d7dcda/bin/newgroundsio.min.js"></script>Newgrounds.io is a server API packed full of features for indie game developers.
Here are some of the many things it can do for you:
- Track distribution of web-based games.
- Control what sites can host web-based games.
- Log statistics for custom events.
- Track referrals from in-game links.
- Add in-game achievements (medals).
- Add score tables.
- Save game/player states to the cloud.
Before you can use this library, you will need to create a project on http://www.newgrounds.com/projects/games and obtain an app id from your new project's "API Tools" page. Be sure you have switched to the v3 beta!
Using the Newgrounds.io.core class to make calls to the server is extremely easy!
var ngio = new Newgrounds.io.core(app_id, aes_encryption_key);
ngio.callComponent(component_name, parameters_object, callback_function, callback_context);The context is an optional parameter through which you can specify the context under which the callback function will be executed. Practically all methods which support callbacks can also take a context parameter.
Let's try a real, working, example. This will load the current datetime on the server:
var ngio = new Newgrounds.io.core("39685:NJ1KkPGb", "qsqKxz5dJouIkUNe3NBppQ==");
ngio.callComponent("Gateway.getDatetime", {}, function(result) {
if (result.success) {
console.log('The current date/time on the Newgrounds.io server is '+result.datetime);
} else {
console.log('ERROR!', result.error.message);
}
});Get your player signed in via Newgrounds Passport (using a Newgrounds.com, Facebook or Google+ account):
var ngio = new Newgrounds.io.core("39685:NJ1KkPGb", "qsqKxz5dJouIkUNe3NBppQ==");
function onLoggedIn() {
console.log("Welcome " + ngio.user.name + "!");
}
function onLoginFailed() {
console.log("There was a problem logging in: " . ngio.login_error.message );
}
function onLoginCancelled() {
console.log("The user cancelled the login.");
}
/*
* Before we do anything, we need to get a valid Passport session. If the player
* has previously logged in and selected 'remember me', we may have a valid session
* already saved locally.
*/
function initSession() {
ngio.getValidSession(function() {
if (ngio.user) {
/*
* If we have a saved session, and it has not expired,
* we will also have a user object we can access.
* We can go ahead and run our onLoggedIn handler here.
*/
onLoggedIn();
} else {
/*
* If we didn't have a saved session, or it has expired
* we should have been given a new one at this point.
* This is where you would draw a 'sign in' button and
* have it execute the following requestLogin function.
*/
}
});
}
/*
* Call this when the user clicks a 'sign in' button from your game. It MUST be called from
* a mouse-click event or pop-up blockers will prevent the Newgrounds Passport page from loading.
*/
function requestLogin() {
ngio.requestLogin(onLoggedIn, onLoginFailed, onLoginCancelled);
/* you should also draw a 'cancel login' buton here */
}
/*
* Call this when the user clicks a 'cancel login' button from your game.
*/
function cancelLogin() {
/*
* This cancels the login request made in the previous function.
* This will also trigger your onLoginCancelled callback.
*/
ngio.cancelLoginRequest();
}
/*
* If your user is logged in, you should also draw a 'sign out' button for them
* and have it call this.
*/
function logOut() {
ngio.logOut(function() {
/*
* Because we have to log the player out on the server, you will want
* to handle any post-logout stuff in this function, wich fires after
* the server has responded.
*/
});
}Make multiple component calls in a single request:
var ngio = new Newgrounds.io.core("39685:NJ1KkPGb", "qsqKxz5dJouIkUNe3NBppQ==");
/* vars to record any medals and scoreboards that get loaded */
var medals, scoreboards;
/* handle loaded medals */
function onMedalsLoaded(result) {
if (result.success) medals = result.medals;
}
/* handle loaded scores */
function onScoreboardsLoaded(result) {
if (result.success) scoreboards = result.scoreboards;
}
/* load our medals and scoreboards from the server */
ngio.queueComponent("Medal.getList", {}, onMedalsLoaded);
ngio.queueComponent("ScoreBoard.getBoards", {}, onScoreboardsLoaded);
ngio.executeQueue();Want to unlock one of those medals we just loaded?
/* You could use this function to draw the medal notification on-screen */
function onMedalUnlocked(medal) {
console.log('MEDAL GET:', medal.name);
}
/* attempt to unlock a medal */
function unlockMedal(medal_id) {
/* If there is no user attached to our ngio object, it means the user isn't logged in and we can't unlock anything */
if (!ngio.user) return;
var i, medal;
for (i = 0; i < medals.length; i++) {
medal = medals[i];
/* look for a matching medal name */
if (medal.id == medal_id) {
/* we can skip unlocking a medal that's already been earned */
if (!medal.unlocked) {
/* unlock the medal from the server */
ngio.callComponent('Medal.unlock', {id:medal.id}, function(result) {
if (result.success) onMedalUnlocked(result.medal);
});
}
return;
}
}
}
/* lets unlock a medal!!! */
unlockMedal(some_medal_id);Or post a score?
function postScore(scoreboard_id, score_value) {
/* If there is no user attached to our ngio object, it means the user isn't logged in and we can't post anything */
if (!ngio.user) return;
ngio.callComponent('ScoreBoard.postScore', {id:scoreboard_id, value:score_value});
}
postScore(some_scoreboard_id, your_score);You should always be prepared to handle an error from the API. When contacting Newgrounds support, you will be expected to provide any error messages you are receiving from the server.
Handling errors is as easy as this:
ngio.callComponent(component, params, function(result) {
if (result.success) {
// no problems here
} else {
// there was an error!
var error_msg = result.error.message;
}
});Newgrounds.io can operate in debug mode. While in this mode, calls to any components that normally post data to a user account will not post anything, but rather, simulate a real post.
Additionally, if you watch the server results via your browser's network inspector, JSON objects will contain a lot more meta information and be much more readable in debug mode.
To enable debug mode, simply set 'debug' to true:
ngio.debug = true;API docs for this library are included in the repository. See: doc/api/index.html
Documentation for server components can be found at http://www.newgrounds.io/help/components/
Join the Newgrounds.io Discord at https://discord.gg/wcsCk2ErhH
Follow us on Twitter https://twitter.com/Newgroundsio
Copyright (c) 2015 Newgrounds Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
CryptoJS v3.1.2 code.google.com/p/crypto-js (c) 2009-2013 by Jeff Mott. All rights reserved. code.google.com/p/crypto-js/wiki/License