Kongregate Level Sharing API (AS3 only)

Kongregate's Content Sharing API makes it easier than ever for developers to add features like custom level sharing to your games. The new API gives your players the ability to:

  • Save in-game content like levels, characters and game customizations to Kongregate's servers for easy retrieval any time and from any computer.
  • Browse publicly shared, user-generated content through a Kongregate hosted UI
  • Share in-game content easily via direct links, email or by posting to top social media sites. (No more copying and pasting of long, ugly text strings!)

We urge you all to check out the first integration of level sharing in Hexiom: Connect and grab the complete documentation here

Setup

The shared content API is available through the sharedContent property of the Kongregate API. Currently the shared content API is only available in AS3. When using the service, it is important to register your event listeners before calling connect on the Kongregate API, as shown below: 

// Register the shared content load listener before connecting
kongregate.sharedContent.addLoadListener('Level', onLoadLevel);
  
// Connect
kongregate.services.connect();

Each game may save up to 10 different types of shared content, so the possibilities of what you can do with this API are nearly endless.

API Functions

Adding load event listeners

You can use the addLoadListener function to register an event listener which will be triggered when content of the specified type is loaded by the user.

addLoadListener(contentType:String, callback:Function):void
  • contentType:String - Type of content to listen for
  • callback:Function - Function to call when content load request has been made

The callback function must accept a single Object which will have the following properties:

  • id:Number - The id of the shared content
  • name:String - The name of the shared content
  • permalink:String - A link to the shared content
  • content:String - The content itself
  • label:String - The label for the content

Example: Loading shared content with "Contraption" as the content type: 

kongregate.sharedContent.addLoadListener("Contraption", onContraptionLoad);

function onContraptionLoad(params:Object) {
  var id:Number        = params.id;
  var name:String      = params.name;
  var permalink:String = params.permalink;
  var content:String   = params.content;
  var label:String     = params.label;
       
  trace("Contraption " + id + " [" + label + "] loaded: " + content);
}

Browsing shared content

By using the browse function, you can cause a list of shared content to appear in the user's browser. This will allow them to view, rate, or load shared content for your game.

browse(contentType:String, sortOrder:String=null, label:String=null):void
  • contentType:String - Type of content to browse
  • sortOrder:String - Optional constant specifying how to sort content:
    • BY_NEWEST - Newest content first (This is the default if no method is specified)
    • BY_RATING - Highest-rated content first
    • BY_LOAD_COUNT - Most-viewed content first
    • BY_FRIENDS - Only show content made by friends (newest first)
    • BY_OWN - Only show your own content (newest first)
  • label:String - Optional, only browse content saved with the specified label

Example: Display a Shared Content browser for Contraptions, only showing those by your friends with the "Level 3 Solution" label 

kongregate.sharedContent.browse("Contraption", kongregate.sharedContent.BY_FRIENDS, "Level 3 Solution");

Saving content

You can use the save function to submit shared content on the Kongregate back-end.

save(contentType:String,content:String,callback:Function,thumbnail:DisplayObject=null,label:String=null):void
  • contentType:String — Type of content the user wishes to save, 12 characters max
  • content:String — Value of content to be saved. We strongly recommend keeping these values under 100K since the game will hang until the content is sent, which can lead to a poor user experience if the content is too large.
  • callback:Function — Function to call when save has finished
  • thumbnail:DisplayObject — Optional but highly recommended! Send us a DisplayObject that we will snapshotted and used as a thumbnail for the content. If this is not provided we will take a picture of the entire stage and use that as the thumbnail.
  • label:String — Optional, label for sub-classing the shared content.

The callback parameter should be a function that accepts a single Object as a parameter, which will have the following properties:

  • success:Boolean - True if successful. If false, no other attributes will exist
  • id:Number - Database ID of the shared content
  • name:String - Name of the shared content
  • permalink:String - Link to the shared content
  • content:String - The content itself
  • label:String - The label for the content

Example: Save some shared content to as a "Contraption" with the contents "x1y3z10", calling back onContraptionSaved using myContraptionEditor for the thumbnail and with the label "Level 3 Solution" 

kongregate.sharedContent.save('Contraption', 'x1y3z10', onContraptionSaved, myContraptionEditor, 'Level 3 Solution');

function onContraptionSaved(params:Object) {
  if (params.success) {
    // The shared content was saved successfully.
    trace("Content saved, id:" + params.id + ", name:" + params.name);
  } else {
    // The shared content was not saved.
    // The most likely cause of this is that the User dismissed the save dialog  
  }
}

Saving shared content on sites other than Kongregate

You may submit shared content created in versions of your game hosted on sites other than Kongregate. The API simply consists of a set of URL parameters you pass along with a GET request to your game's URL on Kongregate.

The relevent query parameters are type, content, and optionally, label. Note that this method is more limited in terms of the size of the content due to browser limitations with passing through a URL - they need to be limited to under 2,000 characters after encoding in order to ensure that it will work.

Additionally, a trailing &z must be appended to the URL to indicate the content was not truncated.

Example

This snippet is a simple function that accepts the relevant arguments and forwards them to Kongregate: 

var saveRemote:Function = function(kongregateGameUrl:String, contentType:String, content:String, label:String=null):void {
  var toQueryString:Function = function(params:Object):String {
    var q:Array = [];
    for (var p:String in params) q.push(encodeURIComponent(p) + '=' + encodeURIComponent(params[p]));
    return q.join('&');
  }
  
  var loc:String = kongregateGameUrl + "?" + toQueryString({
    'type': contentType,
    'content': content,
    'label': label
  }) + '&z';

  // This &z sigil indicates that no content was truncated from the URL by a nasty browser
  // and is required for your level to be saved when a user visits the game
  
  // Make sure your URL isn't going to be too long to send through a browser
  if (loc.length < 2000)
    navigateToURL(new URLRequest(loc), '_blank');
  
  // else...
  // You will need to provide some error handling in cases where the content is too large
}
Click Here