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