Skip to content

quick_start_guide

Jump to bottom
Francisco Dias edited this page Sep 17, 2024 · 4 revisions

Quick Start Guide

This section aims to deliver an easy and simple set of examples that should help you migrate your project from a previous version of the AdMob extension into this new, updated version. The first thing to notice is that all previously named "GoogleMobileAds_*" functions have been renamed to "AdMob_*" providing a more compact naming convention which is consistent with the Google API function names outside the GameMaker environment.

Initialization

The first thing to look for when creating an AdMob GameMaker project is initializing your API.

[Old Version]

// On the previous version you would need to provide application id and
// an interstitial id to the API initialization function.
GoogleMobileAds_Init(interstitialId, applicationId);

// Optionally you could set your device to test mode to use test ads instead
// of ‘live’ ones. You would provide the enable flag and the device id.
GoogleMobileAds_UseTestAds(enable, deviceId); // <----- this is OPTIONAL

[New Version]

// If you are using Test Ads the ‘AdMob_SetTestDeviceId’ function needs to be
// called BEFORE initialization (no arguments are required).
AdMob_SetTestDeviceId(); // <----- this is OPTIONAL (development only)

// In the new version you just need to call the initialization method without
// any arguments, as the extension now gets the application id from the
// “extension options” automatically (Setup, 2.), and the ad ids are setup on
// a per ad-type basis.
AdMob_Initialize();

Consent (GDPR)

One of the first concepts requiring your attention when setting up a project using AdMob is that, depending on the user's geographic location, you might need to ask for permission to use their personal information to personalize the ads that are shown.

[Old Version]

In previous versions you could ask the user for their consent to collect data for personalized ads using one of the following setups:

// You could forcefully show the consent form providing a privacy URL and
// options for personalized ads, non-personalized ads and ad-free version of
// your game.
GoogleMobileAds_ConsentFormShow(privacyPolicy, personalized, nonPersonalized, adFree);

OR

// You could show the consent form ONLY if the user hasn’t yet answered it.
GoogleMobileAds_ConsentUpdate(publisherId, privacyPolicy, personalized, nonPersonalized, adFree);

[New Version]

The new version has added functionality that requires you to:

  1. check the consent status;
  2. load the consent form before showing it to the user;
  3. show the form (this replaces the old ’GoogleMobileAds_ConsentFormShow’)

The first steps towards requesting user consent are the following:

// First of all we need to set the Consent Mode, which can be used for
// debugging purposes to run tests as a  user in a different geographic area;
// more info: Consent Mode. This function will generate an ASYNC SOCIAL EVENT.
AdMob_Consent_RequestInfoUpdate(AdMob_Consent_Mode_PRODUCTION);

After setting the consent mode we need to add some code to the Social Async Event, to check for the events generated by the AdMob_Consent_RequestInfoUpdate function call. Here is what each event allows us to do:

  1. “AdMob_Consent_OnRequestInfoUpdated” → we check status & load form;
  2. “AdMob_Consent_OnLoaded” → we show the consent form;
  3. “AdMob_Consent_OnShown” → we get the user's consent type;

Given below is the fully documented template code that you can use in your Social Async Event:

// Early exit if there is no 'type' key defined
if (!ds_map_exists(async_load, "type")) exit;

// All the events triggered by the AdMob extension have a "type" key
// containing a string that starts with "AdMob_".
switch(async_load[? "type"])
{
	// AdMob_Consent_RequestInfoUpdate() succeeded
	case "AdMob_Consent_OnRequestInfoUpdated":

		// Now we need to get the consent Status, this will tell us if we
		// are required to ask the user for GDPR consent.
		if (AdMob_Consent_GetStatus() == AdMob_Consent_Status_REQUIRED)

			// Since we are REQUIRED, we now need to load the consent
			// form before we can show it. For this we use the function
			// below (more info: AdMob_Consent_Load). This function call
			// will also generate an ASYNC SOCIAL EVENT.
			AdMob_Consent_Load();
		break;

	// AdMob_Consent_RequestInfoUpdate() failed
	case "AdMob_Consent_OnRequestInfoUpdateFailed":

		// This means there was a problem while setting the consent
		// mode. Here we can add some code to deal with it.
		break;

	// AdMob_Consent_Load() succeeded
	case "AdMob_Consent_OnLoaded":

		// We have successfully loaded the consent form and we are now
		// ready to show it to the user (more info: AdMob_Consent_Show)
		AdMob_Consent_Show();
		break;

	// AdMob_Consent_Load() failed
	case "AdMob_Consent_OnLoadFailed":

		// This means there was a problem while loading the consent
		// form. Here we can add some code to deal with it.
		break;

	// AdMob_Consent_Show() succeeded and the user already answered it
	case "AdMob_Consent_OnShown":

		// At this point we now have the consent information from the
		// user. We can use both the GetStatus and GetType functions to
		// get the obtained information (more info:
		// AdMob_Consent_GetStatus and AdMob_Consent_GetType)
		global.ConsentStatus = AdMob_Consent_GetStatus();
		global.ConsentType = AdMob_Consent_GetType();
		break;
}

