From a8777264e099a9529392d35bfbb90eb99865dd1a Mon Sep 17 00:00:00 2001 From: Jon Imperiosi Date: Wed, 25 Sep 2024 16:14:55 -0700 Subject: [PATCH] Add gaming interstitial ad documentation. PiperOrigin-RevId: 678885355 --- .github/workflows/push-to-gh-pages.yml | 8 +- .../display-gaming-interstitial-ad/README.md | 92 +++++++++++++++++++ 2 files changed, 96 insertions(+), 4 deletions(-) create mode 100644 samples/display-gaming-interstitial-ad/README.md diff --git a/.github/workflows/push-to-gh-pages.yml b/.github/workflows/push-to-gh-pages.yml index aa046dd..681011c 100644 --- a/.github/workflows/push-to-gh-pages.yml +++ b/.github/workflows/push-to-gh-pages.yml @@ -30,17 +30,17 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v3 - name: Build project run: | npm install npm run build - name: Setup Pages - uses: actions/configure-pages@v5 + uses: actions/configure-pages@v3 - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v2 with: path: './dist' - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v2 diff --git a/samples/display-gaming-interstitial-ad/README.md b/samples/display-gaming-interstitial-ad/README.md new file mode 100644 index 0000000..bf9eea2 --- /dev/null +++ b/samples/display-gaming-interstitial-ad/README.md @@ -0,0 +1,92 @@ +# Display an H5 gaming interstitial ad + +Important: Gaming interstitial ads are a limited-access format. For more +information, see [Display an H5 gaming interstitial ad][admanger_hc_gia]. + +This example displays a gaming interstitial ad using the Google Publisher Tag +(GPT) library. Gaming interstitials are GPT-managed, full-page ads that you +display to users playing web-based games based on a manual trigger. For more +information about gaming interstitials, see +[Display an H5 gaming interstitial ad][admanger_hc_gia]. + +To display and interact with gaming interstitial ads, use the following GPT +events: + +Event | Fired when... +:--------------------------- | :------------------------------------------- +[`GamingInterstitialSlotReady`][] | A gaming interstitial ad is ready to display to the user.

To display the interstitial, call [`makeGameManualInterstitialVisible()`][] on the provided event object. +[`GamingInterstitialSlotClosed`][] | The user closed a previously displayed gaming interstitial ad.

Use this event to run custom logic whenever a gaming interstitial is closed. + +##Game structures + +Gaming interstitial ads can display either fullscreen or inside the frame of +your game, depending on how your game is structured. For more details, see +[H5 Game structures][admanager_hc_game_structures]. + +The sample implementation assumes that the H5 game renders directly into the +top-most window, using the **Fullscreen** structure. In this scenario, the +gaming interstitial ad also renders fullscreen. + +However, this same code also works when placed inside of a child frame, using +the **iFrame/WebView** structure. To constrain the gaming interstitial ad to the +H5 game canvas, place the game in an iFrame, as shown in the following example: + +```html + + + + + Page for this example H5 game + + + + Example H5 game + + + + + +``` + +## Usage notes + +* **To ensure an optimal user experience, GPT only requests gaming + interstitial ads on pages that properly support the format.** Due to this + restriction, `defineOutOfPageSlot()` may return null. You must check for + this case to ensure you're not doing any unnecessary work. + +* **Only request gaming interstitial ads on pages or environments where you + want an interstitial to appear.** Gaming interstitial ads are eligible to + serve to desktop, tablet, and mobile devices. + + Note: You can use Chrome DevTools mobile simulation to test gaming + interstitial ads on mobile from a desktop environment. + +* **Gaming interstitial ads generate their own ad slot.** Unlike other ad + types, it's not necessary to define a `
` for gaming interstitial ads. + These ads automatically create and insert their own container into the page + when an ad fills. + +* **Gaming interstitial ads are one-time use.** You cannot refresh a gaming + interstitial ad slot. Instead, you must destroy the slot and re-create it, + as shown in the sample implementation. + +* **Gaming interstitial ads have a fixed frequency cap.** The frequency cap + prevents the `gamingInterstitialSlotReady` event from firing more than once + every 120 seconds. + +* **If using single-request architecture (SRA) on a page with multiple slots, + don't call `display()` until static ad slots divs are created.** As + explained in [Ads Best Practices][guide_sra], the first call to `display()` + requests every ad slot defined before that point. Although gaming + interstitial slots don't require a predefined `
`, static ad slots do. + Calling `display()` before these elements are present on the page can result + in lower quality signals. We recommend delaying the initial call until after + static slots are defined. + +[admanager_hc_game_structures]: //support.google.com/admanager/answer/14637831#h5-game-structures +[admanger_hc_gia]: //support.google.com/admanager/answer/14640119 +[guide_sra]: //developers.google.com/publisher-tag/guides/ad-best-practices#use_single_request_architecture_correctly +[`GamingInterstitialSlotClosed`]: //developers.google.com/publisher-tag/reference#googletag.events.GameManualInterstitialSlotClosedEvent +[`GamingInterstitialSlotReady`]: //developers.google.com/publisher-tag/reference#googletag.events.GameManualInterstitialSlotReadyEvent +[`makeGameManualInterstitialVisible()`]: //developers.google.com/publisher-tag/reference#googletag.events.GameManualInterstitialSlotReadyEvent.makeGameManualInterstitialVisible