Ads - mMedia (v1.3+)

This page takes you through the setup procedure for mMedia support for the Android and iOS target modules.

mMedia

Signing up and getting started with mMedia is an exceptionally simple process. Just fill out the information they request, selecting "Developer" and either "Monetize" or "Monetize and promote", and then click the "Register" button. A verification link that they send to you by e-mail which must use before you can start using their services. You can then log in to the mMedia dashboard, where you will be greeted by the following message:

This is just a way to get started as quick as possible and sets the default startup screen for your dashboard. Since we are interested in receiving advertising for our games, you should click the Monetizing button then get Started. You will probably see the a message something like the following: "To start making money with us you need to complete your payment info and add your applications", so before actually you can start to add an app to their services, you should fill out your payment details.

Payment Information

If you move your mouse over your profile name (top right of the page) a pop-up menu will appear that has the following options:

• General Info
• Payment Info
• Password

You should go through the necessary steps for each of these sections and fill in the relevant information, making sure that you have your bank accounts IBAN and Swift Codes for the payment details, and if you are registering in the United States you will also need your Taxpayer Identification Number.

When you have finished, click on the Monetize button to take you back to your Dashboard.

Adding An App

Your dashboard will display that you have no apps currently generating revenue, so click on the "Apps and Sites" tab, which will take you to a new section with an Add An App button. Click this now to start the process of adding your app to the network.

You will then be presented with the following screen that requests details about your app and the platform that you wish to host it on:

Currently the GameMaker: Studio extension packages only cover iOS and Android, so you should select one of those platforms only.

The obligatory fields are marked with an (*) and should be filled in for your app submission to be successful, while the rest can be left for later if you are still testing or have not yet finished preparing the necessary media. Also note that the Description field has a maximum character limit of 250 so keep your descriptions concise!

Finally, you should give this first ad placement an identifying name and choose the type of ad that you wish to show from the five options presented. When you are finished and happy that the information is correct, click on the Save button to continue.

You will then be shown a message giving instructions for integrating their SDK. This is not necessary so you can click the "Done" button at the bottom of the page to continue.

As you can see, you will need to wait a few hours before your app can properly test ads, but we can spend that time reviewing the rest of the mMedia Dashboard and setting up our game in GameMaker:Studio correctly. 

Apps And Sites

The Apps and Sites tab is where you can review all the information on the apps that you currently have active (or pending review) with mMedia, selecting each app from the column on the left. This overview includes a series of icons across the top of the screen to show what type of ads have been configured for the app, and two buttons to either Edit or Remove the app information. There is also a tab for Test devices which we shall look at a bit more further on.

At the bottom of the screen you can see a more detailed list of all the ads you have active for the selected app, along with a button marked Placements. Clicking on this will permit you to add another ad placement to your app, which in turn will give you another APID, unique to that ad. You will need to note these APID for use in GameMaker:Studio as these will be needed to configure the ad in the Global Games Settings.

You can also disable these ads using the button marked Status, change their name by clicking the main placement field, and some ads may have extra options in the column marked Enable which will give you extra options - for example with interstitial ads, permit you to choose video ads, image only ads, or both.

Ads

The Ads tab permits you to configure the ad suppliers that will be used by your apps and it also permits you to add in special client supplied ads as well as your own custom house ads. Initially, you would leave this "as is" but if you are working with a sponsor then you may need to configure the Client Ads with their information. You may also wish to have ads that point to your own apps, known as House Ads, too and mMedia permits this from the appropriate tab. It is worth noting that while mMedia do not charge you for this service, you do not get any money from them either!

If you choose to use House ads or Client ads, these will now be listed along with the other servers on the main Ads tab, and you can use the visible sliders to change the amount of network time each different provider gets. For example, you can make 10% of all your ads be House ads and so promote your own products while still maintaining an income stream from general ads.

Reports

The reports screen gives you a detailed view of how your apps are performing. You can select the app from the left of the screen, then select the individual ad placements to review how they are doing, with extra options available to show the performance over time, or geographical information. You can also select the type of ad to look at (house ads, client ads, etc...) and even have the possibility to export the information as an Excel or CSV file for integration into spreadsheets.

Although this section isn't initially the most important of the mMedia tools, over time it is an excellent resource and permits you to see which ads get the best responses and so target your placements better.

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 mMedia

