Parameters can now and must now be defined as properties of an object literal (excluding callback functions).

Added short circuit evaluation, though some properties may not go undefined.

Certain bugs with the data methods have been corrected.

Missing trophy and scoreboard methods have been added.

For more specific information, please visit the Official API Documentation.

This library uses Game Jolt API v1.

All information marked in square brackets is a string, though some strings may be harmlessly replaced with integers.

Initializing the API is fairly straightforward. First, reference the gj.api.js script in your HTML code.

<script type="text/javascript" src="./gj.api.js"></script>

Now, call gj.setup in JavaScript.

gj.setup( [game_id_here], [API_key_here] );

This will record your credentials for future use, rather than unnecessarily resupplying them. Keep in mind that most methods require you to call this function before use.

The gj.on_setup event is fired after this is done. You can use it after redefining it.

gj.on_setup = function(){ console.log('API has been set up!'); }

You may log users in effortlessly with just the gj.login method.

gj.login( [username], [token], [callback(boolean:success)] );

If you wish to log users in automatically, you may set gj.auto_login to true.

gj.auto_login = true;

This will tell gj.login to store the user credentials, and gj.setup to log the user in upon initialization.

To listen for a successful login either automatically or manually, you may use gj.on_logged_in

gj.on_logged_in = function(){ console.log('User logged in!'); }

To log a user out, simple invoke gj.logout.

gj.logout();

You may define gj.on_logged_out similarly.

gj.on_logged_out = function(){ console.log('User logged out!'); }

Data in the Game Jolt API is handled via strings in a key based system, both global and user specific. Global keys can be accessed by anyone, user specific keys require user authentication and cannot be seen in the data storage dashboard.

The following text references an options object, and below it the object's properties. Response objects have a success property, and other related data. Please note that logging in is a requirement most of these methods.

To set data, use gj.data.set.

gj.data.set( object:options, function(object:response) );

Parameters ( * = optional ):

key: [key_name]

data: [data_string]

*user_specific: [boolean]

To fetch data, use gj.data.fetch.

gj.data.fetch( object:options, function(object:response) );

Parameters ( * = optional ):

key: [key_name]

*user_specific: [boolean]

To update data, use gj.data.update.

gj.data.fetch( object:options, function(object:response) );

Parameters ( * = optional ):

key: [key_name]

value: [new_data_string]

operation: [operation_type (add, subtract, multiply, divide, append, prepend)]

*user_specific: [boolean]

To permanently remove data, use gj.data.remove.

gj.data.remove( object:options, function(object:response) );

Parameters ( * = optional ):

key: [key_name]

*user_specific: [boolean]

To get all keys in either global or specific data tables, use gj.data.get.

gj.data.get( object:options, function(object:response) );

Parameters ( * = optional ):

*user_specific: [boolean]

If any keys are found, you may find them listed in an array in response.keys.

Here, the user and token properties may be omitted if the user is logged in.

gj.users.fetch returns all user-related data, including avatar, status, user ID, and more.

gj.users.fetch( object:options, function(object:response) );

Parameters:

user: [username]

gj.users.fetch_id is similar to the last, but requires you supply a user ID.

gj.users.fetch( object:options, function(object:response) );

Parameters:

id: [user_id]

gj.users.auth authenticates a user and returns a success value of true if successful.

gj.users.auth( object:options, function(object:response) );

Parameters:

user: [username]

token: [user_token]

Sessions tell Game Jolt when a user is playing your game. You may open, close, or ping a session as displayed below.

gj.sessions.open( function(object:response) );

gj.sessions.close( function(object:response) );

gj.sessions.ping( function(object:response) );

Once again, please note that logging in is a requirement these methods.

Trophies are self explanatory.

gj.trophies.fetch( function(object:response) );

Parameters ( * = optional ):

*trophy: [trophy_id (will return all trophies if not defined)]

*achieved: boolean (only returns achieved trophies if true)

This fetches either a list of trophies and their details, or a single trophy.

gj.trophies.add( function(object:response) );

Parameters ( * = optional ):

trophy: [trophy_id]

This will add the defined trophy to the users' achieved trophies.

As always, logging in is a requirement these methods.

Game Jolt offers a variety of ways to add and retrieve scores.

Fetching scores is done with gj.scores.fetch.

gj.scores.fetch( object:options, function(object:response) );

Parameters ( * = optional ):

*limit: [result_limit]

*table: [table_id]

*user_specific: boolean (if true, this function will only return the users' scores)

You can add scores with gj.scores.add.

gj.scores.add( object:options, function(object:response) );

Parameters ( * = optional ):

score: [score_to_use (can use a string)]

table: [sort_integer (must be an integer representing its order on the table)]

Anonymous scores are added with gj.scores.guest_add. These do not require authentication.

gj.scores.guest_add( object:options, function(object:response) );

Parameters ( * = optional ):

score: [score_to_use (can use a string)]

table: [sort_integer (must be an integer representing its order on the table)]

You can get all tables with gj.scores.tables.

gj.scores.guest_add( function(object:response) );

Need to write a custom call to the API? You can do that like this:

gj.custom( [data_url (ex. 'data/set' or 'trophies')], [parameters], function(object:response) );

In all option objects you may pass a custom user and token if you wish.

You can also omit the options object in any case where all properties are optional.

Though techincally almost all parameters can be omitted, you should always define at least the options object and callback where it is described. Please don't define absolutely nothing.