JSON Feed Type

Feeds come in two flavors, Atom and JSON. Atom is the default feed type served, however you may also request any feed in JSON format. The following is an example of all games in JSON format.

http://www.mochimedia.com/feeds/games/XXXX/?format=json

All games

This is the root feed url and will contain the entire catalog of Mochi enabled games:

http://www.mochimedia.com/feeds/games/XXXX

NOTE: You must include your own publisher ID in the feed URL. For purposes of these examples XXXX will represent your publisher ID

Limiting the amount of games

You can limit the number of games returned in the feed. This is useful for feed readers or widgets in which you want to pull a smaller, faster, feed for real-time display.

http://www.mochimedia.com/feeds/games/XXXX/?limit=25

You can also use the offset parameter to fetch older games in smaller chunks. Note that the feed can change at any moment so iterating over the feed with the offset parameter is not guaranteed to be reliable. If you are doing this, you must make sure to increment your offset in quantities sufficiently smaller than your limit so that you do not miss any games. offset must be combined with limit.

http://www.mochimedia.com/feeds/games/XXXX/?limit=25&offset=10

Limiting to a single category of games

You may place the slug of any category after your publisher ID to limit the type of games in the feed. Games may contain more than one category, so you may see the same game show up across different categories.

http://www.mochimedia.com/feeds/games/XXXX/action/

Limiting games to an content rating

If you want restrict the game feed to only contains containing an particular content rating, you may place the slug of the content rating as a second parameter after your publisher ID.

http://www.mochimedia.com/feeds/games/XXXX/all/teen/

NOTE: This is not inclusive of wider content ratings. The above example will return only teen rated games.

List of available rating slugs:

• all
• everyone
• teen
• mature

Limiting by both category and ratings

You may combine URL parameters to limit by both a category and a rating.

http://www.mochimedia.com/feeds/games/XXXX/action/mature

1.1 Overview

The Bridge is a feature that allows communication between a Mochi Scores game and the publisher.

Benefits of using the Bridge:

• Leverage hundreds of Mochi Scores enabled games to attract new players.
• Build exciting site features – Save player scoring info for all Mochi Scores games.
• Encourage competition – In-game scores are listed for your community only.
• Maintain consistency – Display your own community usernames when players post scores.
• Promote your brand – Put your site logo directly in the game.

Bridge integration is great for:

• Show top scores and gaming history in your player profiles.
• Show friend scores to players and let them invite others to compete.
• Get players hooked with points or prizes for obtaining top rankings.

1.2 Installing the Bridge

The Bridge is implemented as a simple JavaScript embed you can place on your game pages. This code acts as a secure connection to the publisher site, sending any relevant information it receives from the game, and giving the game any relevant information it requires. This provides a layer of separation between the game developer's code and the publisher site.

The embed code and settings for the Bridge can be found on your publisher settings page.

Note: You don't need to worry if the game is a Mochi game or if it is Mochi Scores enabled. The Bridge will sit quietly if it can't communicate with a game.

1.3 Embed Example

The following example demonstrates a typical Bridge embed with JavaScript.

<div id="leaderboard_bridge"></div>
<script src="http://xs.mochiads.com/static/pub/swf/leaderboard.js" type="text/javascript"></script>
<script type="text/javascript">
// Mochi Bridge
var options = {partnerID: "[[Publisher ID provided by Mochi Media]]", id: "leaderboard_bridge"};
options.userID = "29281";
options.username = "rockstar";
// optional
options.sessionID = "sf908uw098urerjw3948";
// optional
options.gateway = "http://www.example.com/bridge/";
// optional
options.profileURL = "http://www.example.com/profile/${name}";
// optional
options.logoURL = "http://www.example.com/images/icon_16x16.jpg";
// optional
options.siteURL = "http://www.example.com/";
// optional
options.siteName = "Example.com";
// optional
options.callback = function (params) { alert(params.name + " (" + params.username + ") just scored " + params.score + "!"); }
// uncomment this to display global scores
// options.globalScores = "true";

// optional
// options.denyScores = "Login to Example to submit scores!";

// optional
// options.denyFriends = "true";
// optional
// options.denyChallenges = "true";
/*
// uncomment this block for debug mode
options.width = 320;
options.height = 240;
options.debug = "true";
*/
Mochi.addLeaderboardIntegration(options);
</script>

You can find your unique publisher ID in your publisher settings page.

1.4 Embed Parameter Descriptions

