1.1 Overview

The Mochi Coins API provides an easy way to sell game upgrades like level unlocks, equipment, special weapons and cheats to players. It also provides secure login and server side persistence of player data to store game state and user data no matter where the game is played.

1.2 Prerequisites

MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.

Installing the Coins API

1. Download and unzip the latest MochiAPI.
2. Copy the “mochi” folder and paste it into the root classpath of your game. Most often this is the same as the location of your game’s FLA file.
3. Create your store and add items in your Mochi Developer account.

1.3 Connecting to MochiServices

1.4 Showing the Login Widget.

The Login Widget allows the player to register or login and gives them access to their items and coins. If the player has previously logged in, the widget will show their profile picture, items, and coins. The Login Widget is 200x25 in size, and will automatically place itself on the lower right corner of your stage. We recommend this placement for consistency between all Coins enabled games, however you may pass in a custom position for your specific design.

import mochi.as3.*;

MochiCoins.showLoginWidget(); // You can also pass a x,y - MochiCoins.showLoginWidget({x:330, y:360})

You can hide the Login Widget with the code below. The widget will still be loaded to keep state but won't be visible.

MochiCoins.hideLoginWidget();

1.5 Listening to Events.

Once a player has logged in, you will get a LOGGED_IN event followed by ITEM_OWNED events for each item the player owns. If the player previously logged in and has a valid session, this may happen quickly after the MochiServices.connect() call, so listeners should be enabled for these events before your MochiServices.connect() call. When players purchase an item, the ITEM_NEW event will happen, allowing you to register the item for your game.

import mochi.as3.*; // import mochi.as2.* if using the AS2 API

    MochiCoins.addEventListener(MochiCoins.ERROR, handleError);
    MochiCoins.addEventListener(MochiCoins.LOGGED_IN, loggedIn);
    MochiCoins.addEventListener(MochiCoins.ITEM_OWNED, registerItem);
    MochiCoins.addEventListener(MochiCoins.ITEM_NEW, newItem);

    MochiServices.connect("xxx", root, onError);

    public function loggedIn(event:Object):void {
        // receive {name: name, uid: uid, profileImgURL: profileImgURL, hasCoins: True, userProperties: { hitPoints: 120 }}
        trace("Hello " + event.name);
    }

    public function registerItem(event:Object):void {
        // receive {id: id, count: count}
        trace("Player owns " + event.count + " of " + event.id);
    }

    public function newItem(event:Object):void {
        // receive {id: id, count: count}
        trace("Player just bought " + event.count + " of " + event.id);
    }
    

It should be noted that the parameter dispatched with an event is an Object, and not a decedent of the Event class. While Objects behave in a similar fashion as an Event object, they do not contain the same parameters and properties as a built-in AS3 Event. Likewise, you will not be able to use instanceof, is, as and typeof to determine what kind of event has been passed.

1.6 Showing the store.

Use MochiCoins.showStore() to show your store with two or more items. You may pass an optional tags array to show a subset of the items in your store that match the tags defined in your items in your Mochi Developer account. The tags array can also have specific itemIds specified as each item is already implicitly tagged with its itemId. The example below shows all items with the "weapons" tag as well as a specific itemId. No x,y coordinates are passed as the store should fill the stage.

MochiCoins.showStore({ tags: ["weapons", "c27d0672bf98ec05"] });

1.7 Showing a single item.

Use MochiCoins.showItem() to show a modal dialog offering a single item. Pass the item identifier listed for your item in your Mochi Developer account. The dialog will center itself on the stage but you may also pass x,y coordinates.

MochiCoins.showItem({item: "xxx"}); // You can also pass a x,y - MochiCoins.showItem({x:330, y:360, item: "xxx"})

1.8 Showing an item demonstration video.

Use MochiCoins.showVideo() to show a modal dialog displaying the demonstration video associated with an item. The call will be ignored if the item ID is invalid, or there is no video associated with the specified item.

MochiCoins.showVideo({item: "xxx"});

1.9 Saving persistent player properties.

