Mobile Advert

The Mobile Advert plugin allows a game to use Admob Banner, Interstitial and Rewarded Video adverts on Android and iOS. This plugin does not provide advert services for HTML, Arcade, Desktop or Windows UWP exports.

Advert types

Construct supports the three main types of advert that AdMob provides:

Banner Advert
Displays an advert that partially overlays the bottom of the screen, the size of the advert can be specified when it's created.
Interstitial Advert
Displays a full screen advert, useful for transitioning between layouts.
Rewarded Video Advert
Similar to an interstitial advert in that it is a full screen advert. Plays a video that the user can either watch or dismiss. If the user watches the whole video then a reward payload is given.

Getting Started

Before getting start you need to complete the following steps first.

  1. Create an Admob account - see: https://support.google.com/admob/answer/7356219
  2. Create an application on Admob account - see: https://support.google.com/admob/answer/2773509
  3. Create advert units for your application
  4. Copy your publisher ID and paste it in to the Mobile Advert Publisher ID property. Finding your Publisher ID
  5. Submit your business and payment details to your AdMob account and wait for them to verify (which may take 24 hours). This must be done before ads can be served.

That's all the configuration you need for now. You can create new applications and edit your advert units later if you need.

Before using adverts inside your game you need to specify your application ID, publisher ID and a privacy policy URL on the Mobile Advert object. Without these values the plugin will not be able to start. If you do not have a privacy policy yet then you can place a filler website address in its place, but this should be replaced with your actual privacy policy before you release your game.

Initialization

The plugin will automatically initialize when the app starts. However this may involve showing a user consent prompt to the user for regulatory reasons, depending on the user's region. Therefore you should wait for the On configuration complete trigger to fire before attempting to show any ads. You should also use the On configuration failed trigger, and perhaps the Is configured condition, to check if configuration failed for any reason, such as being on an invalid platform or one of your properties being incorrect.

Using IDFA on iOS

As of iOS 14+, the identifier for advertisers or IDFA is no longer available to apps by default. This can affect the performance of ads. To use the IDFA, you must prompt the user for permission to access it with the Request IDFA action. You may also wish to do this on startup. The On IDFA request complete trigger fires when the user makes a decision, and the IDFAStatus expression indicates the outcome.

The AppTrackingTransparency framework on iOS

In order to support the Request IDFA action, the Mobile Advert plugin includes an iOS library called AppTrackingTransparency. To comply with Apple's App Store review process you may be required to indicate to the reviewers where your app uses the IDFA prompt. Therefore you may be required to add the Request IDFA action somewhere in your project. You do not have to always request it on startup - it could for example be a setting in a menu, and then you indicate to the App Store reviewers where to find the option.

Advert Loading

Adverts need to load over the network before you can use them. When creating an advert you can choose to "show" the advert immediately after it has loaded. However if it's more suitable for your game you can choose to load your advert ahead of time by creating the advert, but not showing it, then later displaying the advert when you need it. This will prevent your user experiencing a lag while the advert loads. Be sure to check your advert has actually loaded before trying to display it, loading times for rewarded video adverts in particular can be quite long. It's also worth remembering that you are not guaranteed to receive an advert when you request one, so take that into account when you are making your events.

Banner Advert Sizes

To display a banner advert you must specify a size for it, generally smart portrait/landscape will work for most situations but here are the specifiable sizes. Using a size that is larger than the display will prevent it from loading. Smart banner will vary in height depending on the available screen height. With a smart banner if the base image isn't wide enough to fill the screen black bars are displayed on either side.

Smart portrait
Screen width x 32/50/90
Smart landscape
Screen width x 32/50/90
Standard
320 x 50
Large
320 x 100
Medium
300 x 250
Full (tablet only)
468 x 60
Leaderboard (tablet only)
728 x 90

Mobile Advert Properties

Testing mode
Changes the displayed adverts units to testing adverts. Should be used during development.
Android application ID
The Admob application ID for the Android version of your game. This has the format "ca-app-pub-0000000000000000~0000000000". On Android this value is required, and your application will fail to start unless it is provided and correct. Find your app ID
iOS application ID
The Admob application ID for the iOS version of your game. This has the format "ca-app-pub-0000000000000000~0000000000". On iOS this value is required, and your application will fail to start unless it is provided and correct. Find your app ID
Publisher ID
Your Admob publisher ID. This has the format "pub-0000000000000000". Finding your Publisher ID
Show AD free option
Toggles whether the "show Ad free" option will appear on the user consent dialog. Typically this is used if you wish to charge a user to disable adverts in your application.
Privacy policy URL
Your privacy policy URL, this will appear in the user consent dialog. This is required, and your game may fail to start if this is an invalid URL.
Locations to show user consent dialog
Changes the locations in which the user consent will be shown automatically at startup. Set to "nowhere" if you wish to control when it appears yourself. Unfortunately the development kit does not currently allow the dialog to be shown outside of the EEA.
Spoof location (debug)
Fakes the device location to allow testing the user consent dialog in different scenarios.