Certain publisher information is required in order to take advantage of various Bridge features. This metadata is provided as variables passed to the JavaScript function that initiates the Bridge.

• partnerID
  Your unique publisher ID. This can be found in your publisher settings page.

• id
  The id of the HTML element you want to place the Bridge SWF into. If this parameter is NOT set, the Bridge will write a new DIV element to the page with the id of 'mochi_leaderboard_bridge'. This DIV will be written in the same location the Bridge JavaScript call is made.

• userID (optional)
  The unique id for the user on the site. This is a string which must be unique for each user. This ID is passed back you if you are providing a gateway URL for scores.
  Please note in Leaderboard 3.0: this value is now used to determine if a user is logged into your portal. You may specify any value you wish here, it should however be unique to individual users. Please do not specify userIDs for guest accounts.

• userPrefix (optional)
  Deprecated in Leaderboard 3.0: See profileURL for alternative.

• gateway (optional)
  A fully qualified URL on which will receive posted leaderboards data. ('http://' is required).

• username (optional)
  The display username for the player for your site. The game will check to see if the Bridge SWF has received a username from the publisher site. If it has, then it will use that username instead of allowing the user to enter one. For guests, you can either supply a generated guest name yourself (such as 'guest1234') or allow them to enter their own names.

• sessionID (optional)
  The unique identifier for the current logged in user session on your own site. If you supply this session variable, it will be passed through to your gateway for authentication.

• logoURL (optional)
  A URL to an 16x16 JPG icon for your site. This will display on the leaderboard within the game. This will not be used unless a siteName has been specified.
  Please note: For compatibility with older games, our services are designed to run in flash player 7 and higher. As a result, we are only able to support JPG images at this time.

• siteURL (optional)
  The URL of your site. Used as a link on the 16x16 JPG icon.

• siteName (optional)
  The name of your site. This will display on the leaderboard within the game.

• globalScores (optional)
  Set to true if you wish to display global scores and not just those submitted from your site.

• pageURL (optional)
  A valid URL to play this game on your site. Defaults to location.href. Normally this default is fine unless you keep sessions in the URL or your games are played in an IFRAME (such as with Facebook apps).

• callback (optional)
  A JavaScript function which will be called when the player submits a score. This can be used instead of the gateway if you prefer to handle the score information via the client-side. Or you may want to alter the game page based on the submission. The function receives a JavaScript object as a single parameter using the same naming system as the gateway score submission.

• postMedals (optional)
  This parameter will allow the bridge to post back information regarding medals received by the player. This parameter defaults to false.

• denyScores (optional)
  This parameter will replace the score submission portion of the leaderboard with the value that this parameter is set to. The value will be rendered as HTML in flash, and must conform to AS2 HTML formatting requirements. This allows publishers to ask users to login before they are allowed to submit scores to the leaderboard. This parameter will also remove challenge integration.

• denyFriends (optional)
  When defined as "true", this parameter removes references to external friend networks. That includes the Friends tab and the Facebook integration.

• thumbURL (optional)
  New to leaderboard 3.0. You can now specify a thumbnail image for user profiles. These images will be displaced next to user's score that have been submitted to publisher domain boards. globalScores must be set to false for this option to work. This parameter will be ignored on all submissions that provided without a valid userID.
  
  URLs may be keyed by either userID or username. These values are inserted into the URL using two magic tokens "${uid}" and "${name}". For example, if user "asterick" as logged in with id "09DE", specifying a thumbURL of "http://www.sploder.com/thumbs/${name}.${uid}.gif" will load "http://www.sploder.com/thumbs/asterick.09DE.gif". These values are case sensitive.
  Please note: For compatibility with older games, our services are designed to run in flash player 7 and higher. As a result, we are only able to support JPG images at this time.

• profileURL (optional)
  New to leaderboard 3.0. You can now specify a templated link for user profiles. These profiles will be accessible by clicking any score submission on your leaderboard that has an associated userID. globalScores must be set to false for this option to work. This parameter will be ignored on all submissions that provided without a valid userID.
  
  URLs may be keyed by either userID or username. These values are inserted into the URL using two magic tokens "${uid}" and "${name}". For example, if user "asterick" as logged in with id "09DE", specifying a profileURL of "http://www.sploder.com/profile/${name}?uid=${uid}" will load http://www.sploder.com/profile/asterick?uid=09DE" will". These values are case sensitive.

