# Standalone solution

## 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)

<mark style="background-color:purple;">**Access**</mark>

**Playgama Ad** is currently available in **open beta**, please contact us using the Contact Us form at [**https://playgama.com/adv**](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:

```html
<script src="https://playgama.com/ads/common.v0.2.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:

```javascript
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:

```javascript
// 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.

```javascript
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.

```javascript
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.

```javascript
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.

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

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

```javascript
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')
})
```

**`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.