Once you have your MMedia 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 MMedia package saved. Once it has been added, you then need to set up your game to initialise the MMedia support by adding the following line of code:

MMedia_Init(InterstitialID);

This code should only be run once in your game, preferably in the game start event of the very first object. You need to supply the ID argument for the interstitial ad that you have set up, or an empty string "" if you are not using them. This ID value can be found by going to "Apps and Sites", then clicking on the app from the list on the left. You will be presented with a page for your app, and at the bottom are listed the placements you have created along with their unique APID:

Showing Banner Ads

Once the above mentioned function has been added, showing the ads requires only a few lines of code, which should be placed in the appropriate object in your game.

For banner ads, you need to call:

MMedia_AddBanner(BannerID, sizeType);

The banner ID is found from the mMedia publisher dashboard (shown above for interstitials) and the function will add a banner ad to your game. You can also place the ads when you create them using the function:

MMedia_AddBannerAt(BannerID, sizeType, x, y)

The "sizeType" argument refers to the type of banner ad that your dashboard has been set up to show and is covered in the extension package by using the following constants:

• MMedia_Banner
• MMedia_Rectangle

So, your final code for creating a banner will look something like this:

MMedia_AddBannerAt("589690", MMedia_Banner, 0, 0);

When calling a banner ad, it will trigger the Social Asynchronous Event, where you can get information about the ad being shown (see below for more details).

Show Interstitial Ads

For interstitial ads, you must first load them before they can be shown, so you should use:

MMedia_LoadInterstitial();

to load it (and have supplied a valid ad ID string in the "init" function given above), and then a few seconds later check to see if it has loaded before showing it, like this:

if MMedia_InterstitialStatus() == "Ready"
{
MMedia_ShowInterstitial();
}

So, you would have an instance that loads an ad in it's create event, then you could use an alarm with the above code to poll the result and only show the ad when it is loaded (for example).

It is recommended that you think very carefully about just where interstitial 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.

Social Asynchronous Event

When calling a banner or interstitial ad, it will trigger a Social Asynchronous Event, which you can then use to perform extra actions (like placing a banner ad in a different position). 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 - “type”
Values - “banner_load”, “interstitial_load”

The ds_map will have the key “type” which will then hold (as a string) either “banner_load”, or “interstitial_load”.

If the type is “banner_load” then the following key/value pairs will be returned:

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

Key - “width” (width in display pixels)
Value - “height” (height in display pixels)

If the type is “banner_load” then the following key/value pair will be returned:

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

An example code of the asynchronous event would look something like this:

var ident = ds_map_find_value(async_load, "type" );
var loaded = ds_map_find_value(async_load, "loaded");
if ident == "banner_load"
{
 if loaded
    {
    var bw = ds_map_find_value(async_load, "width");
    var bh = ds_map_find_value(async_load, "height");
    var px = (display_get_width() - bw)/2;
    var py = (display_get_height() - bh)/2;
    MMedia_MoveBanner(px, py);
    }
}
else if ident == "interstitial_load"
{
global.interLoading = false; 
}

Test Devices

If you wish to receive test ads on your device (recommended when testing so as not to generate fraudulent click-through) you will need to first configure the mMedia Test Devices tab.

For Android devices, you must first run your game (by creating an APK, not by testing) with ads enabled, taking note of the ADB output as there you will find the following:

That rather large code underneath the line Millennial Device Id, is what you need to input into the Device ID field of the Add Device form (on the left) along with an identifying name for the device. You can get this information easier if you right-click the command line window and select all, then press <ENTER> and paste the contents of the clipboard into a notepad *.txt file. Then it's simply a question of finding the appropriate lines and copying them into the correct field of the mMedia form page.

For iOS devices, the code can be found in a similar way by checking the console output from iphone via the iPhone Configuration Utility, or in Xcode.

Once finished, click the (+)Device button to complete the process. If you have several devices that you wish to test on you can continue and add them in too, but you will need to connect each one to GameMaker:Studio and run them once each to get the unique device id that mMedia requests.

When this has been completed you will recieve test ads instead of live ads whenever you run ads from this device. Note that you can switch this function off by simply clicking on the Status button for the individual devices.

Further Information

For further information on the mMedia network of services please consult the following pages:

• mMedia
• mMedia Support Center