• publisherHTML (optional)
  New to leaderboard 3.0: Publishers may now specify a full, HTML encoded page to be included with the leaderboards. This block of text will appear as it's own tab and is fully customizable to the publishers wishes. This page can be used to drive registrations, push logins or even display statistics about the current logged in player.
  
  Currently, only a limited subset of HTML is supported. Please consult Adobe's 'Using HTML-formatted text' for a more in-depth reference. We support 3 internal style classes, 'default', 'title' and 'byline'.

• publisherTab (optional)
  New to leaderboard 3.0: If you have specified a publisherHTML block, setting this value allows you to change the title text of the tab. This value defaults to "Publisher"

1.5 Receiving Player Score Data

To receive scoring information, publishers will need to supply a gateway URL in the embed parameters for the Bridge to send game data. The Bridge will post the data (as HTTP POST parameters) to this URL when the score is submitted. The parameters are:

Score Information:

Player score is typically reported at the end of the game. The player is prompted to submit their score for one or more leaderboards. Leaderboards are defined by the game developer, and can represent a number or length of time (in milliseconds).

• submission
  "score" will be passed here. This is used to filter score submissions.

• userID
  Unique ID of the logged-in player. This will be what you supplied in the embed parameters.

• name
  Username the user input for the score.

• username
  Username you supplied in the embed parameters.

• sessionID
  Returned ID provided through the embed parameters to identify the unique user playing the game.

• score
  Integer indicating the score the player is submitting

Leaderboard Metadata:

Each leaderboard contains metadata to describe how the score should be tracked and displayed. The Bridge will supply the meta data for game leaderboards each time a score is submitted. It is up to the publisher to store this metadata in order to properly display leaderboards on their site.

• gameID
  Unique ID of the game the leaderboard belongs to.

• boardID
  Unique ID of the leaderboard.

• title
  Title of the leaderboard

• description
  Text description of the leaderboard (optionally supplied)

• datatype
  Value indicating the type of score. Values are either 'number' or 'time'. Note: time is supplied in milliseconds

• sortOrder
  Value indicating the sort direction of the scores. Values are either 'asc' or 'desc'.

• scoreLabel
  Label to indicate what the score represents. (ex: 'Track time', 'Gems', or 'Points')

Authentication Data:

• signature
  (this is part of the security protocol explained below in 1.6)

1.6 Receiving Player Medal Data

To receive medal information, publishers will need to supply a gateway URL in the embed parameters for the Bridge to send game data. The Bridge will post the data (as HTTP POST parameters) to this URL when the medal is submitted. The parameters are:

Medal Information:

Player score is typically reported at the end of the game. The player is prompted to submit their score for one or more leaderboards. Leaderboards are defined by the game developer, and can represent a number or length of time (in milliseconds).

• submission
  "medal" will be passed here. This is used to filter medal submissions.

• name
  Plain test name of the medal achieved.

• description
  Plain text description of the medal achieved.

• thumbnail
  Fully qualified URL to a 64x64 pixel image of the medal.

• gameID
  Unique ID of the game that this medal is associated with.

• userID
  Unique ID of the logged-in player. This will be what you supplied in the embed parameters.

• username
  User name of the player. This will be what you supplied in the embed parameters.

• sessionID
  Returned ID provided through the embed parameters to identify the unique user playing the game.

Authentication Data:

• signature
  (this is part of the security protocol explained below in 1.6)

1.7 Partner Server Authentication

In your publisher settings page you'll find a secret key that can be used to authenticate the score data sent from the Bridge to your server. The signature is an MD5 hash of the POST vars + your secret key.

In order to use this for authentication, create a string of all the POST vars and their values, EXCEPT signature. The POST vars and values should be a URL encoded string, sorted alphabetically by param name.

When the Bridge sends variables to the supplied gateway, all parameters are treated as escaped UTF-8 data using the encoding specified by RFC 1738. This will mimic the behavior laid out by the PHP rawurlencode() function in most conditions.

In accordance to this standard, we will not escape: Letters, numbers, hyphens ('-'), periods ('.'), or underscores ('_').

Equivalent escaped form of commonly used characters

%20

space

%21

!

%22

"

%23

#

%24

$

%25

%

%26

&

%27

'

%28

(

%29

)

%2A

*

%2B

+

%2C

,

%2F

/

%3A

:

%3B

;

%3C

<

%3D

=

%3E

>

%3F

?

