H5 Games Ads topic
Before you start
This package is only intended for use by web games.
Please apply to the beta using this form. Once approved, you may use the package.
Without approval, your code may not behave as expected, and your AdSense account may face policy issues.
H5 Games Ads
The h5.dart
library provides a way to use the
AdSense Ad Placement API
to display ads in games on the web.
H5 Games Ads offers high-performing formats:
- Interstitials: Full-screen ads that are displayed at natural breaks in your game, such as between levels. Users can choose to either click these ads or return to your game.
- Rewarded ads: Ads that users can choose to interact with in exchange for in-game rewards.
H5 Games Ads formats support display ads, TrueView and Bumper video ads.
Review the Policy for ad units that offer rewards before using Rewarded Ads.
Usage
First, initialize AdSense (see the Initialization topic).
Import the H5 Games Ads client
import 'package:google_adsense/h5.dart';
This provides an h5GamesAds
object with two methods: adBreak
to request ads,
and adConfig
to configure the ads that are going to be served.
Displaying an Interstitial Ad
To display an Interstitial Ad, call the adBreak
method with an
AdBreakPlacement.interstitial
:
h5GamesAds.adBreak(
AdBreakPlacement.interstitial(
type: BreakType.browse,
name: 'test-interstitial-ad',
adBreakDone: _interstitialBreakDone,
),
);
Ad break types
The following break types are available for interstitial
ads:
BreakType |
Description |
---|---|
start |
Before the app flow starts (after UI has rendered) |
pause |
Shown while the app is paused (games) |
next |
Ad shown when user is navigating to the next screen |
browse |
Shown while the user explores options |
See the Ad Placement API reference on Interstitials for a full explanation of all the available parameters.
Displaying a Rewarded Ad
Review the Policy for ad units that offer rewards before using Rewarded Ads.
To display a Rewarded Ad, call the adBreak
method with an
AdBreakPlacement.rewarded
:
h5GamesAds.adBreak(
AdBreakPlacement.rewarded(
name: 'test-rewarded-ad',
beforeReward: _beforeReward,
adViewed: _adViewed,
adDismissed: _adDismissed,
afterAd: _afterAd,
adBreakDone: _rewardedBreakDone,
),
);
If a Rewarded ad is available, the beforeReward
callback will be called with a
showAdFn
function that you can call to show the Ad when the player wants to
claim a reward.
When the user fully watches the ad, the adViewed
callback will be called, and
the reward should be granted.
If the user dismisses the ad before they're eligible for a reward, the
adDismissed
callback will be called instead.
See the Ad Placement API reference on Rewarded ads for a full explanation of all the available parameters, and the call sequence for a rewarded ad.
The adBreakDone
callback
Note that a call to adBreak
might not show an ad at all. It simply declares a
place where an ad could be shown.
If the API does not have an ad to show it will not call the various before/after
callbacks that are configured. However, if you provide an adBreakDone
callback,
this will always be called, even if an ad is not shown. This allows you to
perform any additional work needed for the placement, such as logging analytics.
The adBreakDone
function takes as argument an AdBreakDonePlacementInfo
object,
which contains a breakStatus
property. See the BreakStatus
enum docs for
more information about the possible values.
Configuring Ads
The adConfig
function communicates the game's current configuration to the Ad
Placement API. It is used to tune the way it preloads ads and to filter the kinds
of ads it requests so they're suitable.
You can call adConfig
with an AdConfigParameters
object at any time, like
this:
h5GamesAds.adConfig(
AdConfigParameters(
// Configure whether or not your game is playing sounds or muted.
sound: SoundEnabled.on,
// Set to `on` so there's an Ad immediately preloaded.
preloadAdBreaks: PreloadAdBreaks.on,
onReady: _onH5Ready,
),
);
See the Ad Placement API reference on adConfig for a full explanation of all the available parameters.