# Before you start

This package is only intended for use by web **games**.

Please apply to the beta using
[this form](https://adsense.google.com/start/h5-beta/?src=flutter).
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](https://developers.google.com/ad-placement)
to display ads in games on the web.

[H5 Games Ads](https://adsense.google.com/start/h5-games-ads/)
offers high-performing formats:

* [Interstitials](https://developers.google.com/ad-placement/apis#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](https://developers.google.com/ad-placement/apis#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](https://support.google.com/adsense/answer/9121589)
before using Rewarded Ads._

## Usage

First, initialize AdSense (see the
[Initialization](https://pub.dev/documentation/google_adsense/latest/topics/Initialization-topic.html)
topic).

### Import the H5 Games Ads client

<?code-excerpt "../example/lib/h5.dart (import-h5)"?>
```dart
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`:

<?code-excerpt "../example/lib/h5.dart (interstitial)"?>
```dart
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](https://developers.google.com/ad-placement/apis#interstitials)
for a full explanation of all the available parameters.

### Displaying a Rewarded Ad

_Review the
[Policy for ad units that offer rewards](https://support.google.com/adsense/answer/9121589)
before using Rewarded Ads._

To display a Rewarded Ad, call the `adBreak` method with an
`AdBreakPlacement.rewarded`:

<?code-excerpt "../example/lib/h5.dart (rewarded)"?>
```dart
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](https://developers.google.com/ad-placement/apis#rewarded_ads)
for a full explanation of all the available parameters, and the
[call sequence for a rewarded ad](https://developers.google.com/ad-placement/apis#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:

<?code-excerpt "../example/lib/h5.dart (adConfig)"?>
```dart
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](https://developers.google.com/ad-placement/apis/adconfig)
for a full explanation of all the available parameters.
