iOS and Android: Google Mobile Ads Setup

While Google is primarily directed towards supporting their Android platform, they do provide the AdMob platform to deliver advertising to both Android and iOS. In this article we will take you through the steps required to set up your game on the AdMob dashboard, as well as prepare it in GameMaker Studio 2 so that ads will be shown when the final game is played by users.

NOTE: If you have the Amazon Fire target, the setup for advertising is exactly the same as is described in this article for Android.

If you have not already signed up for an AdMob account, you should do this now (it's free), and also ensure that you have your game set up and running on the target platform(s). You can find setup guides from the following links:

We also recommend that you read the AdMob Implementation Guidelines, as these outline how Google expects you to use each type of ad unit:

 

Adding Your Game To The AdMob Dashboard

Once you have signed up and logged in to your AdMob account, you can start to add the games you want to monetise to the dashboard. When it comes to AdMob, each version of a game is considered an individual app, so if your project is for iOS and Android then you'll need to add it twice, once for each platform.

NOTE: From now on this article assumes you will be publishing to both Android and iOS, but if that is not the case, simply skip the steps associated with the platform you do not wish to target.

From the main dashboard menu on the left, select the Apps category:

AdMob_Dashboard_Apps.png

Here is where you will add the games that you want to monetise and define the different properties for the advertising to be shown. To add a game to the dashboard, simply click the Add App button. You will then be asked if you have already published the game to the App Store or Google Play. If you have already published and have a live store page, you should select "Yes" and then search for the app and click the "Add" button on the right:

AdMob_AddExistingApp.png

Once added, you will be shown the App ID (which we'll need later) and be prompted to make an Ad Unit for the game or skip that step. Don't forget, if you have a game on both Google Play and the App Store, you will need to add it twice in this way and set up individual ad units for each one, so you may want to skip setting up an ad unit just now and go ahead and add the other version of the published app. Once you're ready and have linked both stores, you can go ahead to the section below on Creating An Ad Unit.

If you haven't yet published the game publicly to either of the supported stores, you can simply click "No" and continue. On the next page you will be asked to give a name to the App and then select whether it is Android or iOS:

AdMob_NewAppListing.png

Click the Add button when ready and you'll be taken to the overview page where you'll be shown the App ID - which you should take note of as you'll need it later - along with options to Create Ad Unit or skip that step. You can add ad units at any time to an app after it has been created so if you are doing Android and iOS you may want to skip the ad unit part and instead add the other version of the game. When ready you can continue on to the section on Creating An Ad Unit.

 

Creating An Ad Unit

Once you have added the app(s) you can then start creating ad units. There is no limit to ad units that you can add for an application. and they don't all need to be active in the same app at the same time. You can create various units with different properties and then swap the unit IDs in the game project to change which one is used (this will require a new upload of the project to the relevant stores).

If you didn't click the Create Ad Unit button when you added the game to the AdMob dashboard, then you will need to create the ad unit from the dashboard itself. For that simply go to the app listing and click the game title link:

Admob_OpenAppOverview.png

Regardless of how you get here, the next thing you'll see is the App Overview page where you'll get the basic information and reports about the apps monetisation performance. From here, if the game has no ad units added yet, you'll see a handy button "Add Ad Unit" (alternatively you can click the Ad Units option from the Dashboard menu and add the unit from there):

AdMob_AddAdUnit.png

You will then be presented with the option to select the type of ad unit to create:

AdMob_AdUnitType.png

 

All three types are supported by GameMaker Studio 2, so we'll quickly run through the setup of each in the following sections.

Note that after creating each of your ad units you will be presented with the App Id (which you should already have taken note of) and the ad Unit ID

AdMob_CreatedBannerAd.png

The Unit ID is the ID that will be required by GameMaker Studio 2 to show the ads, so take a copy of it after creating each unit for later.

IMPORTANT! Once an ad unit is set up, it may take a few hours (up to 24) for it to start serving ads, and during that time any test you do using GMS2 may show an error in the console. This means that you should wait some time between creating the ad unit and testing.

 

Banner Ads

Banner ads are just what they say - banners of text, images or video that can be displayed anywhere in the screen at any time. Setting them up is as simple as giving the unit a name and then clicking the Create Ad Unit button, although there are some advanced settings available too (see the Google Documentation for details):

AdMob_BannerAdSetup.png

Once you click the Create Ad Unit button, the unit will be created and you can note the Unit ID and then click either Done, if you don't wish to make any other ad units, or Create Another Ad Unit, if you do.

 

Interstitial Ads

An interstitial ad is a full screen advert that can be either text, images or video, and they are usually shown at natural breaks in the game, like when completing a level or dying, etc... Like banner ads, when you select this format you can simply give it an identifying name and then click the Create Ad Unit button, although there are some advanced settings available too (see the Google Documentation for details):

AdMob_InterstitialAdSetup.png

Once you click the Create Ad Unit button, the unit will be created and you can note the Unit ID and then click either Done, if you don't wish to make any other ad units, or Create Another Ad Unit, if you do.

 

Rewarded Ads

Rewarded video ad units enable users to watch videos to earn in-app rewards, such as coins, extra lives, or points. You can set different rewards for different ad units, and specify the reward values and items users will receive. Note that rewarded ads can only be video ads, with a maximum length of 60 seconds.

As with the other ad types, you need to give the unit a name and then you can set the award amount, and the name of the "currency" that you are awarding. This can be anything appropriate for your game, like gold, mana, etc... In general you need do nothing else and can click the Create Ad Unit button, although there are some advanced settings available too (see the Google Documentation for details):

AdMob_RewardsAdSetup.png

Once you click the Create Ad Unit button, the unit will be created and you can note the Unit ID and then click either Done, if you don't wish to make any other ad units, or Create Another Ad Unit, if you do.

 

Setting Up GameMaker Studio 2

Once you have set up the ad units for the game, you need to open up GameMaker Studio 2 and prepare the project to show the ads. For this we'll need to first install the Google Play Services extension, which you can get by going to the Add Ons section of the Main Game Options:

AdMob_AddExtension.png

Clicking the Download button will download the extension and install it. Once that's done you will also need to ensure that the Minimum SDK API Level is set to 14 in the Android Game Options, as that is the minimum required API level for the AdMob SDK to build:

AdMob_MinSDK.png

 

Initialising Ad Mob

Once you have installed the extension, you are almost ready to start coding the ads into your project. However before you start, make sure that you have the App ID and the various Ad Unit IDs as we'll need them for the code. If you didn't copy this when you created the app listing, you can easily find it by going to the AdMob dashboard and selecting the Apps menu option then View All Apps:

AdMob_ViewAllApps.png 

From the apps listings, you then simply have to click the App ID icon to copy the App ID to the clipboard:

AdMob_AppID.png

If you are wanting to show interstitial ads, then you will also need your Ad Unit ID for the interstitial ad unit, which (if you haven't already got it copied somewhere) you can get by clicking on the app in the AdMob dashboard, and then going to Ad Units and clicking the Ad Unit ID button to copy it to the clipboard. If you do not want to use interstitial ads, then simply supply an empty string "" as the Unit ID.

If you have any other ads (banners, or rewarded) then you should take a moment to copy each of those Ad Unit IDs too, as you'll need them later.

The actual code to initialise the ads should go in a controller object or a script that is called at the very start of your game, and it should be called once only. In our example code we'll also be showing how to set the game up for both iOS and Android, but if you only target one platform then the other can be omitted from the code.

So, to initialise the ads we'll do this (use your own App and Unit ID's, the ones shown here are for example only and will not work):

if os_type == os_ios
    {
    app_id = "ca-app-pub-4337965814269841~8766033236";
    banner_id = "ca-app-pub-4337965814269841/5893054134";
    interstitial_id = "ca-app-pub-4337965814269841/5893054156";
    rewarded_id = "ca-app-pub-4337965814269841/5893054177";
    }
else
    {
    ads_app_id = "ca-app-pub-4337965814269841~8766033395";
    banner_id = "ca-app-pub-4337965814269841/5893055122";
    interstitial_id = "ca-app-pub-4337965814269841/5893055258";
    rewarded_id = "ca-app-pub-4337965814269841/5893055399";
    }
GoogleMobileAds_Init(ads_interstitial, ads_app_id);
GoogleMobileAds_LoadInterstitial();
interstitial_loaded = false;

Storing the IDs in this way makes it obvious what each of them is and also makes it easier to change them later (especially important when re-using the code in another project). This will initialise AdMob and also set an interstitial ad to load in the background, as well as create a variable that will be used later to show the interstitial (see the section Adding An Interstitial, below, for more information).

At this point, we recommend that you run the project on your test device and pay attention to the console output. If all is correct then you should get a message like the following at some point:

Use AdRequest.Builder.addTestDevice("E3DAE5ACB5072BA36197B94E287927C9") to get test ads on this device.

If you copy this string you can then use it after initialising the ads extension to tell AdMob that the ads being shown are TEST ads only. This prevents any issues, like Google suspending your account for fraudulent click-through while testing. To set the ads as test ads you would use the following, after the code shown above (be sure to change the example string for the one from the console):

GoogleMobileAds_UseTestAds(true, "E3DAE5ACB5072BA36197B94E287927C9");

When you no longer require test ads, simply set the first argument of this function to false.

It is worth noting that a number of the Google Mobile Ads extension functions will trigger a Social Asynchronous Event with further data about the ads being run. This event can be identified by checking the "id" key of the built-in async_load DS map, which should hold the constant GoogleMobileAds_ASyncEvent. This is useful if you have multiple extensions generating asynchronous callbacks and need to easily identify them, and the code shown in the examples below demonstrates how this works.

 

Adding A Banner

Banner ads can be added to your game at any point and they can also be removed and even moved around on the screen as required. Banners are placed relative to the display size, and so you should be using the display_get_*() functions along with the extension functions to get the banner width and height to position them correctly.

When you initialise the AdMob extension and want to show a banner, you can choose to add the banner then position it later, or add the banner at a given display position. This can be done in any event at any time, so you can add a banner only when on the Main Menu, for example, and you also have multiple banner types that can be shown. The AdMob extension has the following constants to identify the different banner types:

Constant Name Size in dp (WxH) Description Availability
GoogleMobileAds_Banner 320x50 Standard Banner Phones and Tablets
GoogleMobileAds_Skyscraper 320x100 Large Banner Phones and Tablets
GoogleMobileAds_MRect 300x250 IAB Medium Rectangle Phones and Tablets
GoogleMobileAds_Full_Banner 468x60 IAB Full-Size Banner Tablets
GoogleMobileAds_Leaderboard 728x90 IAB Leaderboard Tablets
GoogleMobileAds_Smart_Banner Screen width x 32|50|90 Smart Banner Phones and Tablets

The code for adding a banner looks like this:

    GoogleMobileAds_AddBanner(banner_id, GoogleMobileAds_Banner);
    // or if you want to add it to a specific position:
    GoogleMobileAds_AddBannerAt(banner_id, GoogleMobileAds_Banner, x, y);

Just calling the function doesn't mean that the ad will be shown though, as there may be no ads to serve or some other issue. You may also wish to place the ads dynamically based on the size of the ad itself, which you won't know until you actually have an add to show. To help with this, adding a banner will trigger a Social Asynchronous Event. In this event, you can then check that it has been loaded correctly and position it or whatever. This would be done with something like the following code:

var _id = async_load[? "id"];
if _id == GoogleMobileAds_ASyncEvent
{
var ident = async_load[? "type"];
switch (ident)
    {
    case "banner_load":
        if async_load[? "loaded"] == 1
            {
            var _bw = GoogleMobileAds_BannerGetWidth();
            var _bh = GoogleMobileAds_BannerGetHeight();
            var _hh = display_get_height();
            var _ww = display_get_width() / 2;
            GoogleMobileAds_MoveBanner((_ww / 2) - (_bw / 2), _hh - _bh);
            }
        break;
    }
}

Now, the code above checks the built-in DS map async_load for the "type" key. This key will tell us which type of ads event has been triggered and in this case it's the "banner_load" event (note that we use a switch() for the check here, as it permits us to easily add in further checks as we add on other types of ad unit later). In the case of "banner_load", we then check to see if the banner has loaded correctly - the "loaded" key will be 1 for loaded and 0 for an error - and if it has loaded we use its width and height to position it correctly within the display.

NOTE: The full contents of the async_load map when loading a banner are -

"id" - The ID of the event being fired, in all cases for any AdMob extension callback it will be the constant GoogleMobileAds_ASyncEvent.

"type" - This is the event type and for banners it will be "banner_loaded".

"loaded" - This will be either 1, for loaded, or 0, for not loaded. If it's 0 then it may be that there is an error, or no connection, or there is no ad to be served.

"width" - The width of the banner that has been loaded (only valid if the "loaded" key equals 1).

"height" - The height of the banner that has been loaded (only valid if the "loaded" key equals 1).

Banners can be also be removed when not required, for example you may want to show a banner only when the game is paused, in which case you would call one of the Add functions on pause and then the remove function on un-pause. To remove a banner simply call:

GoogleMobileAds_RemoveBanner();

Note that you don't have to constantly add and remove banners to show/stop showing them. Instead you can use the following two functions to simply hide/show the ad (this is often preferable to adding and removing the ad, as you don't have to wait for the banner to load again):

GoogleMobileAds_HideBanner();
GoogleMobileAds_ShowBanner(); 

 

Adding An Interstitial

While you can show an interstitial ad at any time, Google recommends - and the user expects - interstitials to be shown only at certain points in a game where there is a natural pause in the gameplay. Transitions from one game area to another, when a player dies, or when the level changes, etc... To show an interstitial you need to follow these steps:

  • Load the interstitial
  • Check the interstitial has loaded
  • Show the interstitial at an opportune moment
  • Repeat

In the section on Initialising AdMob (above) we initialised the interstitial API when we initialised the AdMob extension and then we called GoogleMobileAds_LoadInterstitial() to start loading an ad and created a controller variable interstitial_loaded. This means our ad will be loaded right from game start so it will be ready to be shown when required. However we need to know when it is going to be ready to show, which you can do in either of the following two ways:

  • In The Step Event: You can check to see if an interstitial has loaded using the following code in the Step Event of a controller object:

        if GoogleMobileAds_InterstitialStatus() == "Ready"
            {
            if interstitial_loaded != true
                {
                interstitial_loaded == true;
                }
            }


    The function GoogleMobileAds_InterstitialStatus() will return either "Ready" or "Not Ready" depending on whether the ad has loaded or not, and in the code when it is ready it sets a variable to true so we can check the variable later and show the ad.

  • In The Social Asynchronous Event: When you call the interstitial load function, a Social Asynchronous Event will be fired when the SDK callback is received, and you can use that to check and see if the ad has loaded or not. This event would be set up similar to that used when working with Banner Ads, and if you have already set up banners, you will simply need to add the case for interstitials from this code example into the switch statement that you already have:

        var _id = async_load[? "id"];
        if _id == GoogleMobileAds_ASyncEvent
        {
        var ident = async_load[? "type"];
        switch (ident)
            {
            case "interstitial_load":
                if async_load[? "loaded"] == 1
                    {
                    interstitial_loaded = true;
                    }
                break;
            }
        }

In both the above cases, we are setting a variable to true, and this variable can then be checked on room end, or when the player dies, or whenever is required that you show the app, something like this:

if interstitial_loaded == true
    {
    interstitial_loaded = false;
    GoogleMobileAds_ShowInterstitial();

    }

Finally, once the ad has been shown, another Social Asynchronous Event will be triggered, and you can check for the "type" "interstitial_closed". In this way you can do something specific after the ad has been shown, or (as is shown in the example code) start loading the next ad to be shown. The code below is a single case that would be added into the switch shown above::

case "interstitial_closed":
    GoogleMobileAds_LoadInterstitial();
    break;

NOTE: The full contents of the async_load map when loading an interstitial are -

"id" - The ID of the event being fired, in all cases for any AdMob extension callback it will be the constant GoogleMobileAds_ASyncEvent.

"type" - This is the event type and for interstitials and it will be either "interstitial_loaded" or "interstitial_closed".

"loaded" - This will be either 1, for loaded, or 0, for not loaded. If it's 0 then it may be that there is an error, or no connection, or there is no ad to be served.

 

Adding Rewarded Ads

With rewarded ads, you can give users a reward for having watched a video add. These are set up in a similar fashion to Interstitial Ads, although their placement in the game would be different as they are generally not activated automatically, but rather when the user presses a button or performs a specific act.

Before you can show a reward video it has to be loaded into memory, so you need to call the following function using the rewarded ad Unit ID (this can be done at the start of the game, the same as with interstitials):

GoogleMobileAds_LoadRewardedVideo(rewarded_id);
rewarded_loaded = false;
rewarded_viewed = false;

This will send of a request for an ad and set a variable which can be used to set button status and control the showing of the ad. It also sets a variable to store whether the full ad was watched and the reward should be given, as players can close a rewarded ad at any time.

NOTE: Every time you call the load function, you need to supply a Unit ID for the ad to show, which means that you can have various different rewarded ad units created (each one with a different reward) and show them at different times by simply using a different Unit ID as required.

Once you have called the load function, you can then check whether the rewarded ad has loaded in one of two ways:

  • In The Step Event: You can check to see if a rewarded ad has loaded using the following code in the Step Event of a controller object:

        if GoogleMobileAds_RewardedVideoStatus() == "Ready"
            {
            if rewarded_loaded != true
                {
                rewarded_loaded == true;
                }
            }


    The function GoogleMobileAds_RewardedVideoStatus() will return either "Ready" or "Not Ready" depending on whether the ad has loaded or not, and in the code when it is ready it sets a variable to true so we can check the variable later and show the ad.

  • In The Social Asynchronous Event: When you call the rewarded ad load function, a Social Asynchronous Event will be fired when the SDK callback is received, and you can use that to check and see if the ad has loaded correctly or not. This event would be set up similar to that used when working with Interstitial or Banner Ads, and, if you have already set up either of those, you will simply need to add the case for interstitials from this code example into the switch statement that you already have:

        var _id = async_load[? "id"];
        if _id == GoogleMobileAds_ASyncEvent
        {
        var ident = async_load[? "type"];
        switch (ident)
            {
            case "rewardedvideo_adloaded":
                rewarded_loaded = true;
                break;
            }
        }

In both the above cases, we are setting a variable to true, and this variable can then be checked on room end, or when the player dies, or whenever is required that you show the app.

The Social Asynchronous Event will also be fired should the requested rewarded ad fail to load, and this can be checked by adding the following case into the switch shown above:

    case "rewardedvideo_loadfailed":
        show_debug_message("Error Code: " + string(async_load[? "errorcode"]));
        GoogleMobileAds_LoadRewardedVideo(rewarded_id);
        break;

In the example, we simply output the errorcode to the debug console, but in a game this can be used to disable a button, or show a message to the user saying the ad failed etc...

To show the ad, you would have a button object or something similar for the player to interact with and in that you'd check the variable being used to control the ads (this variable can also be used to show/hide the button based on availability or to show different text or sprites), something like this:

    if rewarded_loaded == true
        {
        GoogleMobileAds_ShowRewardedVideo();
        rewarded_loaded = false;
        }

This will show the rewards video which will then trigger a sequence of async events, each with their own unique "type" string. These events are (in order of firing):

  • "rewardedvideo_adopened" -  The ad has been opened (the async_load map has no further entries)

  • "rewardedvideo_videostarted" - The ad video has started playing (the async_load map has no further entries)

  • "rewardedvideo_watched" - The ad has been watched and the reward obtained. In this case the async_load map will contain two further keys:

    • "currency" - The name of the currency being awarded (a string). This can be stored and shown to the user, or it can be used to compare against a variable to make sure that the correct currency is being added (if you have multiple rewarded currency types)

    • "amount" - The amount of currency being awarded (a real number)

    Note that this event will only be triggered if the video has been watched to the end.

  • "rewardedvideo_adclosed" - The reward video has been closed. Note that this will trigger whenever the ad overlay is closed, regardless of whether the video has been watched to the end

These events would typically be dealt with as different cases within a switch, and for each one you can decide what action (if any) to take, as they happen. The code below is a small example of how this would look (note that if you have already added in interstitial or banner ads, then the cases used in this example can simply be copied into the already created switch):

    var _id = async_load[? "id"];
    if _id == GoogleMobileAds_ASyncEvent
    {
    var ident = async_load[? "type"]
    switch (ident)
        {
        case "rewardedvideo_adopened":
            show_debug_message("Rewards Video Opened");
            break;
        case "rewardedvideo_videostarted":
            show_debug_message("Rewards Video Started");
            break;
        case "rewardedvideo_watched":
            show_debug_message("Rewards Video Watched");
            rewarded_viewed = true;
            global.Money += async_load[? "amount"];
            break;
        case "rewardedvideo_adclosed":
            show_debug_message(“Rewards Video Closed”);
            if rewarded_viewed == false
                {
                // Reward video was closed before the end
                // Here you can set button states, show a message, etc...
                }
            else rewarded_viewed = false;
            GoogleMobileAds_LoadRewardedVideo("ca-app-pub-4337965814269841/9449561646");
            break;

        }
    }

In the above example, we've added a show_debug_message() call into each of the events so that you can see when they are triggered in the debug console. You may not need to use most of them in your projects, but they are provided to give as much control as possible over the rewarded ads should you need it.

 

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.