Ads - AdColony (v1.3+)

Log In To Ad Colony

Once you have signed up with Ad Colony, you can log into the user section where all the controls for your advertising are found. You can both Advertise and Publish ads with Ad Colony, but for our needs we want to Publish as we want them to send us ads for our game to show, rather than have them send ads for our game to others.

It should be noted that Ad Colony only supply fullscreen video ads and offer walls (with their own Virtual Currency which is explained further on in this tutorial) so if you want more discreet advertising this provider is not for you!

Once you have logged in you should be taken you to the following screen:


Setting Up An App

To start with you should click on the button at the bottom right of the screen marked Setup New App which will take you to a new screen. Here you must select certain options to ensure that the ads being sent to your device are correct and target the audience you want. First you should choose the device to show the ads, iOS or Android (in this article we talk about Android, but the procedure is the same for iOS):


Next you should choose a location for your app. This is used for ad targeting and normally the default "United States" value is fine, but if you are using some language other than english you may want to change this.

After that comes the name of the application that is going to receive the Ad Colony ads. Now, this doesn't have to be the name of a published app, you can simply call it "Test App" or whatever for the moment as it is used for identifying the ads group that you are setting up, but if these ads are going to a completed app, then you can put it's name here and have Ad Colony find it on the Google Play store and link it to this page.

The final thing to choose is the type of ad that you want to display. For this you are provided with an ample check-list of ad types to choose from and you should make sure that only those that are suitable for the age-group or market share you are targeting are selected or else you could end up getting negative comments for your app or having it removed from the store if the ads are not appropriate.


Once you are happy that everything is correct you can click on the green Save button which will cause the screen to refresh and now display your app key and your secret key (for general ads you will only need the app key, and for virtual currency you will need the secret key).

You can now click on the Publish button on the left of the screen to take you back to the main publishing page where you can see your newly created ad and its statistics.

Creating a Zone For Your App

When you first add an app to AdColony, you will have a zone created automatically for you. This zone is what defines the type of advert you will receive, the refresh frequency of the advert, whether you use virtual currency or not, and whether it is a test ad or not. Let's go through the options one at a time:


This section is basically for your own personal use and is where you can make the zone active or not, as well as give the zone a name and a description.


Zone Type

If you wish to use offer walls and offer Virtual Currency rewards to your users then you should the Zone Type to Value Exchange/V4VC, but for normal ads it is best left off.


House Ads

Here you can tell AdColony to send ads related to your own company or products or not.


What this means is that if you are not only publishing adverts but you are also actively advertising products, then you can have the AdColony provider show the adverts for your products instead of (or as well as) those adverts from other companies. Normally you would have this set to none but if you have decided to promote your own products in this way, then choose the option that best suits you.


The options available for AdColony deal with the frequency with which ads are served to your app:


The Session Play Cap is for limiting the number of plays of the video or offer-wall per-app. A setting of 0 means that every time you request an ad, it will be sent by the provider, and any other value will limit the ads to that number. The second value requested is the Play Frequency. This controls whether an ad will always be provided on request or not, with a higher value than 1 meaning that the ad will only be provided every ''nth'' request. In this way you can have ads only show, say, every 10 requests, or have them only show once when the game is first played etc...

It is worthwhile thinking carefully about these options and deciding how you want to use the AdColony service.... Bear in mind that their ads are video ads and so will take up the whole screen and require various seconds to finish, or have the user press a button to skip them. This can be quite annoying for the user if it is happening every time that they reset a room, or enter the main menu! So try to balance when and where you play your ads and have them integrated in the natural flow of your game.


This is for testing your apps only. You should set this to "Yes" so that your app only receives test videos until it is actually released and available on an app store.


GameMaker: Studio

With the 1.3 update of GameMaker: Studio, advertising has been taken out of the IDE and has been replaced by Extension Packages. You can get these from the YoYo Games Marketplace, or download them from the "Demos" tab of the GameMaker: Studio "Welcome" page when you start it. So, you should make sure you either have the extension package or have downloaded it from the demo feed before continuing (if you download the demo, it contains a help file which explains how to create the GMEZ extension package which you will need to continue).

Initialising AdColony

Once you have your AdColony GMEZ, you need to install it in your game, so you would right-click on the "Extensions" folder, and select "Import Extension", browsing to the place where you have the AdColony package saved. Once it has been added, you then need to set up your game to initialise the AdColony support by adding the following line of code:

AdColony_Init(AppId, ZoneId, V4VCZoneId);

This code should only be run once in your game, preferably in the game start event of the very first object. It requires the AppID (which you can get from the AdColony dashboard) and the ZoneID (which you can get by clicking the Zone from the App page of the Dashboard), and the optional argument of the V4VC ID (which you will also find clicking the Zone from the App page). if you do not use V4VC videos, you can use an empty string "" as the final argument.

Showing Ads

