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:
- Create an Admob account - see: Sign up for AdMob
- Create an application on your Admob account - see: Set up an app in Admob
- Create ad units for your application - see: Ad units
- Copy your application IDs and paste them to the Mobile Advert Android Application ID and iOS Application ID properties. Finding your Application IDs
- 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:
- Sign up for an Adsense account
if you already don't have one
- You will need a website which is whitelisted to show these type of ads
- Fill in this form to indicate interest in using Google's Ad Placement API
How do I get my site whitelisted?
- Visit the Sites options in the left hand side menu of your Adsense account
- Find the Add site button and click it to start adding your website
- Follow the steps to add your website
- You will need to modify the root of your website by adding a small script to it
- Request a review
After sometime, hopefully your website will be approved and your game will be able to show ads.
Considerations for web adverts
- 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.
- 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.
- 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. If the reload parameter is set to true an existing banner will be reloaded with the new settings. Setting overlap to true causes the banner to overlap the main Webview, If false the main Webview will be resized so both it and the banner fit in the screen without overlapping. In the case of setting overlap to true the offset parameter can be used to specify an amount by which the banner should be offset from it's initial position.
- 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.