Targeting

This new version of the AdMob extension allows the developer to target ads to a specific audience. This could already be done in previous versions but the new version now has more features specifically for targeting.

[Old Version]

In previous versions the developer could mark a user as underage ads using the following function:

// The function below classifies users as under age and only non-personalised
// ads can be shown, regardless of any other setting, and the consent form
// will not be shown.
GoogleMobileAds_ConsentSetUserUnderAge(true);

[New Version]

In the new version of the extension the developer is presented with more features that will help target the right kind of ads to the right kind of audience:

// The function below allows the developer to enable or disable ads for
// under-age users (much like the old version). Note that it is up to the
// developer to identify the age of the consumer.
AdMob_Targeting_UnderAge(true);

// The function below allows the developer to enable or disable ads for
// children. Note that it is up to the developer to identify the age of the
// consumer.
AdMob_Targeting_COPPA(true);

// The new version of the AdMob extension allows for even further control
// over the filtering of the ads being displayed to the user. The function
// below allows the developer to set a maximum content rating of the ads to be
// displayed (info: AdMob_Targeting_MaxAdContentRating and Content Rating constant.
AdMob_Targeting_MaxAdContentRating(AdMob_ContentRating_GENERAL);

Banner Ads

There have been a lot of API changes since the previous version, that said let’s jump in on a quick set up for adding banner ads to your application.

[Function Mappings]

Even though not all old functions map perfectly into the new API the following list should get you started with some of the changes (check the section below for more details):

  • AdMob_Banner_Init(...) initializes the banner ads with a unique id.
  • AdMob_Banner_Create(...) replaces GoogleMobileAds_AddBanner(...)
    • triggers the Social event “AdMob_Banner_OnLoaded” if creation succeeds
    • triggers the Social event “AdMob_Banner_OnLoadFailed” if creation failed
  • AdMob_Banner_Move(...) replaces GoogleMobileAds_MoveBanner(...)
  • AdMob_Banner_Remove() replaces GoogleMobileAds_RemoveBanner()
  • AdMob_Banner_Show() replaces GoogleMobileAds_ShowBanner()
  • AdMob_Banner_Hide() replaces GoogleMobileAds_HideBanner()

[New Version]

The first step we should take towards adding banners is to use a manager object with the following Create Event (remember that you need to initialize the API first - AdMob_Initialize)

// After API initialization we can proceed to initialize the banner options.
// This function requires a unique ad block id string that can be obtained
// from the google developer console (more info: AdMob_Banner_Init).
// This function will generate an ASYNC SOCIAL EVENT.
var banner_id = "ca-app-pub-3940256099942544/6300978111"
AdMob_Banner_Init(banner_id);

The second step requires us to make sure the API was initialized, so for this example we will use the ASYNC SOCIAL EVENT to check for the events generated by the AdMob_Initialize function call.

// Early exit if there is no 'type' key defined
if (!ds_map_exists(async_load, "type")) exit;

// All the events triggered by the AdMob extension have a “type” key
// containing a string that starts with “AdMob_”.
switch(async_load[? "type"])
{
	// AdMob_Initialize() finished initializing the API
	case "AdMob_OnInitialized":

		// Now that we are sure that the API was initialized we can create
		// our new banner on the device display.

		// The function below will create a new banner of a given type,
		// allowing the developer to also select the position of the
		// banner (this can be either at the top or the bottom of the
		// screen (more info: AdMob_Banner_Create and Banner Type).
		var banner_type = AdMob_Banner_ADAPTIVE;
		var bottom = true;
		AdMob_Banner_Create(banner_type, bottom)
		break;

	// AdMob_Banner_Create() succeeded
	case "AdMob_Banner_OnLoaded":

		// At this point we should now have a banner on the screen.
		break;

	// AdMob_Banner_Create() failed
	case "AdMob_Banner_OnLoadFailed":

		// At this point there was a problem while creating the banner.
		// Here we can add some code to deal with it.

		// NOTE: Don’t try to create a banner here because it can lead to
		// an infinite loop if the banner creation fails constantly.
		break;
}

