Chat.AddEventListener
Listen for chat messages from the useraddEventListener(event_type, callback)
Listening for chat text entry
The chat
property on the Kongregate API object broadcasts several different types of events. The message
event lets you know when the player has submitted a message in the custom chat tab, while the room.message
event notifies you of messages from other users in game chat, allowing you to listen in and react.
The addEventListener
method takes two arguments, the event type, and a callback function:
event_type
String
Type of event to listen for
callback
Function
Function to call when the event is triggered
The message
event
The message
event is broadcast when the player submits text in the entry box on your custom tab. It has a single data
field with the following properties:
username
String
The username of the user who sent the message (will always be the current user)
message
String
The message content
Example: Listen for the player submitting a chat message in a custom tab
function onPlayerMessage(event:*):void {
trace("Message from " + event.data.username + ": " + event.data.message);
}
kongregate.chat.addEventListener("message", onPlayerMessage);
function onPlayerMessage(event) {
console.log("Message from " + event.data.username + ": " + event.data.message);
}
kongregate.chat.addEventListener("message", onPlayerMessage);
The room.message
event
The room.message
event is broadcast when a game chat message is received. It has a single data
field with the following properties:
username
String
The username of the user who sent the message
room
Object
An object with name
and id
properties
message
String
The message content
history
Boolean
A flag indicating whether or not the message was retrieved from the room history or not
Example: Listen for game chat messages
function onRoomMessage(event:*):void {
trace("GameChat: " + event.data.username + ": " + event.data.message);
}
kongregate.chat.addEventListener("room.message", onRoomMessage);
function onRoomMessage(event) {
trace("GameChat: " + event.data.username + ": " + event.data.message);
}
kongregate.chat.addEventListener("room.message", onRoomMessage);
The tab_visible
event
The tab_visible
event is broadcast when a custom tab has been shown after a call to showTab
function onTabVisible(event:*):void {
trace("Tab visible!");
}
kongregate.chat.addEventListener("tab_visible", onTabVisible);
function onTabVisible() {
console.log("Tab visible!");
}
kongregate.chat.addEventListener("tab_visible", onTabVisible);
Chat.ClearMessages
Remove all chat messages from the custom tabclearMessages()
This function clears all messages in a previously opened custom chat tab.
kongregate.chat.clearMessages();
kongregate.chat.clearMessages();
Chat.CloseTab
Close a custom chat tabcloseTab()
This function closes a previously opened custom chat tab.
kongregate.chat.closeTab();
kongregate.chat.closeTab();
Chat.DisplayMessage
Display a message in the custom chat tabdisplayMessage(message, username)
The displayMessage
function on the chat
property of the Kongregate API object can be used to create a virtual chat message from a given user in the custom chat tab. It accepts the following arguments:
message
String
The message to display
username
String
The username the message is from
Example: Display a message "Hi there!" from user "BenV"
kongregate.chat.displayMessage("Hi there!","BenV");
kongregate.chat.displayMessage("Hi there!","BenV");
Chat.ShowTab
Displays a custom chat tabshowTab(name, description, options)
Displaying a Custom Tab
This function displays a custom chat tab in the chat area, which will replace any other custom tabs that might be showing. It takes a name
, description
, and options
:
name
String
Name of the tab
description
String
Description of the tab
options
Object
Extra options for the tab
The options object can have the following properties:
size
Decimal
Relative size of the canvas, 0 being the smallest, 1 being the largest (default 0.5)
Example: Display a custom tab with a large canvas
kongregate.chat.showTab("MyTab","My Custom Tab", {size:0.75});
kongregate.chat.showTab("MyTab","My Custom Tab", {size:0.75});
Note
The name
and description
parameters are currently unused - the tab will display "Match" at the top for now. These may be implemented in the future, so adding them in your code will ensure that it will work when we do.
Images.SubmitAvatar
Ask the user to change their avatarsubmitAvatar(display_object, callback)
Exporting a custom avatar
Kongregate's Avatar Export API gives you the ability to export in-game avatars and let users use them as their Kongregate profile avatar. When you call the submitAvatar
function, the user will receive a notification that the game is requesting to change their avatar. At that point, they'll be able to crop the suggested image if they wish, and can choose to accept or decline the avatar modification. This functionality can be used to provide bonuses for players, as well as more directly with avatar creator/editor apps, and probably other uses we haven't even thought of yet.
You can use the submitAvatar
function on the images
property of the Kongregate API object to export a DisplayObject
or a Base64-encoded string containing the image data to be converted to a user avatar. It is highly recommended that avatars be at least 40x40px:
display_object
DisplayObject or Base64-encoded string
The DisplayObject or Base64-encoded string containing the avatar image
callback
Function
The callback function to be called when the operation is complete.
The callback function is passed a single boolean parameter which will be true if the user has accepted the avatar and false if they decide not to use it.
Example: Exporting a rectangle
var rect:Shape = new Shape();
rect.graphics.lineStyle(1);
rect.graphics.beginFill(0x0000FF, 1);
rect.graphics.drawRect(0, 0, 75, 50);
kongregate.images.submitAvatar(rect, onAvatarComplete);
function onAvatarComplete(success:Boolean) {
if(success) {
trace("That user must love rectangles!")
} else {
trace("Next time I'll try a triangle :(")
}
}
var base64PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=';
kongregate.images.submitAvatar(base64PNG, function(success) {
if (success) {
console.log('That is a small avatar');
}
});
Mtx.AddEventListener
addEventListener(event_type, callback)
Mtx events
This method can be used to listen for events related to the incentivized advertising API
The addEventListener
method takes two arguments, the event type, and a callback function:
event_type
String
Type of event to listen for
callback
Function
Function to call when the event is triggered
adsAvailable
Ads are now available, and showIncentivizedAd
will work
adsUnavailable
Ads are not available, and showIncentivizedAd
will fail
adOpened
An ad is being displayed
adCompleted
An ad has completed successfully, and the player should be rewarded
adAbandoned
Ad ad has been closed before completion, the player should not be rewarded
Mtx.InitializeIncentivizedAds
Initialize the incentivized ad systeminitializeIncentivizedAds
The initializeIncentivizedAds
method requests ads from the back-end and allows you to receive events related to ads in the method you registered with addEventListener.
kongregate.mtx.initializeIncentivizedAds();
kongregate.mtx.initializeIncentivizedAds();
Mtx.PurchaseItems
Start the purchase flow for predefined itemspurchaseItems(items, callback)
Requesting Item Purchase
You may bring up the "purchase items" dialog box by using the purchaseItems
method on the mtx
property on the Kongregate API object. It takes either an array of item identifiers or an array of identifier/metadata objects, as well as a callback function which should be called with the result of the purchase:
items
Array
Array of item identifier strings, or an array of objects each with an identifier
and data
field.
callback
Function
A callback function for when the purchase dialog is closed.
The callback function is passed an object with the following fields:
success
Boolean
A flag indicating whether or not the purchase was successful.
Example: Purchasing a single item with identifier "sword":
kongregate.mtx.purchaseItems(["sword"], onPurchaseResult);
function onPurchaseResult(result:Object):void {
trace("Purchase success:" + result.success);
}
kongregate.mtx.purchaseItems(["sword"], onPurchaseResult);
function onPurchaseResult(result) {
console.log("Purchase success:" + result.success);
}
Application.ExternalEval(@"
kongregate.mtx.purchaseItems(['sword'], function(result) {
var unityObject = kongregateUnitySupport.getUnityObject();
var success = String(result.success);
unityObject.SendMessage('MyGameObject', 'OnPurchaseResult', success);
});
");
Metadata
You can attach a metadata string to the item instance if needed which can be retrieved from the server later. It is important to note that the client can change this data using a browser plugin fairly easily, so it is a good idea to obfuscate this string, as well as verify its validity as it relates to your game.
Example: Purchasing an item with metadata attached:
var items:Array = [{identifier:"sword", data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);
function onPurchaseResult(result:Object):void {
trace("Purchase success:" + result.success);
}
var items = [{identifier:"sword", data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);
function onPurchaseResult(result) {
console.log("Purchase success:" + result.success);
}
Mtx.PurchaseItemsRemote
Start the dynamic item purchase flowpurchaseItemsRemote(order_information, callback)
Requesting Remote/Dynamic Item Purchase
You may start the Dynamic Purchasing API purchase flow using the purchaseItemsRemote
method on the mtx
services object. It accepts an order info string which will be passed to your API callback as a signed request, as well as a callback function which should be called with the result of the purchase:
order_information
String
An order info string that will be passed to your server in an API callback.
callback
Function
A callback function for when the purchase dialog is closed.
The callback function is passed a single object with the following fields:
success
Boolean
A flag indicating whether or not the purchase was successful.
item_order_id
Integer
The unique ID of the transaction, or undefined if the purchase failed
Example: Starting a dynamic item purchase with order info set to 'sword':
kongregate.mtx.purchaseItemsRemote("sword", onPurchaseResult);
function onPurchaseResult(result:Object):void {
trace("Purchase success:" + result.success + ", id: " + result.item_order_id);
}
kongregate.mtx.purchaseItemsRemote("sword", onPurchaseResult);
function onPurchaseResult(result) {
trace("Purchase success:" + result.success + ", id: " + result.item_order_id);
}
Application.ExternalEval(@"
kongregate.mtx.purchaseItemsRemote('sword', function(result) {
var unityObject = kongregateUnitySupport.getUnityObject();
var success = String(result.success);
unityObject.SendMessage('MyGameObject', 'OnRemotePurchaseResult', success);
});
");
Once the purchase dialog is invoked, the item_order_request
signed request callback will be initiated to your API callback URL so that your game server can define the items to be purchased dynamically.
Mtx.RequestItemList
Request item definitions from the serverrequestItemList(tags, callback)
Requesting Item Definitions
The non-dynamic item definitions for a game can be retrieved using the requestItemList
method. This function takes an array of tags to filter on (pass an empty array for all items), and a callback function to call when retrieval is complete:
tags
Array
An array of strings containing tags to filter items with. Use an empty array or undefined
for no filter
callback
Function
A callback function to be called with the results of the operation
The callback function is passed a single object with the following fields:
success
Boolean
A flag indicating whether or not the operation was successful
data
Array
An array of item definitions, if successful
Each item definition in the data
array contains the following fields:
id
Integer
The unique ID of the item
identifier
String
The item identifier
name
String
The name of the item
description
String
The item description
price
Integer
The price of the item in Kreds
tags
Array
An array of strings containing the tags for the item
image_url
String
The image for the item
Example: Request all items:
kongregate.mtx.requestItemList([], onItemList);
function onItemList(result:Object):void{
trace("Item list result, success: " + result.success);
if(result.success) {
for(var i:int = 0; i < result.data.length; i++) {
var item:Object = result.data[i];
trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.name);
}
}
}
kongregate.mtx.requestItemList([], onItemList);
function onItemList(result){
console.log("Item list result, success: " + result.success);
if(result.success) {
for(var i = 0; i < result.data.length; i++) {
var item = result.data[i];
console.log((i+1) + ". " + item.identifier + ", " +
item.id + "," + item.name);
}
}
}
Mtx.RequestUserItemList
Request a user's inventory from the serverrequestUserItemList(username, callback)
Requesting User Item Instances
The inventory of any user can be requested by using the requestUserItemList
method. This function takes a username string as the first argument, but you may pass in null
or a blank string to request the inventory for the current user. The second argument is a callback function to call when retrieval is complete, which will generally involve a call to use_item or useItemInstance.
username
String
Username of the user to request items for, or null
for the current user
callback
Function
A callback function to be called with the results of the operation
The callback function is passed a single object with the following fields:
success
Boolean
A flag indicating whether or not the operation was successful
data
Array
An array of item instances, if successful
Each item definition in the data
array contains the following fields:
id
Integer
The unique ID of the item instance
identifier
String
The item identifier
data
String
The metadata attached to the item instance, if any
remaining_uses
Integer
Number of remaining uses, or 0 if this is an unlimited use item
Example: Request the inventory for the current player
kongregate.mtx.requestUserItemList(null, onUserItems);
function onUserItems(result:Object):void {
trace("User item list received, success: " + result.success);
if(result.success) {
for(var i:int = 0; i < result.data.length; i++) {
var item:Object = result.data[i];
trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.data);
}
}
}
kongregate.mtx.requestUserItemList(null, onUserItems);
function onUserItems(result) {
console.log("User item list received, success: " + result.success);
if(result.success) {
for(var i=0; i < result.data.length; i++) {
var item = result.data[i];
console.log((i+1) + ". " + item.identifier + ", " +
item.id + "," + item.data);
}
}
}
Mtx.ShowIncentivizedAd
Attempt to display an incentivized ad to the usershowIncentivizedAd
The showIncentivizedAd
method attempts to show an incentivized ad to the user. It will only work after the adsAvailable
event has been broadcast.
kongregate.mtx.showIncentivizedAd();
kongregate.mtx.showIncentivizedAd();
Mtx.ShowKredPurchaseDialog
Displays the Kred purchase interfaceshowKredPurchaseDialog(type)
Displaying the Kred Purchase Dialog
You may bring up the "purchase kreds" dialog box by using the showKredPurchaseDialog
method on the microtransaction services object. The only argument is the default purchase method you would like to display, which can be either offers
to show the OfferPal Kred options, or mobile
to show the mobile payment options. Any other value will simply show the default purchase dialog.
type
String
Optional type of offer to display, can be offers
or mobile
- any other value shows the default dialog
Example: Display the OfferPal Kred purchase dialog:
kongregate.mtx.showKredPurchaseDialog("offers");
kongregate.mtx.showKredPurchaseDialog("offers");
Handling Guest Users
Since guest users on Kongregate are not allowed to purchase items, you must decide how you want to handle them in your game. In general, whenever a guest user wants to purchase an item, it is a good idea to display a message letting them know they must sign in or register before they can purchase, and then display the sign-in lightbox. Further documentation on this process can be found here.
Mtx.UseItemInstance
Consume an item instance from the user's inventoryuseItemInstance(item_instance_id, callback)
Warning
This function should ONLY be used if your game does not have a server for consuming item instances. If your game has a server component, please use the server-side version.
Consuming user item instances
You can consume a limited-use item instance by using the useItemInstance
method. This function takes the item instance ID (retrieved using the requestUserItemList function) and a callback function to be called when the operation is completed.
item_instance_id
Integer
The item instance ID to be consumed
callback
Function
A callback function to be called with the results of the operation
The callback function is passed a single object with the following fields:
success
Boolean
A flag indicating whether or not the operation was successful
id
Integer
The ID of the item instance that was consumed
Example: Consume an item from the player's inventory
kongregate.mtx.useItemInstance(12345, onUseResult);
function onUseResult(result:Object):void {
trace("Item use result successful: " + result.success);
}
kongregate.mtx.useItemInstance(12345, onUseResult);
function onUseResult(result) {
console.log("Item use result successful: " + result.success);
}
Services.Connect
Connect to to the back-endconnect()
Connecting
The connect
function should be used as soon as you have access to the Kongregate API object in order to initialize the connection to our servers. For more information on initialization, see the Client API Introduction.
Note
This function only needs to be called when using the AS3 API, as the AS2 and JavaScript APIs will call it automatically. It is safe to call in other languages, but it will have no effect.
kongregate.services.connect();
Services.GetGameAuthToken
Get the game authentication token for the current usergetGameAuthToken()
Getting the player's game authentication token
You can use the getGameAuthToken
function to retrieve the game authentication token for the current user for use with the server-side authentication API. All guest users have the same authentication token, and do not need to be authenticated by your server.
Return value
String
The authentication token for the user.
Note
You should not assume that the authentication token will remain the same for each user, as it will change any time a user changes their password.
var token:String = kongregate.services.getGameAuthToken();
var token = kongregate.services.getGameAuthToken();
Services.GetUsername
Get the username of the current usergetUsername()
Getting the player's Kongregate username
You can use the getUsername
function to retrieve the username of the current player. It will begin with Guest
if the user is not signed in.
Return value
String
The username of the current user.
var username:String = kongregate.services.getUsername();
var username = kongregate.services.getUsername();
Services.GetUserId
Get the user ID of the current usergetUserId()
Getting the player's Kongregate user id
You can use the getUserId
function to retrieve the unique user ID of the current player. It will return 0 if the user is not signed in.
Please note that to securely authenticate a player, you should use the server-side authentication API.
Return value
Integer
The user ID of the current user.
var userId:Number = kongregate.services.getUserId();
var userId = kongregate.services.getUserId();
Services.IsGuest
Determine if the current user is a guestisGuest()
Checking if the user is a guest
The isGuest
function can be called to determine if the player is currently signed into Kongregate or not.
Return value
Boolean
A flag indicating whether or not the user is a guest.
var isGuest:Boolean = kongregate.services.isGuest();
var isGuest = kongregate.services.isGuest();
Services.PrivateMessage
Send a private message to the userprivateMessage(content)
Note
This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at apps@kongregate.com.
Private Messages
This feature sends a private message from your game to the player. You simply invoke the method with the desired message content. The message will appear in the player's messages, with your game as the sender.
If you are looking to send them messages when they are not logged in to the game, look at our Private Messages Server API.
content
String
The message to send
kongregate.services.privateMessage("You just did something really great!");
kongregate.services.privateMessage("You just did something really great!");
Services.ResizeGame
Resizes the game frameresizeGame(width,height)
Maximum required game size
Because a large percentage of our players play on laptops with relatively small screens, we request that games don't require any larger than a 1050x700 size if at all possible.
Automatically resizing the enclosing iframe
If your game is embedded on Kongregate as an iframe you can take advantage of our auto-resizing feature. With this enabled the game's frame will automatically size to be appropriate for the player's browser. Your game will then need to match it's parent frame and you'll be good to go.
To use this feature, go to your game's /edit
page (add /edit
to the end of your URL) and scroll down until you see the dimensions section. Just set both your normal (minimum) and maximum dimensions and that's it! If you need to disable this later, set the maximum dimensions to blank again.
Manually resizing the enclosing iframe
If you need to manually resize your game's enclosing container, or you are not hosting your game through an iframe, you may do so with the resizeGame call
. It accepts the following arguments:
width
Integer
Width of the frame in pixels
height
Integer
Height of the frame in pixels
The enclosing iframe will resize around your game. Games may not be resized smaller than their initial dimensions.
kongregate.services.resizeGame(900, 650);
kongregate.services.resizeGame(900, 650);
Services.ShowInvitationBox
Invite other users to play a gameshowInvitationBox(invitation)
Note
This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at apps@kongregate.com.
Invite Friends
This feature displays a dialog requesting the player send a Private Message to their friends inviting them to try your game. If the player is not authenticated, it will require the player to authenticate before displaying the dialog.
The Private Message includes a game specific message you provide and some text the player may enter in the dialog. The dialog includes an interface for selecting up to 20 friends and other Kongregate members to invite and a Text Field to edit a message. An optional filter parameter may be used to narrow the list of invitees to those that have or have not played the game.
invitation
Object
An object containing fields describing the invitation
The invitation
object can contain the following fields:
content
String
The text content of the invitation
filter
String
Optional parameter. If set to played
, the dialog will only allow the player to select users that have played the game. When set to not_played
, the dialog will only the player to select users that have never played the game. You can also pass a list of user IDs as the filter, and it will only show those users ex "123 8219"
. When left blank, all users will be available to invite.
kv_params
Object
An optional object containing parameters to be included in the game link. They must all be prepended with kv_
to be passed through to the game
Example Simple invitation:
kongregate.services.showInvitationBox({
content: "Come try out this awesome game!"
});
kongregate.services.showInvitationBox({
content: "Come try out this awesome game!"
});
Example Only invite players who have never played:
kongregate.services.showInvitationBox({
content: "Come try out this awesome game!",
filter: "not_played",
kv_params: { kv_promo_code: 12345 }
});
kongregate.services.showInvitationBox({
content: "Come try out this awesome game!",
filter: "not_played",
kv_params: { kv_promo_code: 12345 }
});
Services.ShowFeedPostBox
Create a post in the user's activity feedshowFeedPostBox(content)
Note
This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at apps@kongregate.com
Feed Posts
This feature displays a dialog requesting permission to make a feed post to a player's wall on behalf of the game. If the player is not authenticated, it will require the player to authenticate before displaying the dialog.
The player may optionally allow all posts from your game. If the player choses to enable that feature, then this will automatically make a post on that player's wall without invoking the dialog.
The showFeedPostBox
method takes a content argument, which can either be a string containing the text to place into the feed, or an object that contains properties defining the content, image, and parameters to be passed into the game. It fires a callback once the dialog is closed.
content
String or Object
A string containing the text for the feed post, or an object with content
, image_uri
, and kv_params
fields.
callback
Function
A callback method which will be called with an object containing type
, recipients
, success
, and error
fields.
Note
While the game is not published (in "preview" mode), the post will not actually show on the user's feed. This is to avoid confusion around games that aren't public sending out messages. As long as you get the pop-up friend selection box and confirmation the API is integrated correctly
Making a Feed Post
Feed posts are composed of two components: the content of the feed post, and (optionally) an image URI that you specify. If you do not specify an image URI, then the game's icon will be used instead.
Basic Feed Posts
If you don't need a custom image, you may invoke showFeedPostBox with a string containing the post content:
kongregate.services.showFeedPostBox("Praise the Sun!", function(result:Object):void {
trace("Success: " + result.success);
});
kongregate.services.showFeedPostBox("Praise the Sun!", function(result) {
console.log("Success: " + result.success);
});
Using a Custom Image and Parameters
If you wish to specify a custom image and parameters to be passed into the game when clicked, then you will need to pass in an object with the properties:
content
String
The text content for the feed post
image_uri
String
Link to an image to use as an icon for the feed post
kv_params
Object
Optional parameters to be passed into the game when the feed post link is followed
Example: Complex feed post:
kongregate.services.showFeedPostBox({
content: "Come help defeat the boss!",
image_uri: "http://your-domain.tld/feed-post-images/really-hard-boss-face.png",
kv_params: { kv_promo_code: 12345 }
}, function(result:Object):void {
trace("Success: " + result.success);
});
kongregate.services.showFeedPostBox({
content: "Come help defeat the boss!",
image_uri: "http://your-domain.tld/feed-post-images/really-hard-boss-face.png",
kv_params: { kv_promo_code: 12345 }
}, function(result) {
console.log('Success: ' + success);
});
Services.ShowRegistrationBox
Allows guests to sign in or create an accountshowRegistrationBox
Showing the registration box
If the player is a guest, and you want to display the registration UI to them (for example, if you want to upsell them to buy an item or you want to use the authentication API), you can use the showRegistrationBox
function.
kongregate.services.showRegistrationBox();
kongregate.services.showRegistrationBox();
You can read the section on handling guests for more information on how to tell when a user completes registration or signing in.
Services.ShowShoutBox
Post a shout on the user's profile pageshowShoutBox(message)
Note
This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at apps@kongregate.com.
Showing the shout box
If a player is logged-in and you want to allow them to post a shout on their profile page, you may bring up the shout box, optionally populated with some initial content. The showShoutBox
function takes the following arguments:
message
String
The message text to add to the shout
When the function is called, a pop-up will appear giving the player a preview of the shout, and allowing them to add their own text. Once they've done this, the message will read:
[User added text] [Text added by function call] on [Game name with link]
So, for example, if your game "Grind Quest MMO" called kongregate.services.showShoutBox("User43 spent 50 hours grinding to get to level 4")
, and the user added "I really need to get a life!", the resulting shout would read:
I really need to get a life! User43 spent 50 hours grinding to get to level 4 on Grind Quest MMO
Example Creating a shout:
kongregate.services.showShoutBox("I accidentally ate the whole thing!");
kongregate.services.showShoutBox("I accidentally ate the whole thing!");
Stats.Submit
Submit statistics/scores to the serversubmit(statistic_name, value)
Statistics Client API
Submitting statistics from your game using the Client API couldn't be easier. First, make sure you have read the documentation about how to define statistics for your game on the Kongregate servers.
Submitting statistics
The API for submitting a statistic to our servers is very simple. The submit
function on the stats
property of the Kongregate API Object takes two arguments. The first is the name of the statistic as you defined earlier, and the second is an integer for the value:
statistic_name
String
The name of the statistic to submit.
value
Integer
The value of the statistic to submit.
Example: Submit various statistics to the server
kongregate.stats.submit("Coins", 1); // The user collected a coin
kongregate.stats.submit("MonstersKilled", 1); //The user killed a monster
kongregate.stats.submit("HighScore", 398); //The user got a score of 398
kongregate.stats.submit("LapTime", 60); //User finished a lap in 60 seconds
kongregate.stats.submit("Coins", 1); // The user collected a coin
kongregate.stats.submit("MonstersKilled", 1); //The user killed a monster
kongregate.stats.submit("HighScore", 398); //The user got a score of 398
kongregate.stats.submit("LapTime", 60); //User finished a lap in 60 seconds
Authenticate
Verifies a user's identity
The Authentication API allows Kongregate players to play any game without registering or entering a password. By making a call to the web service from your game server you can securely determine the player's Kongregate user id and username.
Note
This method should only be called from a server, not a game client.
For more information on how Kongregate users should be authenticated in your game, see this document.
Badges
Retrieves badge definitions
This endpoint is useful for people making things like the Kongregate Firefox Sidebar. There are two different badge feeds - one for badge releases on the site, and the other as a list of badges a particular user has earned.
You can query for which badges a user has been awarded using the User Badges API.
Badges - User
Retrieves information about a user's badges
This endpoint allows you to retrieve a list of badges that a given user has been awarded. You can query for a list of all available badges using the Badges API.
Characters
Creates/manages game characters for use with guilds
Adding a Character to a Guild
Adding a player's character to a guild is handled by a call to /characters.json
. In the case that a character is added to a guild that has not been created yet, this call will have the side effect of creating that guild.
There are three types of guild members:
- Admin: Can lock, sticky, edit, and hide forum posts in the guild forum. We suggest giving guild officers an admin status.
- Superadmin: Currently has the same permissions as a regular admin, but we may change that later. It would be best to restrict this to the owner of a guild.
- Member: Has access to and can post in guild chat and forums. To denote a character as a member, don't pass the
guild_admin_level
parameter when adding the character to the guild.
Removing a Character from a Guild
In the case that a user leaves a guild, or is booted from one, that user should no longer have access to guild specific forums or chat. The call to remove a character is almost identical to the call to add a character, except the guild_identifier
and guild_name
shouldn't be submitted at all (or alternatively submitted as empty strings).
Revoking a Character's Superadmin or Admin Status
You can revoke a user's Superadmin or Admin status similarly with a call that resubmits the all of the character's guild parameters the same, except without the guild_admin_status
parameter.
High Scores
Retrieve high scores for a statistic
Note
You can find statistic IDs for your game on the "edit statistics" page
Items - Consume
Use a consumable item from a user's inventory
This HTTP endpoint allows you to use a limited-use item belonging to a user. You must pass in the id of the item instance to use. This id can be obtained from the user's inventory. It is important to note that this is NOT the same as the item id which is returned from the items action. Calling this action on an unlimited use item will return failure, since that operation is not supported.
Note:
Note
This method is to be called from a server only. If, and only if, the game is client-side only with no server, you will need to use our client API call to consume items.
Items - User
Retrieve a user's inventory
This HTTP endpoint allows you to request the list of items that belong to a user. These are referred to as item instances. Item instances will only be returned by this method if they have remaining uses, or are unlimited-use items. This should be done after receiving a callback or successful transaction event, as well as each time the game loads in order to check for un-credited items in the inventory.
Note
This call should only be made from a server. To retrieve a user's items from your client, see the requestUserItemList method.
Private Messages
Send messages to Kongregate users
Note
This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please contact us
This function allows you to send a message to a player through a server-side POST, even if that player is offline. It can be used to let players know about updates, information directly relevant to their game status, or whatever else would make sense. However, please keep the messages relevant and well-targeted. We reserve the right to discontinue access to this API if a game is using it excessively or sending information that is not applicable to the recipient.
The targeted user must have played the game recently (within two weeks), and only one message can be sent per player per day.
The user_id
and username
parameters are optional, but you must include one or the other.
Statistics
Submit statistics and high scores
This method submits statistics for uses with badges and high scores. Any parameters other than api_key
and user_id
are assumed to be statistic names for your game, and will be submitted as such.
User Information
Retrieve information about Kongregate users
Note
If you are intending to load lots of user information (for example, loading the avatar URLs for all of a user's friends), you should use the multiple id/username version of the request to avoid long load times or timeouts due to making lots of requests. These group requests can be done with up to 50 user IDs or usernames at a time. The friends flag is not supported when requesting multiple records.