The MochiCoins API will allow you to save persistent player properties. This can be used to save any custom player state that can be retrieved on subsequent gameplays. As an example, you may wish to save the state of health, experience, or the number of levels unlocked for the player which can provide a more continuous game play experience when the user returns to the game at a later time. The example below will save the key value pairs specified for the logged in player. Only values of types Number, String, Boolean, and Array can be saved. There is currently a 4KB limit (total serialized size) per user per game that can be saved.

MochiCoins.saveUserProperties({ hitPoints: 120, levelsFinished: [1, 2, 4, 6] });

The above call will overwrite the previous properties Object that may have existed for the player. On subsequent MochiCoins.LOGGED_IN events, this object will be passed back.

                        MochiCoins.addEventListener(MochiCoins.LOGGED_IN, loggedIn);

                        public function loggedIn(ev:Object):void {
                            // receive {name: name, uid: uid, profileImgURL: profileImgURL, hasCoins: True, userProperties: { hitPoints: 120 .. }}
                            var userProperties:Object = ev.userProperties
                        }
                                                

MochiCoins.PROPERTIES_SAVED event will occur when the properties Object save is successful. MochiCoins.ERROR of type MochiCoins.PROPERTIES_SIZE or of type MochiCoins.NO_USER will occur when the size of the properties Object is too large, or no user is logged in. See 2.0 Event definitions.

                        MochiCoins.addEventListener(MochiCoins.PROPERTIES_SAVED, properties_saved);
                        MochiCoins.addEventListener(MochiCoins.ERROR, handleError);

                        public function properties_saved(ev:Object):void {
                            trace("Properties Saved!");
                        }
                        public function handleError(ev:Object):void {
                            switch (ev.type) {
                                case MochiCoins.PROPERTIES_SIZE:
                                    trace("Properties too large.");
                                    break;
                                case MochiCoins.NO_USER:
                                    trace("No user logged in.");
                                    break;
                            }
                        }
                                                

1.10 API

1.1 Prerequisites:

MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.

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

1. Sign up for a Mochi Developer account on www.mochimedia.com
2. Log in and add a new game to your account.
3. Download the MochiAPI include ZIP package.
4. Choose your code options and copy the Mochi Ads API in-game code.

1.2 The Mochi API Ad Codes:

You need two things for Mochi Ads API to work properly in your game -- The mochi include folder, and the in-game code.

The include folder contains the ActionScript code that your game will reference to display your ad. You will never need to edit this code. You just need to make sure that it is in the proper location so that it is imported or included when you publish or compile your game. You only need to do this once for each game, no matter how many ads you show in the game.

The in-game code is the code you paste into your game to display the ad at a specific point in the game. This may be placed in a specific frame on the main timeline of your movie, or called when a specific event is called in your game code. Depending on how you created your game, where you place this code will differ. Just remember, when you make the call to the Mochi Ads API, that's when the ad will show.

Include Folder Installation:

The MochiAPI ZIP package contains the include code necessary for your game. UnZIP the package to a location on your hard drive. If you browse to that location, you will see a group of folders (fig.a).

Make sure to read the README.TXT file for information regarding the latest release of the MochiAPI file include.

Each folder in the package corresponds to a particular coding environment. It's up to you to choose which one is best for you:

• docs: MochiAPI usage documentation.
• examples: Examples using MochiAPI.
• mochi: MochiAPI include folder.

Simply copy the mochi folder and paste it into the location where you are publishing your game. You do not need to create a special folder for the include (fig.b).

These instructions also apply to the examples. Simply copy the mochi folder into the example project direct that you wish to use, and publish to test.

Adding the In-game Code:

The in-game code is a one-line code snippet that you copy from the Mochi Developer web site. This code is a method call that tells MochiAPI to launch your ad. You will paste this code into your game in the place where you want the ad to appear. Your code looks something like this:

mochi.as2.MochiAd.showPreGameAd({id:"xxxxxxxxxxxxxxxx", res:"360x240"});

NOTE: In the 3.0 revision of the API, we changed namespaces for our libraries to unify and organize our packages. Now you must explicitly call the API corresponding to your ActionScript version: mochi.as2.* or mochi.as3.* respectively. For the purposes of this documentation we will show examples specifying the ActionScript 2.0 MochiAPI. Simply remove mochi.as2. from the code samples, and add import mochi.as3.*; to the beginning of your code block to use the ActionScript 3.0 MochiAPI.

