Standalone solution

Overview

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

• Interstitial ads

• Rewarded ads

• Display ads (banners)

Beta Access

Playgama Ad is currently available in closed beta. To request access, 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.1.js"></script>

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();
    // ...
}

Quick Start

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

// 1. Initialize the SDK
await window.pgAds.init();
window.pgAds.updateTargeting({ playgama_clid: '<your-clid>', gameId: '<game-identifier>' });

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

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

API Reference

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

1. init(): Promise<void>

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

await window.pgAds.init();

2. updateTargeting(targeting): void

Updates targeting parameters for subsequent ad requests. Use this to identify your traffic source.

• Parameters:

  • targeting (object): Key-value pairs for ad targeting. Common keys:

    • playgama_clid (required): Your unique Client ID;

    • gameId (optional): Identifier for your game/app.

window.pgAds.updateTargeting({
    playgama_clid: '<your-clid>',
    gameId: '<game-identifier>'
});

3. requestOutOfPageAd(type): Promise<OutOfPageBanner>

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

• Parameters:

  • type (string): The ad format.

    • 'interstitial': Full-screen ad between content.

    • 'rewarded': Video ad that rewards the user.

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

4. requestPageAd(options): Promise<Banner>

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., 'vertical_1', 'horizontal_1').

    • refresh (number, optional): Auto-refresh interval in seconds.

    • sizes (array): Array of sizes e.g. [[300, 250], [300, 300], 'fluid']. Contact support to get all available sizes.

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

Banner Lifecycle

All ad objects returned by requests (Banner and OutOfPageBanner) 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

Important: Always check the banner.state immediately after receiving the banner object. If the banner is already in ready or empty state (e.g., from cache), the event may not fire again.

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

OutOfPageBanner

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', () => {
    // Ad is ready, you might want to show a "Watch Video" button now
    showWatchButton(); 
});

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');
});

// If ready immediately (rare but possible if cached)
if (banner.state === 'ready') {
   banner.show();
}

Banner

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.