Mobile Advert

The Mobile Advert plugin allows a game to use Admob Banner, Interstitial, Rewarded and Rewarded Interstitial adverts on Android and iOS exports.

Web exports use Google's Ad Placement API to show Interstitial and Rewarded adverts.

Advert types

Construct supports the following advert types:

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. (Mobile export only)
Interstitial Advert
Displays a full screen advert, useful for transitioning between layouts. (Mobile & Web exports)
Rewarded Advert
Similar to an interstitial advert in that it is a full screen advert. If the user watches this advert for the designated amount of time, they will get the reward payload. If the advert is dismissed before that, the reward is not given. (Mobile & Web exports)
Rewarded Interstitial Advert
Similar to rewarded adverts, but users aren’t required to opt in to view a rewarded interstitial. Instead of the opt-in prompt in rewarded ads, rewarded interstitials require an intro screen that announces the reward and gives users a chance to opt out if they wish to do so. (Mobile & Web exports)

Getting started with Admob

Follow these steps to quickly get started with Admob on mobile exports:

  1. Create an Admob account - see: Sign up for AdMob
  2. Create an application on your Admob account - see: Set up an app in Admob
  3. Create ad units for your application - see: Ad units
  4. Copy your application IDs and paste them to the Mobile Advert Android Application ID and iOS Application ID properties. Finding your Application IDs
  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.

Getting started with web adverts

Follow these steps to quickly get started with adverts on web exports:

  1. Sign up for an Adsense account if you already don't have one
  2. You will need a website which is whitelisted to show these type of ads
  3. Fill in this form to indicate interest in using Google's Ad Placement API

How do I get my site whitelisted?

  1. Visit the Sites options in the left hand side menu of your Adsense account
  2. Find the Add site button and click it to start adding your website
  3. Follow the steps to add your website
  4. You will need to modify the root of your website by adding a small script to it
  5. Request a review

After sometime, hopefully your website will be approved and your game will be able to show ads.

Considerations for web adverts

  1. You will need to have your website be a real one, that means that it should have real content and generally speaking look like it is serving a purpose. If you just setup a test website with no content, it is less likely it will be approved.
  2. Since the parent website your game will be hosted in needs to be whitelisted so the game can show ads, the ideal use case is you have control of the hosting website.
  3. If a game is shown in a cross origin iframe, it won't be allowed to show ads.

User Consent (Mobile exports only)

In order for the Show User Consent Dialog action to show GDPR consent forms and IDFA messages (iOS only), it is required to set them up in your Admob account.

GDPR message

Follow this guide to Create a GDPR message

IDFA message

Follow this guide to Create an IDFA message

Mobile exports required properties

If you intend to show ads in mobile exports, either Android or iOS, you will need to specify your application IDs on the Mobile Advert object. Without these values the plugin will not be able to start.

Web exports required properties

If you intend to show ads in a web export, you will need to specify your publisher ID in the Mobile Advert object. Without that value, the plugin will not be able to show web adverts.

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

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 create or 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 App Tracking Transparency framework on iOS

In order to support the Request IDFA action, the Mobile Advert plugin includes an iOS library called App Tracking Transparency. 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 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. (Mobile & Web exports)
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 (Mobile exports only)
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 (Mobile exports only)
Spoof location (debug)
Fakes the device location to allow testing the user consent dialog in different scenarios. Testing mode must be enabled for this to work. (Mobile exports only)
Show on start up
Choose wether to show the consent form automatically on startup or not. This option doesn't do anything in web exports. (Mobile exports only)
Publisher ID
Adsense publisher ID, found in your Adsense account. This is required if you intend to show adverts in a web export. Find your publisher ID (Web exports only)

Differences between mobile and web adverts

Ad units

If you only want to show web ads, it is not necessary to provide ad units in your actions, the field can be left blank. If you are planning to use the same project for web and mobile though, you will still need to provide them.

Rewarded ads

There is a slight difference between rewarded ads in mobile and rewarded ads in web that should be considered.