There are three types of ads you can place in your game -- a pre-game ad, an inter-level ad and a Click-away ad. Pre-game ads include a preloader bar that grows as your game file is loaded from the web to the player's computer. An inter-level ad is an ad that appears at some point during game-play. The most convenient and unobtrusive time to show ads is usually between game levels, hence the name inter-level ad. Click-away ads are 300x250 ads that can be placed anywhere you specify and will only disappear on a user-initiated action.

You can use the Mochi Developer web site to customize your code for the particular type of ad and version of ActionScript you need.

ACTIONSCRIPT 3 NOTE: ActionScript 3 developers will also notice that there is an additional parameter named clip which passes a reference to the DisplayObject container for your ad to appear. This is required, and by default this is set to root for pre-game and inter-level ads. See below for more info regarding customizing this parameter.

Pre-game Ad:

To add a pre-game ad with a preloader to your game, simply get the appropriate in-game code from the Mochi Developer web site, and paste it into the main timeline of your movie, in the place you've designated for a preloader (fig.c).

If your game is ready, you can test your movie, and you should see the pre-game ad appear as your movie loads. You may test your ads as much as you like while you develop your game. Keep in mind that your ads will not earn money until you complete your game profile which includes a URL to the completed game. You may also upload your SWF file from the Game Settings page for free hosting.

Inter-level Ad

To add an inter-level ad to your game, simply get the appropriate code from the Mochi Developer web site, and paste it into the main timeline of your movie, in the place you've designated for your inter-level screen (fig.d).

Just like the pre-game ad, you can test your game and see the inter-level ads in action.

Click-away ad

To add a Click-away ad to your game, simply get the appropriate code from the Mochi Developer web site. Pass in the DisplayObject container / MovieClip which will contain the Click-away ad in the clip parameter. The upper left corner of the 300x250 Click-away ad will be placed at the upper left corner of the DisplayObject container / MovieClip you specify. When you wish to stop displaying the Click-away ad pass your clip to MochiAd.unload() depending on your respective ActionScript version publish settings.

Flash Player Security Settings:

If you are testing locally outside of the Flash authoring environment and want to be able to see ads, you will need to change the default local playback security settings. In Flash, go to "File -> Publish Settings," then click on the "Flash" tab. At the bottom, under "Local Playback Security", choose "Access network only" and then publish again. Keep in mind that if you are loading any local data that it will no longer be accessible until you change your settings back to "Access local files only." These settings will not affect playback on the web.

Alternatively, you may wish to add the location of your development files to your global security settings in the Adobe Flash Player Settings Manager. This way, you can give all SWF files in this location local-trusted access, allowing access to both local and remote data.

You will not need to do this if you are only testing your games in the Flash authoring environment, although you will see Sandbox Violation warnings in the Output panel. Warnings pertaining to MochiAPI can be safely ignored.

Alternate In-game Code Placement

Since there are many different ways to architect Flash games, it is very likely that your game development setup is not the same as what you see above. You may have nested MovieClips, or perhaps you are not using the timeline at all. It is possible to place your in-game code in the timeline of a MovieClip as well, and it will execute when the frame where you placed the code is reached.

And You're Done!

That's all that is required to get MochiAPI Ads running in your game. When you've completed your game and released it to the world, be sure to complete your profile so that your game can be approved and you can start earning money right away!

1.3 Customizing Your Ad

It is possible to customize many of the visual elements and behaviors of your Mochi Ads. The Mochi Ads API in-game code allows you to simply tailor the display to suit your needs. Here's some of the things you can tweak:

• MovieClip container: You can place your ad into any MovieClip on the stage, or into MovieClips you create with Actionscript.
• Timing: You can customize fade time of your ads.
• Colors: Change the colors of the ad preloader bar, background and outline. You can also turn off the solid background.
• Event Handlers: You can assign custom functions to be called when ads start, load, and end.

The Mochi Ads API