%40

@

%5B

[

%5C

\

%5D

]

%5E

^

%60

`

%7B

{

%7C

|

%7D

}

%7E

~

1. Populate an array of all parameter names as keys and their values.
2. Remove out the signature parameter.
3. Sort the array alphabetically by the key name.
4. Turn the array into a url encoded string that looks like this:

   boardID=1e113c7239048b3f​&datatype=number​&description=This%20is%20the%20MochiScores​&gameID=84993a1de4031cd8​&name=rockstar​&score=11519​&scoreLabel=score​&sessionID=sf908uw098urerjw3948​&sortOrder=desc​&title=My%20Top%20Scores​&userID=29281​&username=rockstar

5. Append your secret key. For example, if your query string before was ...

   &username=rockstar

   then it would look like

   &username=rockstarsdcb66e8d7676deb7e6db787cbd98d

6. Compute the MD5 hash with the string, and compare your MD5 hash with the signature parameter sent by the Bridge. They should be identical.

This security authentication protocol is optional, since the data sent is not encrypted. Due to the fact that all of the game-play interaction and communication occurs within the client browser, this security protocol is not foolproof. However, this system will make it more difficult for the casual user to send fake scores to your site. You can also use your own user session ID information that you pass through the SWF to further authenticate the requests.

Note: While using PHP, use caution when working with 'magic quotes'. Developer and user defined variables such as names and leaderboard titles could contain special characters such as backslashes which can result in unwanted behavior. For best results, use single quotes or disable magic quotes all together.

2.1 Overview

You can display high score information directly on your website using our Leaderboards Widget. The widget accepts a game slug and partner ID and will display all the available leaderboards for the given game. The partner ID will constrain the widget to showing only scores from your site if you choose to do so. The widget is a Flash .SWF that can be embedded on any HTML page on your site. Note that the Leaderboards Widget is separate from the Bridge. If you want site-locked scores or other customizations, you must implement the Bridge.

2.2 Installing the Leaderboards Widget on your site

This widget is a Flash .SWF that can be embeded on any HTML page on your site. You can customize the widget's look and feel through EMBED tag parameters. You can also find pre-populated EMBED examples for every qualifying game in the Mochi Media game catalog.

Basic Embed Example:

We recommend using one of the JavaScript based examples below, but if you want something super simple here it is! The following example uses an embed tag to embed a 400x400 leaderboard widget for the game with the slug "mochiscores-sample-game":

<embed src="http://xs.mochiads.com/static/pub/swf/LeaderboardWidget.swf?game=mochiscores-sample-game"
allowscriptaccess="always" allowmenu="false" quality="high" width="400" height="400"
type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer"></embed>

Simple JavaScript Example:

The following example uses JavaScript to embed a 400x400 leaderboard widget for the game with the slug "mochiscores-sample-game":

<div id="leaderboard_widget"></div>
<script src="http://xs.mochiads.com/static/pub/swf/leaderboard.js" type="text/javascript"></script>
<script type="text/javascript">
Mochi.showLeaderboardWidget({game: "mochiscores-sample-game", id: "leaderboard_widget"});
</script>

Customized JavaScript Example:

The following example uses JavaScript to embed a fully customized 500x500 leaderboard widget for the game with the slug "mochiscores-sample-game", replacing an existing div with the id "leaderboard_widget" and using publisher-specific scores: NOTE: you can select a specific tab by defining the 'defaultTab' option. Valid tabs are: "daily", "weekly", "monthly", and "alltime".

<div id="leaderboard_widget"></div>
<script src="http://xs.mochiads.com/static/pub/swf/leaderboard.js" type="text/javascript"></script>
<script type="text/javascript">
// Customized example: Embeds a 500x500 leaderboard widget, replacing the "leaderboard_widget" div
var options = {game: "mochiscores-sample-game", width: 500, height: 500, id: "leaderboard_widget"};
// Select a specific leaderboard for a game - optional (if not included, a selectable list will be used)
options.leaderboard = "Level 1";
// your publisher ID - optional (if not included, ALL scores from all sites will be shown)
options.partnerID = "0123456789adbcdef";
// username link prefix - optional
options.profileURL = "http://www.example.com/profile/${name}";
// leaderboard background color - optional
options.backgroundColor = "#ffffff";
// Show the widget!
options.defaultTab = "alltime";
// Default to the all time tab!
Mochi.showLeaderboardWidget(options);
</script>