Mobile Advert Conditions

On Banner Ready
Triggers when a banner advert has loaded.
On Video Ready
Triggers when a video advert has loaded.
On Interstitial Ready
Triggers when a interstitial advert has loaded.
On Banner Failed to Load
Triggers when a banner advert fails to load.
On Video Failed to Load
Triggers when a video advert fails to load.
On Interstitial Failed to Load
Triggers when a interstitial advert fails to load.
On Banner Shown
Triggers when a banner advert has been displayed.
On Video Complete
Triggers when a video advert has closed, and the user has been rewarded.
On Interstitial Complete
Triggers when a interstitial advert has closed.
On Banner Hidden
Triggers when a banner advert has been hidden.
On Interstitial Cancelled
Triggers when a interstitial advert has been cancelled.
On Video Cancelled
Triggers when a video advert has been cancelled.
On Configuration Complete
Triggers when the application ID has been successfully set.
On Configuration Failed
Triggers when the application ID failed to be set.
On IDFA request complete
Triggered after the Request IDFA action once the user has made a decision. The outcome of their decision is reflected in the IDFAStatus expression.
On User Personalization Updated
Triggers when the user advert personalization value has been updated
Is Configured
True if a banner advert is being shown.
Is Showing Banner
True if a banner advert is being shown.
Is Showing Video
True if a video advert is being shown.
Is Showing Interstitial
True if a interstitial advert is being shown.
Is Banner Loaded
True if a banner advert is ready to be shown.
Is Video Loaded
True if a video advert is ready to be shown.
Is Interstitial Loaded
True if a interstitial advert is ready to be shown.
Is in EEA or unknown
True if the SDK consider the device to be inside the EEA or is unable to detect the location. As it is a requirement to show the dialog inside the EEA "unknown" is considered effectively the same as being in the EEA.

Mobile Advert Actions

Create Banner
Create a banner advert with a AdMob advert unit ID and size. Optionally show when loaded. Only one banner may be created at a time.
Create Video
Create a rewarded video advert with a AdMob advert unit ID. Optionally show when loaded. Only one video may be created at a time.
Create Interstitial
Create a interstitial advert with a AdMob advert unit ID. Optionally show when loaded. Only one interstitial may be created at a time.
Show User Consent Dialog
Shows the modal user consent dialog
Set User Personalization
Change the user personalization setting. Note changing this may have legal implications related to GDPR regulations
Show Banner
Show a loaded banner advert. Will only display if there is a loaded banner ready.
Show Video
Show a loaded video advert. Will only display if there is a loaded video ready.
Show Interstitial
Show a loaded interstitial advert. Will only display if there is a loaded interstitial ready.
Hide Banner
Hide an active banner advert (destroys the advert). Does nothing if no banner is available.
Request IDFA
Prompt the user for permission to use the identifier for advertisers (IDFA). When the user makes a decision, On IDFA request complete triggers, and the outcome is indicated in the IDFAStatus expression. See the section on using the IDFA above.
Set Max Advert Content Rating
Filter the viewed adverts based on the digital content label classifications for various age groups.
Tag For Child Directed Treatment
Request advert content that is child-directed for the purposes of the Children's Online Privacy Protection Act (COPPA).
Tag for under age of consent
Indicate the user should be treated as under the age of consent as per the restrictions in the European Economic Area(EEA) General Data Protection Act(GDPR).

Mobile Advert Expressions

ErrorMessage
When in a failure condition, an error message related to it.
RewardType
When in a On Video Complete condition, the type of the related reward.
RewardValue
When in a On Video Complete condition, the value of the related reward.
ConsentStatus
The current user consent status as a string (PERSONALIZED, NON_PERSONALIZED, AD_FREE or UNKNOWN). Note that on subsequent runs of the app AD_FREE reverts to UNKNOWN.
IDFAStatus
Indicates the outcome of requesting to use the IDFA. If no request has been made this defaults to "not-determined". After a request it is either "authorized" or "denied" depending on the choice the user made.
Construct 3 Manual 2020-12-10