Once the above mentioned function has been added, showing the ads requires only a further line of code, which should be placed in the appropriate object in your game. It is recommended that you think very carefully about just where these ads should be shown as they are generally far more intrusive than banner ads and as such may annoy some users of your app if used too much, or placed in inconvenient moments. An excellent place to use them (for example) is right at the start of the game, or just after your splash screen.

The following code will show an ad if one is available (note that between initialisation and showing the ad, a few seconds should pass to give the ad time to be downloaded):


And that's it, really. Test your app a couple of times, making sure that it is network visible, either through WiFi or your device ISP, and then check the Ad Colony page for your app and you should now see the following message indicating that all is well and the app is communicating correctly:


NOTE: On Android, you must create an APK file for this to work, as test play will give errors with the extension package.

Social Asynchronous Event

When calling an interstitial ad, it will trigger a Social Asynchronous Event, which you can then use to perform extra actions. The event creates a special ds_map() and stores its ID in the constant async_load. You can then parse this map to get information about the ad being shown.When calling any ad:

Key - “shown
Value - 1 for success or 0 for failure (reals)

If "shown" is 1 for a successful showing of a V4VC video, then you will also get the following key/value pairs in the ds_map:

Key - “currname
Value – The reward name (as set in the AdColony dashboard)

Key - “curramount
Value – the reward amount (as set in the AdColony dashboard)

 If "shown" is 0 then there will be no further map entries.

Virtual Currency

The Videos For Virtual Currency feature of Ad Colony ads, is a slightly more complicated system to set up and maintain. It basically permits you to give the end-user a set quantity of of currency (tokens, points, "money" etc...) for viewing advertising videos from within the app.

NOTE: For this service to work correctly, you really need a good working knowledge of database management as well as php to create your own back-end server to deal with the ''Virtual Currency'' and user information!


The above image shows the AdColony page for a zone where you have enabled the V4VC functionality and as you can see there are a number of options available related to how you wish to handle the transactions.

  • V4VC Secret Key - This is the security hash for the Ad Colony virtual currency system and will be needed to verify the currency transaction.
  • Client Side Only - Here you can tell Ad Colony to send the reward directly to the device that is requesting it ("yes") or have it sent to a server that you have set up for your apps ("no"). By default this is set to "no" due to the fact that having your own server is a far more secure system since devices can suddenly lose connection or be switched off before the transaction is completed.
  • Callback URL - This URL is used by Ad Colony for server (or client) communication.
  • Virtual Currency Name - The name of the currency in your game, eg: token, diamonds, mana etc...
  • Daily Max per User - The maximum number of times that a user can be granted Virtual Currency. The default (and maximum) is 20.
  • Reward Amount - The amount of the chosen Virtual Currency to award the player for watching the video adverts.

For this to work correctly you must have your own back-end server set up to store individual player details as using client side payments can be problematic and less secure and so is not supported currently by GameMaker:Studio. How you set up your server is up to you, but it should store user information like login name, password, current Virtual Currency, and app details as well as use the Secret Key hash that AdColony provide for the ad zone using the system.

Ad Colony themselves will send a callback with the following example format to your server:[ID]&uid=[USER_ID]&zone=[ZONE_ID]&amount=[CURRENCY_AMOUNT]&currency=[CURRENCY_TYPE]&verifier=[HASH]

Where all the parts in the [ ] are supplied by them. Your server should be equipped to deal with this information appropriately. It is worth noting that for testing purposes you can reset the play cap for the zone by clicking the button at the bottom.

Virtual Currency In GameMaker:Studio

To set up GameMaker: Studio with the Ad Colony Virtual Currency system, you should follow the steps above for the initialising AdColony (given above) only this time supply the V4VC key in the function. 

Ideally you will want to get a user name and password for your game to store on the server you set up, so you can keep track of the virtual currency given out. How you get this id is up to you, but GameMaker: Studio does have an async login function (get_login_async) that you can use to get a username and password which can then be sent using the http_* functions to your server for verification and storage.

Once you have done that you can run your ads using the function:


this function will show a video ad as before, but the difference now is that it will also trigger a Social Asynchronous Event, where you can poll the results map and reward the player appropriately. The ds_map created in this event will always have the ID "adcolony_reward", and will contain the name of the VC reward (as defined when you created the Zone in the AdColony dashboard) as well as the amount rewarded. The async_load ds_map returns these in the keys "currname" (a string) and "curramount" (a real). The code below illustrates how this event would be structured:

var type = ds_map_find_value(async_load, "type");
if (type == "adcolony_reward")
    var name = ds_map_find_value(async_load, "currname");
    var amount = ds_map_find_value(async_load, "curramount");
        case "item": global.items += amount; break;
        case "gold": global.coins += amount; break;

Further Information

For further information on AdColony as well as documentation relating to their services and the SDK used by GameMaker: Studio please use the following links:

Have more questions? Submit a request


Article is closed for comments.