In mobile when the ad is viewed you can use the RewardType and RewardValue expression to get information about the reward and this information is set in your Admob account through the ad unit.

In a web export, because you don't use ad units, the rewarded ads will always return the value "Reward" for the RewardType expression and the value of "1" for the RewardValue expression.

For this reason it is recommended to use the Platform Info plugin to decide what to do after a rewarded ad is viewed, depending on what platform the game is running on.

Mobile Advert Conditions

On Banner Ready
Triggers when a banner advert has loaded.
On Interstitial Ready
Triggers when a interstitial advert has loaded.
On Rewarded Ready
Triggers when a rewarded advert has loaded.
On Rewarded Interstitial Ready
Triggers when a rewarded interstitial advert has loaded.
On Banner Failed to Load
Triggers when a banner advert fails to load.
On Interstitial Failed to Load
Triggers when a interstitial advert fails to load.
On Rewarded Failed to Load
Triggers when a rewarded advert fails to load.
On Rewarded Interstitial Failed to Load
Triggers when a rewarded interstitial advert fails to load.
On Banner Shown
Triggers when a banner advert has been displayed.
On Interstitial Complete
Triggers when a interstitial advert has closed.
On Rewarded Complete
Triggers when a rewarded advert has closed, and the user has been rewarded.
On Rewarded Interstitial Complete
Triggers when a rewarded interstitial advert has closed, and the user has been rewarded.
On Banner Hidden
Triggers when a banner advert has been hidden.
On Interstitial Cancelled
Triggers when a interstitial advert has been cancelled.
On Rewarded Cancelled
Triggers when a rewarded advert has been cancelled.
On Rewarded Interstitial Cancelled
Triggers when a rewarded interstitial 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.
Is Configured
True if the plugin has been succesfully configured.
Is Showing Banner
True if a banner advert is being shown.
Is Showing Interstitial
True if a interstitial advert is being shown.
Is Showing Rewarded
True if a rewarded advert is being shown.
Is Showing Rewarded Interstitial
True if a rewarded interstitial advert is being shown.
Is Banner Loaded
True if a banner advert is ready to be shown.
Is Interstitial Loaded
True if a interstitial advert is ready to be shown.
Is Rewarded Loaded
True if a rewarded advert is ready to be shown.
Is Rewarded Interstitial Loaded
True if a rewarded 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. In web exports this condition always evaluates to "true".

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 Rewarded
Create a rewarded advert with a AdMob advert unit ID. Optionally show when loaded. Only one rewarded advert 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.
Create Rewarded Interstitial
Create a rewarded interstitial advert with a AdMob advert unit ID. Optionally show when loaded. Only one rewarded interstitial may be created at a time.
Show User Consent Dialog
Shows the modal user consent dialog
Show Banner
Show a loaded banner advert. Will only display if there is a loaded banner ready.
Show Rewarded
Show a loaded rewarded 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.
Show Rewarded Interstitial
Show a loaded rewarded interstitial advert. Will only display if there is a loaded rewarded 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. This action is not supported in web exports.
Tag For Child Directed Treatment
Request advert content that is child-directed for the purposes of the Children's Online Privacy Protection Act (COPPA). This action is not supported in web exports.
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). This action is not supported in web exports.

Mobile Advert Expressions

ErrorMessage
When in a failure condition, an error message related to it.
RewardType
When in a On Rewarded Complete condition, the type of the related reward. In web exports this expression always returns the value "Reward".
RewardValue
When in a On Rewarded Complete condition, the value of the related reward. In web exports this expression always returns the value "1".
RewardInterstitialType
When in a On Rewarded Interstitial Complete condition, the type of the related reward. In web exports this expression always returns the value "Reward".
RewardInterstitialValue
When in a On Rewarded Interstitial Complete condition, the value of the related reward. In web exports this expression always returns the value "1".
ConsentStatus
The current user consent status as a string, can take the values of: UNKNOWN, NOT_REQUIRED, REQUIRED or OBTAINED. In web exports this expression always return the UNKNOWN value.
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. In web exports this expression always return the "not-determined" value.
Construct 3 Manual 2023-03-28