Interstitial Ads

Interstitial ads are ads that will fill up the entire screen and need to be dismissed in order for the application to continue execution. Initial setup for interstitials is very similar to Banner ads (more info: Banner Ads). Let’s look at some code to quickly set up interstitial ads for your application.

[Function Mappings]

Even though not all old functions map perfectly into the new API, the following list should get you started with some of the changes (check the section below for more details):

  • AdMob_Interstitial_Init(...) initializes the interstitial ads with a unique id.
  • AdMob_Interstitial_Load() replaces GoogleMobileAds_LoadInterstitial()
    • triggers the Social event “AdMob_Interstitial_OnLoaded” if load succeeds
    • triggers the Social event “AdMob_Interstitial_OnLoadFailed” if load fails
  • AdMob_Interstitial_IsLoaded() replaces GoogleMobileAds_InterstitialStatus()
  • AdMob_Interstitial_Show() replaces GoogleMobileAds_ShowInterstitial(...)
    • triggers the Social event “AdMob_Interstitial_OnFullyShown” if show succeeds
    • triggers the Social event “AdMob_Interstitial_OnShowFailed” if show fails
    • triggers the Social event “AdMob_Interstitial_OnDismissed” upon dismissing

[New Version]

The first step we should take towards adding interstitials is to use a manager object with the following CREATE EVENT (remember that you need to initialize the API first - AdMob_Initialize)

// After API initialization we can proceed to initialize the interstitial
// options. This requires a unique ad block id string that can be obtained
// from the google developer console. (more info: AdMob_Interstitial_Init).
// This function will generate a SOCIAL ASYNC EVENT.
var interstitial_id = "ca-app-pub-3940256099942544/1033173712"
AdMob_Interstitial_Init(interstitial_id);

The second step requires us to make sure the API was initialized so for this example we will use the ASYNC SOCIAL EVENT, to check for the events generated by the AdMob_Initialize function call.

// Early exit if there is no 'type' key defined
if (!ds_map_exists(async_load, "type")) exit;

// All the events triggered by the AdMob extension have a “type” key
// containing a string that starts with “AdMob_”.
switch(async_load[? "type"])
{
	// AdMob_Initialize() finished initializing the API
	case "AdMob_OnInitialized":

		// Now that we are sure that the API got initialized we can load
		// a new interstitial ad.(more info: AdMob_Interstitial_Load).
		// This function will generate an ASYNC SOCIAL EVENT.
		AdMob_Interstitial_Load();
		break;

	// AdMob_Interstitial_Load() succeeded
	case "AdMob_Interstitial_OnLoaded":

		// At this point we should now have the interstitial ad loaded and
		// and we can check that using the ´AdMob_Interstitial_IsLoaded´
		// function. We are now ready to show the interstitial ad to the
		// user (more info: AdMob_Interstitial_Show). This function will
		// generate an ASYNC SOCIAL EVENT.
		AdMob_Interstitial_Show();
		break;

	// AdMob_Interstitial_Load() failed
	case "AdMob_Interstitial_OnLoadFailed":

		// At this point there was a problem while loading the
		// interstitial ad. Here we can add some code to deal with it.

		// NOTE: Don’t try to reload the interstitial ad here because
		// it can lead to an infinite loop.
		break;

	// AdMob_Interstitial_Show() succeeded
	case "AdMob_Interstitial_OnFullyShown":

		// At this point the interstitial ad is on screen and the user is
		// looking at it. Note that at this point in time your game is
		// paused and will remain paused until the interstitial gets
		// dismissed.
		break;

	// AdMob_Interstitial_Show() failed
	case "AdMob_Interstitial_OnShowFailed":

		// At this point the interstitial ad failed to get shown to the
		// user. You can add code to deal with the problem here.

		// NOTE: Don’t try to reload/show the interstitial ad here
		// because it can lead to an infinite loop.
		break;

	// Interstitial got dismissed
	case "AdMob_Interstitial_OnDismissed":

		// At this point the interstitial ad got dismissed by the user and
		// the game logic is running again.
		break;

}

Rewarded Video Ads

Rewarded video ads are ads that will fill up the entire screen and play a video, at the end of which the user can be rewarded in some way, and similar to interstitial ads they also need to be dismissed in order for the application to continue execution. Rewarded Video ads setup is very similar to other previous ads (more info: Banner Ads and Interstitial Ads). Let’s look at some code to quickly set up rewarded video ads on your application.

[Function Mappings]

