Standalone solution

Overview

Playgama Ad provides a monetization solution for web games and gaming platforms. The solution supports the following ad formats:

Interstitial ads
Rewarded ads
Display ads (banners)

Access

Playgama Ad is currently available in open beta, please contact us using the Contact Us form at https://playgama.com/adv.

Installation

Add the SDK script in your HTML head. For testing purposes, you can use the following version of the Playgama Ad SDK:

<script src="https://playgama.com/ads/common.v0.2.js"></script>

Country Code

The SDK needs to know the user's country. By default it makes a network request to resolve it. If you already know the country on your side, you can pass it via the data-country-code attribute on the script tag — the SDK will use it directly and skip the request:

<script
    src="https://playgama.com/ads/common.v0.2.js"
    data-country-code="DE"
></script>

The value must be a two-letter ISO 3166-1 alpha-2 country code.

Asynchronous Initialization

If you load the SDK asynchronously (or you are not sure when it loads), use pgAdsCallbacks to ensure the SDK is ready before you use it:

window.pgAdsCallbacks = window.pgAdsCallbacks || []
window.pgAdsCallbacks.push(() => {
    // window.pgAds is now available
    initAds()
})

async function initAds() {
    await window.pgAds.init({ clid: '<your-clid>' })
    // ...
}

Quick Start

Below is the minimal setup to initialize the SDK and display an interstitial ad:

// 1. Initialize the SDK
await window.pgAds.init({ clid: '<your-clid>' })

// 2. Request an Interstitial Ad
const banner = await window.pgAds.requestOutOfPageAd('interstitial')

// 3. Show the Ad when ready
banner.addEventListener('ready', () => {
    banner.show()
})

API Reference

The SDK exposes the global window.pgAds object with the following methods:

1. init(options): Promise<void>

Initializes the ads service. This must be called before requesting any ads.

Parameters:
- options (object):
  - clid (string, required): Your unique Client ID.
  - gameId (string, optional): Identifier for the current game.

await window.pgAds.init({ clid: '<your-clid>', gameId: '<game-identifier>' })

2. setGameId(gameId): void

Updates the game identifier after initialization. Use this when navigating between games without reinitializing the SDK.

Parameters:
- gameId (string | undefined): Identifier for the current game, or undefined to clear it.

window.pgAds.setGameId('<game-identifier>')

Updates the game identifier after initialization. Use this when navigating between games without reinitializing the SDK.

3. requestOutOfPageAd(type): Promise<PublicOutOfPageAdBanner>

Requests a full-screen or overlay ad (Interstitial or Rewarded).

Parameters:
- type (string): The ad format.
  - 'interstitial_preroll': Full-screen ad before content.
  - 'interstitial': Full-screen ad between content (e.g. at natural breaks in gameplay).
  - 'rewarded': Opt-in full-screen ad that rewards the user.

const rewardedBanner = await window.pgAds.requestOutOfPageAd('rewarded')

4. requestPageAd(options): Promise<PublicPageAdBanner>

Requests a standard display banner to be rendered inside a specific DOM element.

Parameters:
- options (object):
  - el (string): ID of the DOM element to render the ad in.
  - type (string): The ad type (e.g., 'banner_1', 'banner_2'). Contact support to get your personal banner types.
  - sizes (array): Array of sizes e.g. [[300, 250], [300, 300], 'fluid']. Contact support to get all available sizes.
  - refresh (number, optional): Auto-refresh interval in seconds.

const banner = await window.pgAds.requestPageAd({
    el: 'ad-container-id',
    type: 'banner_1',
    sizes: [[300, 300]],
})

5. preload(): Promise<void>

Preloads ad provider scripts into the browser cache.

When to use: This method is only needed if you have an same-origin iframe on your page inside which the SDK will be initialized (e.g. a game iframe hosted on the same domain). In that case, call preload() on the parent page before adding the iframe to the DOM — the scripts will already be cached when the SDK initializes inside the iframe.
If you don't have such an iframe, skip preload() entirely and call init() directly.
Note: Due to browser cache partitioning, this optimization does not work with cross-origin iframes — resources fetched in the parent are not reused in iframes on a different domain.

// Only if you have a same-origin game iframe:
// Call as early as possible, before adding the iframe to the page
window.pgAds.preload()

Banner Lifecycle

All ad objects returned by requests (PublicPageAdBanner and PublicOutOfPageAdBanner) share a common lifecycle managed through states and events.

Banner States

Check banner.state (string) to determine the current status of an ad:

'loading': The ad is currently being fetched.
'ready': The ad has loaded and is ready to be shown.
'showing': The ad is currently visible to the user.
'empty': No ad fill was received.
'closed': The ad was closed or finished.

Event Handling Use banner.addEventListener(event, callback) to react to lifecycle changes.

Common Events

Event

Description

ready

Fired when state becomes 'ready'. You can now call show().

empty

Fired when no ad is available (state becomes 'empty').

rendered

Fired when the ad is physically rendered in the DOM.

viewable

Fired when the ad becomes visible in the viewport.

Specific Events

Event

Description

rewarded

(Rewarded Ads only) Fired when the user completes the video. Grant the reward here.

closed

Fired when the user closes the ad or it finishes automatically. Resume your game/content here.

Ad Objects

PublicOutOfPageAdBanner

Returned by requestOutOfPageAd(). Represents high-impact, overlay ads.

Methods:

show(): void
- Displays the ad. Throws an error if the ad is not in the 'ready' state.

Example: Rewarded Ad Flow

const banner = await window.pgAds.requestOutOfPageAd('rewarded')

banner.addEventListener('ready', () => {
    banner.show()
})

banner.addEventListener('rewarded', () => {
    // User watched the video
    grantUserReward()
})

banner.addEventListener('closed', () => {
    // Ad closed, resume game loop
    resumeGame()
})

banner.addEventListener('empty', () => {
    // No ad available
    console.log('No fill')
})

PublicPageAdBanner

Returned by requestPageAd(). Represents standard in-page display ads.

These ads are typically rendered automatically into the container provided in el.
You mostly listen to empty or rendered events for layout adjustments.

Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the ask query parameter:

GET https://wiki.playgama.com/playgama/playgama-ad/standalone-solution.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.

PreviousGetting Started NextFallback Solution

Last updated 3 days ago