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.mochiads.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.mochiads.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.mochiads.com/feeds/games/XXXX/?limit=25

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.mochiads.com/feeds/games/XXXX/action/

Limiting games to an ESRB 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.mochiads.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.mochiads.com/feeds/games/XXXX/action/mature

1.1 Overview

Integrated leaderboards is a feature that allows MochiAds to provide game information to publisher sites during game play. It also, optionally, allows publishers to set games to a particular user context by providing user information for the current player. This allows publishers to track and correlate game activity for each user on their site.

Benefits of MochiAds Integrated Leaderboards:

• Leverage the hundreds of leaderboard enabled games to attract new players.
• Build exciting site features – Save player scoring info for all MochiAds leaderboard-enabled 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.

MochiAds Integration is great for:

• Build player-to-player challenges to encourage repeat plays.
• 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 Integrated Leaderboards

The Integrated Leaderboards feature operates through a SWF that resides on MochiAds and is embedded on the same page as any game that will make use of it. This SWF 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's API, which may or may not be open. This means all the data sent to the publisher from any game goes through the MochiAds API and sent via a SWF served from MochiAds servers.

The settings, and URL for the Integrated Leaderboards SWF can be found on your publisher settings page.

Note: You don't need to worry if the game is leaderboard enabled. The Integration SWF will sit quietly if it can't communicate with the game.

1.3 SWF Embed Parameter Descriptions

Certain publisher site metadata is required in order to set the proper context for the functions and messaging within the system. This metadata will be provided as variables placed in the object/embed tag for the Integrated Leaderboards SWF.

• userID
  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

• 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 Integrated Leaderboards 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.

• userPrefix (optional)
  A URL prefix to use as a link to a user's profile on your site (e.g. "http://www.example.com/profile.php?username=" or "http://www.example.com/profile/") The supplied username will be appended to this URL.

• logoURL (optional)
  A URL to an 88x31 JPG banner for your site. This will display within the game on the leaderboard.

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

1.4 Embed Example

The following example demonstrates a typical Integrated Leaderboards 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 Integrated Leaderboards
var options = {partnerID: "[[Publisher ID provided by MochiAds]]", id: "leaderboard_bridge"};
options.userID = "29281";
options.username = "rockstar";
// optional
options.sessionID = "sf908uw098urerjw3948";
// optional
options.gateway = "http://www.example.com/bridge/";
// optional
options.userPrefix = "http://www.example.com/profile/";
// optional
options.logoURL = "http://www.example.com/images/banner_88x31.jpg";

// uncomment this to display global scores
// options.globalScores = "true";

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

You can find your Integration publisherID in your unique publisher settings page.

1.5 Receiving Player Score Data

To receive scoring information, publishers will need to supply a gateway URL in the embed parameters via which MochiAds will send game data. The Integrated Leaderboards SWF 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).

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

• userName - Username the user input for the score, or if you supplied on 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 Integrated Leaderboards SWF 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 - IValue 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 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 Integration SWF 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.

1. Populate an array of all param names as keys and their values.
2. Splice out the signature param.
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 param 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 param sent by MochiBridge. They should be the same.

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.

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.

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 our MochiAds 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:

<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"};
// your publisher ID - optional (if not included, ALL scores from all sites will be shown)
options.partnerID = "0123456789adbcdef";
// username link prefix - optional
options.userPrefix" = "http://www.mochiads.com.com/community/profile/";
// leaderboard scores text color - optional
options.textColor = "#ffffff";
// username link color - optional
options.linkColor = "#ffffff";
// username hover color - optional
options.hoverColor = "#3399CC";
// button color - optional
options.buttonColor = "#f29d1c";
// button text color - optional
options.buttonTextColor = "#ffffff";
// Show the widget!
Mochi.showLeaderboardWidget(options);
</script>

2.1 Overview

Site owners utilizing the popular GameSiteScript arcade can use our MochiAds GSS plugin to automatically post games to your site. Once you've installed the plugin, you can browse our game catalog and add games to your site with a single click

2.2 Prerequisites

Before you get started, make sure you have done the following:

1. You must have a working installation of GameSiteScript 3.2 or above
2. Valid 'MochiAds for Publishers' account with a verified domain

2.3 Installation Instructions

1. Install the Auto Post GameSiteScript plugin from the installation ZIP.

2. Take the plugin ZIP and extract it in to a working directory. Upload the mochiads/ directory to be a subdirectory of the plugins/ directory in your GSS installation. This will activate it as a plugin.

3. Execute the mochi-dist.sql SQL file with your database. This can be done from within GameSiteScript if required, however, it would be best to do this through phpMyAdmin or a similar SQL access interface.

4. Log in to your GameSiteScript site as an administrator, and navigate to the administration area.

5. Find the new "MochiAds" item in the sidebar, and click on it. Navigate to Configuration, and fill in your publisher ID.

6. Visit mochiads.com and go to your publisher settings (https://www.mochiads.com/pub/settings)

7. Enter the full URL of your GSS installation. (e.g. http://www.mysite.com/)