Even though not all old functions map perfectly into the new API the following list should get you started with some of the changes (check the section below for more details):

  • AdMob_RewardedVideo_Init(...) initializes the interstitial ads with a unique id.
  • AdMob_RewardedVideo_Load() replaces GoogleMobileAds_LoadRewardedVideo()
    • triggers the event “AdMob_RewardedVideo_OnLoaded” if load succeeds
    • triggers the event “AdMob_RewardedVideo_OnLoadFailed” if load fails
  • AdMob_RewardedVideo_IsLoaded() replaces GoogleMobileAds_RewardedVideoStatus()
  • AdMob_RewardedVideo_Show() replaces GoogleMobileAds_ShowRewardedVideo(...)
    • triggers the event “AdMob_RewardedVideo_OnFullyShown” if show succeeds
    • triggers the event “AdMob_RewardedVideo_OnShowFailed” if show fails
    • triggers the event “AdMob_RewardedVideo_OnDismissed” upon dismissing
    • triggers the event “AdMob_RewardedVideo_OnReward” when reward conditions are met.

[New Version]

The first step we should take towards adding rewarded videos is to use a manager object with the following CREATE EVENT (remember that you need to initialize the API first - AdMob_Initialize)

// After API initialization we can proceed to initialize the rewarded video
// options. This requires an unique ad block id string that can be obtained
// from the google developer console. (more info: AdMob_RewardedVideo_Init).
// This function will generate an ASYNC SOCIAL EVENT.
var rewarded_id = "ca-app-pub-3940256099942544/1033173712"
AdMob_RewardedVideo_Init(rewarded_id);

The second step requires us to make sure the API was initialized. For this example we will use the ASYNC SOCIAL EVENT, to check for the events generated by the AdMob_Initialize function call.

// Early exit if there is no 'type' key defined
if (!ds_map_exists(async_load, "type")) exit;

// All the events triggered by the AdMob extension have a “type” key
// containing a string that starts with “AdMob_”.
switch(async_load[? "type"])
{
	// AdMob_Initialize() finished initializing the API
	case "AdMob_OnInitialized":

		// Now that we are sure that the API got initialized we can load
		// a new rewarded video ad.(more info: AdMob_RewardedVideo_Load).
		// This function will generate an ASYNC SOCIAL EVENT.
		AdMob_RewardedVideo_Load();
		break;

	// AdMob_RewardedVideo_Load() succeeded
	case "AdMob_RewardedVideo_OnLoaded":

		// At this point we should now have the rewarded ad loaded and
		// and we can check that using the ´AdMob_RewardedVideo_IsLoaded´
		// function. We are now ready to show the rewarded video ad to the
		// user (more info: AdMob_RewardedVideo_Show). This function will
		// generate an ASYNC SOCIAL EVENT.
		AdMob_RewardedVideo_Show();
		break;

	// AdMob_RewardedVideo_Load() failed
	case "AdMob_RewardedVideo_OnLoadFailed":

		// At this point there was a problem while loading the
		// interstitial ad. Here we can add some code to deal with it.

		// NOTE: Don’t try to reload the interstitial ad here because
		// it can lead to an infinite loop.
		break;

	// AdMob_RewardedVideo_Show() succeeded
	case "AdMob_RewardedVideo_OnFullyShown":

		// At this point the rewarded video ad is playing and the user is
		// looking at it. Note that at this point in time your game is
		// paused and will remain paused until the rewarded video ad gets
		// dismissed.
		break;

	// AdMob_RewardedVideo_Show() failed
	case "AdMob_RewardedVideo_OnShowFailed":

		// At this point the rewarded video ad failed to get shown to the
		// user. You can add code to deal with the problem here.

		// NOTE: Don’t try to reload/show the rewarded video here
		// because it can lead to an infinite loop.
		break;

	// RewardedVideo got dismissed
	case "AdMob_RewardedVideo_OnDismissed":

		// At this point the rewarded video ad got dismissed by the user
		// and the game logic is running again.
		break;

	// RewardedVideo triggered the reward event
	case "AdMob_RewardedVideo_OnReward":

		// At this point the user watched enough of the rewarded video and
		// can be rewarded for it. Here we can add the reward code.
		show_debug_message("You got 1000 points");
		break;

}

Rewarded Interstitial Ads

Rewarded interstitial is a type of incentivized ad format that allows you offer rewards for ads that appear automatically during natural app transitions. Unlike rewarded ads, users aren't required to opt-in to view a rewarded interstitial, and similar to interstitial ads they also need to be dismissed in order for the application to continue execution. Rewarded interstitial ads setup is very similar to other previous ads (more info: Banner Ads and Interstitial Ads). Let’s look at some code to quickly set up rewarded interstitial ads on your application.

