This page takes you through the setup procedure for MoPub support for the Android and iOS target modules.
MoPub Overview
MoPub are another option to consider when adding advertising into your iOS or Android app, however it is worth noting that unlike other ad companies which are integrated within the GameMaker:Studio IDE, MoPub ''do not serve adverts'', at least not in the same way as other publishers. They are primarily a mediator for other ad networks, meaning that you should have accounts with other ad providers like AdMob, iAds, or Millennial Media before starting with MoPub.
Once setup, MoPub will pull adverts from all these providers and show them depending on the world zone your app is being used in and the parameters that you have set from the main MoPub dashboard, therefore keeping your fill-rate as high as possible. You can also offer up space on your app for adverts from the MoPub Marketplace, which is where third-party developers can bid on your app for advertising.
NOTE: When using MoPub, make sure your browser has no ad-blocker technology active! This will prevent many of the graphs, buttons and functions of the page from loading.
Getting Started
Once you have signed up for a MoPub account, the first thing you will be presented with is a page to set up your first app ad unit. However it is recommended that you skip this section for now and continue with your account setup as once you have done that you can forget about it. So, click on the login name at the top of the page, and select General Settings from the menu that appears.
You will be taken to a screen showing the information that you supplied when you signed up (which you can edit now if you like too), and beneath that is a section for payment information. Click the Edit button and you will be taken to the accounts screen where you should fill in the appropriate details.
This form is very straightforward, asking you to supply the country you live in and your tax details, as well as offering you the option to use PayPal or Wire Transfer for payment. As with all ad providers it is recommended that you use the Wire transfer option as Paypal can sometimes give problems and will also charge you on every transfer.
Adding An App
The first time that you click on the Dashboard button at the top of the MoPub screen, you will be taken to the main App Details page where you are prompted to add an application and then create an ad unit for it.
Here you can select either iOS or Android, then go ahead and add the name of your app (and, if it is already published, you can have MoPub search the app store for it). For iOS you have the extra option of supplying the iTunes URL, and for Android the package name (in reverse URL format), and then you should select a category and a subcategory for you app, as well as ad an Icon to help identify it.
Once that has been done, you should scroll down the page and set up the first ad unit for the app profile that you are creating...
Creating An Ad Unit
Beneath the section for adding your app the first time you setup up MoPub you will be presented with a section for defining an ad unit.
Creating an ad unit involves nothing more than choosing a size and giving your ad unit a name and a description. You may also wish to change the refresh rate which defaults at 60 seconds, but it's not really necessary.
Once you have completed this you can click on the Continue button to go on to the Code integration page, where you will be shown the app id (which is what will be used by GameMaker:Studio). You can click on the Continue button again from here as you need do nothing more and you will be taken to your Dashboard.
MoPub Dashboard
The MoPub Dashboard will look something like this now:
and every time you login this will be your first stop. From here you can configure further ad units, add new apps and see the general performance of those that you have active. However, at this point, if you have just started, you are going to have to set up some source streams for your ad units, so you should now go to the Network button at the top of the screen and add in the networks that you want MoPub to mediate.
NOTE: You will need to have prepared the app on the other ad network sites and have the app id that each of the other networks has assigned you for this integration to work correctly.
The other ad source for your ads is from the Marketplace. This is where companies can bid for space on your app to show their adverts and is an excellent way to maintain the fill rate for your ad units. MoPub configure a MoPub Marketplace ad stream for you by default and it is recommended that you use it without changing anything. However it is worthwhile studying the pages related to the marketplace and reading the help pages associated so that you know who it all comes together should you wish to change anything.
Configuring Your Ads
From the Inventory page of the dashboard, you can click on any of the ad units that you have created and you will be taken to their individual configurations page. It is here that you can choose what ad sources to enable or disable as well as recover the add id should you need it.
To enable (or disable) an ad source for your unit, you need to click on it from the list at the bottom of the screen, which will take you to a new page showing the source and the ad units that use it. On the right of the list is the enable/disable checkbox so you can switch off individual sources for different apps and ad units.
Back on the page of your ad unit, you will also see that there is a button marked Test Ad. you can click this and a new window will open to show you how the current ad streams work and the resulting ad that will be shown on your device. This service can be a bit picky and so you may need to refresh a few times before it works (and make sure your browser has no adblock enabled!).
It is worth noting here that for testing, you want to make sure that the only ad source enabled to start with is the one labelled MoPub Demo Order > MoPub Demo Line Item (this be archived or paused at a later date).
Once you are familiar with the ins and outs of the MoPub dashboard and have set up the ad unit(s) for your game, you should click on the button labelled Code Integration and copy the Ad Unit Id from the top of the page as you will now need it in GameMaker:Studio.
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 MoPub
Once you have your MoPub 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 MoPub package saved. Once it has been added, you then need to set up your game to initialise the MoPub support by adding the following line of code:
MoPub_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 an interstitial ID to show (or an empty string "" if you are not using them). This ID value can be found by clicking the "Code Integration" button from the Ad Unit Details page, and should be added as strings, eg: "agltb3B1Yi1pbmNyDQsSBFNpdGUYneC1Fgw".
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:
MoPub_AddBanner(BannerID);
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:
MoPub_AddBannerAt(BannerID, x, y)
So, your final code for creating a banner will look something like this:
MoPub_AddBannerAt("agltb3B1Yi1pbmNyDQsSBFNpdGUYneC1Fgw", 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:
MoPub_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 MoPub_InterstitialStatus() == "Ready"
{
MoPub_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;
MoPub_MoveBanner(px, py);
}
}
else if ident == "interstitial_load"
{
global.interLoading = false;
}
Further Information
For further information on MoPub as well as documentation relating to their services and the SDK used by GameMaker: Studio please use the following links: