Newgrounds (removed)

Newgrounds is a game page for serving Flash and HTML5 games and by that capable to distribute libGDX GWT games.

Overview

Newgrounds stable API only supports Flash, but there is a beta API called NGIO based on REST services that can be used by HTML5 games.

Newgrounds API supports the following features:

• Achievements (called Medals)
• Leaderboards (called Scoreboards)
• Events

Please note that the API was removed for v 0.2.4. Newgrounds.io service is unreliable and often returns a "You have made too many calls" response.

Also, the high score API does not work correctly (as of June 2017): Higher scores are always overwritten with lower scores.

Configure your Newgrounds project

Sign up at Newgrounds, create or edit your game project and go to "API Tools". Acitvate the API tools and then enable NGIO API. Disable encryption - it is used for avoiding tampering, but not supported by gdx-gamesvcs-ngio at the moment.

Add achievements, leaderboards and events as you wish.

See also: http://www.newgrounds.io/get-started/

Usage in your libGDX project

Include the Newgrounds.io implementation in your build.gradle for your HTML5 project:

    compile "de.golfgl.gdxgamesvcs:gdx-gamesvcs-html-ngio:$gamesvcsVersion"
    compile "de.golfgl.gdxgamesvcs:gdx-gamesvcs-html-ngio:$gamesvcsVersion:sources"

Now you can use NgioClient in your HTMLLauncher class. Don't forget to call initialize() with your Newgrounds app id and the user's session id which is given to you via a GET-parameter in your Newgrounds-embedded iframe.

    gsClient.initialize(NG_APP_ID,
            com.google.gwt.user.client.Window.Location.getParameter(NgioClient.NGIO_SESSIONID_PARAM),
            null // Encryption not supported atm
            );

Specific setup for posting scores and unlocking achievements

You can't give your own ids for newgrounds medals and scoreboards, but Newgrounds generates an integer id for them. To map your service independant String ids to the Newground's ids, set a mapper to the client before submitting scores or unlocking achievements:

 gsClient.setNgScoreboardMapper(new IGameServiceIdMapper<Integer>() {
                @Override
                public Integer mapToGsId(String independantId) {
                    // your mapping here
                    return ngId;
                }
            });

If you don't provide a mapper, calling the methods for posting scores or unlocking achievements will only write a log message.

Specific setup for submitting events

In order to sumit events, you have to provide a "host id". Newgrounds' dashboard aggregates event calls by this host id and it is a mandatory parameter for the API call. Best is to set it right after initialization to the host name you are coming from:

gsClient.setEventHostId(com.google.gwt.user.client.Window.Location.getHostName());

If you don't provide a host name, calling the method for submitting events will only write a log message.

The increment parameter is ignored, but submitting events does work for guests. It is expicitely encouraged by Newgrounds to use it even when your game is not hosted on Newgrounds' servers, so this is an interesting possibility to track usage on hosting sites that doesn't provide an own games service.

Working Example

See the demo app's Newgrounds branch for a fully working example, and try it at Newgrounds.

What work is undone?

Newgrounds recommends to ping their service at least every 30 minutes to ensure the user's session is not closed after two hours of inactivity. If you have a game where it could happen that no call (submitting event, unlocking achievement or posting a score) to the API is performed in such a period of time, you have to ensure yourself to keep the user session open.