Your ads can be customized by sending special parameters via your in-game code. Depending on whether you've chosen to display a pre-game or inter-level ad, your options will be slightly different.

The in-game code is passed an object with keys and values to pass to the server. The default code contains two keys -- id, the unique Mochi game ID, and res, the height x width of your game. These parameters are required.

mochi.as2.MochiAd.showPreGameAd({id:"xxxxxxxxxxxxxxxx", res:"360x240"});

You may add more key: value pairs to the object by separating them with commas. You may add the following optional parameters to your object:

• clip:MovieClip - a MovieClip reference in which to place the ad. Required for click-away ads or if you're using Actionscript 3.0. Otherwise the default is _root. (default: _root)
• no_bg:Boolean - setting to true allows you to disable the background entirely. (default: false)

The following additional options apply to pre-game ads only:

• color:Number - the color of the preloader bar as a number. (default: 0xFF8A00)
• background:Number - the inside color of the preloader bar as a number. (default: 0xFFFFC9)
• outline:Number - the outline color of the preloader bar as a number. (default: 0xD58B3C)
• no_progress_bar:Boolean - setting to true allows you to disable the preload progress bar. (default: false)

You can find out the width and height of your ad when it loads. You can use this information to create a custom frame around your ad that matches your game.

• ad_loaded:Function - ad_loaded is called just before an ad is displayed with the width and height of the ad. (default: function(width:Number, height:Number):Void { }).

You can also find out the progress of the preloader bar. You can use this information to create your own preloader bar when used with the no_progress_bar option.

• ad_progress:Function - ad_progress is called with the progress of the preloader bar. The progress is a percent (represented from 0 to 100). (default: function(percent:Number):Void { }).

Here is an example of how the code might look if you were to add more options:

mochi.as2.MochiAd.showPreGameAd({id:"xxxxxxxxxxxxxxxx", res:"360x240", clip: _root.myClip, no_bg: true, color: 0x006699, outline: 0xFFFFFF});

If you need to add many options, or define functions to handle ad events, you may consider creating an object first, and then referencing that object when you call the Mochi Ads API.

var myOptions:Object = {
    id: "xxxxxxxxxxxxxxxx",
    res: "360x240",
    clip: _root.myClip,
    color: 0x006699,
    background: 0x333333,
    outline: 0xFFFFFF,
    ad_loaded: function (width, height) { trace("ad loaded: " + width + "x" + height); }
    ad_progress: function (percent) { trace("preloader percent: " + percent); }
}
mochi.as2.MochiAd.showPreGameAd({myOptions});

There is also a tool on the Mochi Developer web site to customize the appearance of your ad when you set up your in-game code. Often, this is easier than editing the code by hand.

1.4 Changing Ad Behaviors

The Mochi Ads API described above also allows you to assign your own event handlers to be called by your ad. There are six events:

• ad_started:Function - a function to call when the ad has started playing. (default: function ():Void { this.clip.stop() })
• ad_loaded:Function - a function to call just before an ad is displayed with the width and height of the ad. If it is called, it is called after ad_started. (default: function(width:Number, height:Number):Void { }).
• ad_finished:Function - a function to call when the ad has finished playing. (default: function ():Void { this.clip.play() })
• ad_failed:Function - a function to call if an ad can not be displayed, this is usually due to the user having ad blocking software installed or issues with retrieving the ad over the network. If it is called, then it is called before ad_finished. (default: function ():Void { })
• ad_skipped:Function - a function to call if the ad was skipped, this is usually due to frequency capping, or developer initiated domain filtering. If it is called, then it is called before ad_finished. (default: function ():Void { })
• ad_progress:Function - a function to call when the progress of the preloader bar has changed. The progress is a percent (represented from 0 to 100). (default: function(percent:Number):Void { }).

When you assign custom functions to ad_started and ad_finished in your options object, your ad will no longer stop and play the timeline. Instead, your custom functions will be called.

var myOptions:Object = {
    id: "xxxxxxxxxxxxxxxx",
    res: "360x240",
    clip: _root.myClip,
    ad_started: function ():Void { _global.game.pause(); },
    ad_finished: function ():Void { _global.game.resume(); }
}
mochi.as2.MochiAd.showPreGameAd({myOptions});

