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.
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.
Before getting start you need to complete the following steps first.
- Create an Admob account - see: https://support.google.com/admob/answer/7356219
- Create an application on Admob account - see: https://support.google.com/admob/answer/2773509
- Create advert units for your application
- Copy your publisher ID and paste it in to the Mobile Advert Publisher ID property. Finding your Publisher ID
- 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.
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.
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
- 320 x 50
- 320 x 100
- 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.
- 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
- When in a failure condition, an error message related to it.
- When in a On Video Complete condition, the type of the related reward.
- When in a On Video Complete condition, the value of the related reward.
- 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.
- 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.