Standalone solution

v0.2 is still supported, but new integrations should use v0.3. See the version tabs below for the differences.

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. Pick the tab for the SDK version you're integrating:

v0.3

<script src="https://playgama.com/ads/v0.3.js?clid=<your-clid>"></script>

Your Client ID is passed as the clid query parameter on the script URL itself.

Config ID

To use a different ad configuration than the one linked to your clid, pass its ID via the config_id query parameter:

<script src="https://playgama.com/ads/v0.3.js?clid=<your-clid>&config_id=<your-config-id>"></script>

v0.2

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

The SDK build is provided by your account manager. Replace <partner_name_sdk> with the name provided for your account, and use only the SDK build assigned to your account.

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, and the SDK will use it directly and skip the request:

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

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

Your clid is the playgama_clid assigned to your account.

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:

v0.3

window.pgAdsCallbacks = window.pgAdsCallbacks || [];
window.pgAdsCallbacks.push(async () => {
  await window.pgAds.init();
});

v0.2

window.pgAdsCallbacks = window.pgAdsCallbacks || [];
window.pgAdsCallbacks.push(async () => {
  await window.pgAds.init({ clid: "<your-clid>" });
});

Quick Start

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

v0.3

// 1. Initialize the SDK (clid comes from the script URL, see Installation)
await window.pgAds.init();

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

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

v0.2

// 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

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

v0.3

init(options?): Promise<void>

• Parameters:

  • options (object, optional):

    • gameId (string, optional): Identifier for the current game.

await window.pgAds.init({ gameId: "<game-identifier>" });

v0.2

init(options): Promise<void>

• 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>");

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. requestVideoPageAd(options): Promise<PublicPageVideoAdBanner>

Requests an in-page video banner to be rendered inside a specific DOM element.

Unlike requestPageAd, this method takes no sizes and no refresh: the creative is stretched to fill the element you point at, and it is not auto-refreshed.

• Parameters:

  • options (object):

    • el (string): ID of the DOM element to render the ad in. It must have a fixed width and height, since the SDK renders the creative into it. A collapsed element leaves nothing to fill.

    • type (string): The ad type (e.g. 'video_banner'). Contact support to get your personal video banner types.

const banner = await window.pgAds.requestVideoPageAd({
  el: "ad-video-container-id",
  type: "video_banner",
});

The returned object is a PublicPageVideoAdBanner, with the states and events:

Event	Description
rendered	The ad has been rendered into your element
viewable	The ad became visible in the viewport.
empty	No ad was rendered.
closed	The ad finished or was closed. The banner destroys itself.

banner.addEventListener("rendered", () => {
  // The video ad is on screen
});

banner.addEventListener("viewable", () => {
  // The video playing
});

banner.addEventListener("empty", (event) => {
  // no ad
});

banner.addEventListener("closed", () => {
  // The video finished or was closed
});

6. preload(): Promise<void>

Preloads ad provider scripts into the browser cache.

When to use: This method is only needed if you have a 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, so the scripts are already 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

PublicPageAdBanner and PublicOutOfPageAdBanner share a common lifecycle managed through states and events. The lifecycle events for PublicPageVideoAdBanner are documented separately above.

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.