It is best to explicitly pass a function literal in your options object instead of referencing a function in a separate class. That way, you do not need to worry about losing scope or relying on the Delegate class. If you are using ActionScript 3, though, you can pass a reference to your function without losing scope.

Keep in mind that, if you define custom ad_started or ad_finished event handlers, your timeline will no longer be stopped during the playback of your ad. So, if you still wish to stop your timeline, you will need to be sure your event handler does this.

1.5 MTASC and MXMLC

For those developers who are developing in environments that don't use the Flash IDE, the process for adding the Mochi Ads API will be slightly different. In order to get your ads functioning in your game, you will need to:

1. Make sure that the mochi folder is in your root project classpath.
2. You've added the in-game code in a method that is executed in an instantiated class in your game.

1.6 Adobe Flex

To use the Mochi Ads API as an Adobe Flex application's preloader, you will need to:

1. Make sure that you use the MochiPreloader.as from the examples/flex folder from the MochiAPI ZIP package.
2. Make sure that the mochi folder and MochiPreloader.as are in your project classpath.
3. Tell your MXML application the preloader you want to use:

   <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" preloader="MochiPreloader">
   </mx:Application>

4. NOTE: With inter-level ads, the Mochi API is unable to tell your game when it has finished via the MovieClip.stop() and MovieClip.start() methods. You must use the ad_started and ad_finished callback methods in your game's options object (described in Section 1.4) to be notified when to start and stop your game.

1.7 ActionScript 3.0 Preloader

The mxmlc folder includes a preloader class (Preloader.as) that provides an example of how to properly compile a preloader into an AS3 SWF compiled with Adobe Flex mxmlc compiler. For the preloader to function correctly, it must load first and execute before your base class and other SWF assets load. In order for this to happen, the Preloader class is included on the first frame of your SWF and all of the other assets are included on the next frame. The Preloader class contains a weak reference to your document class that it uses to instantiate your class after it completely loads your game.

// Change this class name to your main class
public static var MAIN_CLASS:String = "Test";

For Flex Builder, there is a makefile included in the example which tells the mxmlc compiler to include your Document Class in the second "frame" of your SWF so that the preloader will load first:

mxmlc \
               -default-frame-rate 31 \
               -default-size 550 400 \
               -use-network \
               -optimize=true \
               -output $@ \
               -frame=Test,Test \
               Preloader.as

Notice the compiler option '-frame=Test,Test'.

If you are using FlashDevelop, you need to make sure you're passing "-frame Test, Test" to the mxmlc compiler, which you can set under Compiler Options in Project Properties. Don't forget to change 'Test' to the actual name of your base class.

1.8 Flash Develop

Our example uses the AS3 Empty Project Template as it's basis. Using our API within this framework is no more difficult than that of a standard Flash IDE project. Simply copy the mochi folder into the src folder created for your project. After you have done this, it is simply a matter of using that standard API calls

1.9 More Resources

If you have questions about using the Mochi Ads API, you can view our FAQs or visit the support forums for help. Also, if you have suggestions regarding this help document, we encourage your feedback.

1.1 Overview

MochiServices is all Mochi APIs except for the Mochi Ads API. The API is dynamically loaded from Mochi servers and must be initialized in either the first frame of your game or during Document Class initialization.

1.2 Prerequisites

MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.

Installing the Mochi Scores API

1. Download and unzip the latest MochiAPI.
2. Copy the “mochi” folder and paste it into the root classpath of your game. Most often this is the same as the location of your game’s FLA file.

NOTE: In the 3.0 revision of the API, we changed namespaces for our libraries to unify and organize our packages. Now you must explicitly call the MochiAPI that is specific version: mochi.as2.* or mochi.as3.* respectively. For the purposes of this documentation we will show examples specifying the ActionScript 2.0 API. Simply change mochi.as2. from the code samples, and add import mochi.as3.*; to the beginning of your code block to use the ActionScript 3.0 API.

1.3 Connecting to MochiServices

Leaderboards

MochiDigits

Link Tracking API Documentation

1.1 Overview