[Function Mappings]

Even though not all old functions map perfectly into the new API the following list should get you started with some of the changes (check the section below for more details):

  • AdMob_RewardedInterstitial_Init(...) initializes the interstitial ads with a unique id.
  • AdMob_RewardedInterstitial_Load()
    • triggers the event “AdMob_RewardedInsterstitial_OnLoaded” if load succeeds
    • triggers the event “AdMob_RewardedInsterstitial_OnLoadFailed” if load fails
  • AdMob_RewardedInterstitial_IsLoaded()
  • AdMob_RewardedInterstitial_Show()
    • triggers the event “AdMob_RewardedInsterstitial_OnFullyShown” if show succeeds
    • triggers the event “AdMob_RewardedInsterstitial_OnShowFailed” if show fails
    • triggers the event “AdMob_RewardedInsterstitial_OnDismissed” upon dismissing
    • triggers the event “AdMob_RewardedInsterstitial_OnReward” when reward conditions are met.

[Code Sample]

The first step we should take towards adding rewarded interstitial is to use a manager object with the following CREATE EVENT (remember that you need to initialize the API first - AdMob_Initialize)

// After API initialization we can proceed to initialize the rewarded
// interstitial options. This requires an unique ad block id string that can
// be obtained from the google developer console. (more info:
// AdMob_RewardedInterstitial_Init).
// This function will generate an ASYNC SOCIAL EVENT.
var rewarded_interstitial_id = "ca-app-pub-3940256099942544/5354046379"
AdMob_RewardedVideo_Init(rewarded_interstitial_id);

The second step requires us to make sure the API was initialized. For this example we will use the ASYNC SOCIAL EVENT, to check for the events generated by the AdMob_Initialize function call.

// Early exit if there is no 'type' key defined
if (!ds_map_exists(async_load, "type")) exit;

// All the events triggered by the AdMob extension have a “type” key
// containing a string that starts with “AdMob_”.
switch(async_load[? "type"])
{
	// AdMob_Initialize() finished initializing the API
	case "AdMob_OnInitialized":

		// Now that we are sure that the API got initialized we can load
		// a new rewarded interstitial ad.
		// (more info: AdMob_RewardedInterstitial_Load).
		// This function will generate an ASYNC SOCIAL EVENT.
		AdMob_RewardedInterstitial_Load();
		break;

	// AdMob_RewardedInterstitial_Load() succeeded
	case "AdMob_RewardedInterstitial_OnLoaded":

		// At this point we should now have the rewarded ad loaded and
		// and we can check that using the
		// ´AdMob_RewardedInterstitial_IsLoaded´ function. We are now
		// ready to show the rewarded interstitial ad to the user
		// (more info: AdMob_RewardedInterstitial_Show).
		// This function will generate an ASYNC SOCIAL EVENT.
		AdMob_RewardedInterstitial_Show();
		break;

	// AdMob_RewardedInterstitial_Load() failed
	case "AdMob_RewardedInterstitial_OnLoadFailed":

		// At this point there was a problem while loading the
		// interstitial ad. Here we can add some code to deal with it.

		// NOTE: Don’t try to reload the interstitial ad here because
		// it can lead to an infinite loop.
		break;

	// AdMob_RewardedInterstitial_Show() succeeded
	case "AdMob_RewardedInterstitial_OnFullyShown":

		// At this point the rewarded video ad is playing and the user is
		// looking at it. Note that at this point in time your game is
		// paused and will remain paused until the rewarded video ad gets
		// dismissed.
		break;

	// AdMob_RewardedInterstitial_Show() failed
	case "AdMob_RewardedInterstitial_OnShowFailed":

		// At this point the rewarded video ad failed to get shown to the
		// user. You can add code to deal with the problem here.

		// NOTE: Don’t try to reload/show the rewarded video here
		// because it can lead to an infinite loop.
		break;

	// RewardedInterstitial got dismissed
	case "AdMob_RewardedInterstitial_OnDismissed":

		// At this point the rewarded interstitial ad got dismissed by the
		// user and the game logic is running again.
		break;

	// RewardedInterstitial triggered the reward event
	case "AdMob_RewardedInterstitial_OnReward":

		// At this point the user watched enough of the rewarded video and
		// can be rewarded for it. Here we can add the reward code.
		show_debug_message("You got 1000 points");
		break;

}

YoYoGames 2025

AdMob Extension

Guides

Modules

Extras

Clone this wiki locally