Our version control and encryption technology enables you to create a special version of your SWF which can be updated at any time and contains an extra layer of encryption to protect against decompiling.

Benefits of Mochi Live Updates

• Update anything about your game, at any time. The updated version will be instantly available to players around the world.
• The game does not require Mochi servers to be played – Your file is completely stand alone.
• Your game can be played offline as well as online – Offline players simply get the original packaged version
• Increased encryption and protection from decompiling.
• Downloading the new updates are quick and transparent, players only need the differences between versions.

Live Updates works great for

• Fixing those nasty bugs that crop up after your game is released.
• Recently changed your logo? No problem, upload a new version with a new splash screen.
• Made a hot new sequel to your game? Add in a link and screenshot pointing users to the sequel to generate awareness and traffic.
• Sell a timed sponsorship to someone for a fixed period of time. Simply upload the new version with their links and splash screen and revert to the old version when you're done.

How it works

Live Updates games play just like any other game to the user. However behind the scenes when the game is first loaded it checks with Mochi servers to see if there is a new version available. If so, the game will be patched while during the loading process (it only sends minimum differences, so it doesn’t have to download the whole game over again).

1.2 General Installation

Adding a new game

1. Click on 'add game' like normal to add a game to the Mochi service.
2. Check the box 'Use Live Updates' to enable the feature.
3. Add a verification code to your game - this ensures you have access to the source code.
4. Upload your game, a pre-loader is automatically added so you don't have to include any ad-code for a pre-loader. Other in-game ad formats are ok.

Updating your game

1. Click on your game from your developer dashboard.
2. Click on the 'game settings' link
3. Under the 'game files' section, click on 'upload new version'.
4. Select 'use Live Updates' for the new game version.
5. Follow the on-screen instructions and upload your new version.

That's it!

Distribute your new version anywhere you like! If at any time you want to change your game, visit your game settings tab and upload the new version. Within minutes players will be enjoying your new awesomeness.

1.3 Test Your Game For Compatibility

The Live Updates service embeds games into an AS3 loader SWF. The Flash Player treats games differently when loaded this way than when loaded by either through an HTML page or directly into a browser.

To test for compatibility, loading your game using the LoaderTest utility to see if you can reproduce the problem. LoaderTest uses the same underlying Flash features that the encryption and version control tool's loader SWF uses. If the problems are still present when using LoaderTest, then you will need to make changes to your game. If the problems are not present, then notify us, and we will investigate the problem.

1.4 Preparing AS3 games

AS3 display list membership

Adobe’s Flash Player treats AS3 SWFs loaded into another AS3 SWF differently than when it’s loaded directly by the browser. In particular, the main object is not added to the display list until after the constructor is called whereas when loaded directly the main object is already attached to the display list. This results in the stage and parent properties being set to ‘null’ (and likely resulting in null object references).

This can usually be worked around by moving any code that needs to interact with the stage being moved to an event listener. Event.ENTER_FRAME, Event.INIT, or Event.ADDED_TO_STAGE events are good candidates for this.

AS3 LoaderInfo, third party APIs

Since Live Updates loads your code with a flash.display.Loader, the FlashVars and URL should be accessed somewhat differently than normal. Some third party APIs may need small changes to use this LoaderInfo instead of root.loaderInfo. This code will get the true LoaderInfo in a game using Live Updates (but also works if not using Live Updates):

    public function getMainLoaderInfo():LoaderInfo {
        var loaderInfo:LoaderInfo = root.loaderInfo;
        if (loaderInfo.loader != null) {
            loaderInfo = loaderInfo.loader.loaderInfo;
        }
        return loaderInfo;
    }

1.5 Preparing AS2 games

1.6 Preparing AS1 games

Case-sensitivity: Users have reported that AS1 games loaded into AVM1Movie are suddenly case sensitive, whereas normally they are case-insensitive.

1.7 Third Party APIs written in AS2

Usually these APIs work by cross-scripting a SWF to inject new code into AS2 games. However, Flash does not support cross-scripting between AS2 and AS3, and the version control and encryption loader SWF uses AS3, preventing the API from being injected correctly.

NOTE: LocalConnection APIs will still work, but sites may not provide these for AS2.