> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama-ad/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama-ad/getting-started/quick-start.md).

# Quick Start

Get Playgama Ad running in your game or portal. This page covers a minimal setup designed for visual testing — for complete technical documentation, see [Standalone SDK](https://wiki.playgama.com/playgama-ad/integration/standalone-sdk.md).

***

## Prerequisites

Before going live in production, you will need to complete the full onboarding workflow:

* A signed partnership agreement with Playgama.
* An approved Google MCM connection and `ads.txt` updated on your domain.
* Your `playgama_clid` (partner ID) obtained by registering your account.
* Your custom Ad SDK build provided directly by Playgama.
* End-to-end ad testing in a staging environment together with the Playgama team.
* An active Consent Management Platform (CMP) correctly passing consent signals.

For a detailed step-by-step walkthrough of the go-live requirements, see the [Onboarding Process](https://wiki.playgama.com/playgama-ad/getting-started/onboarding-process.md) page.

***

## Step 1. Add the SDK

> **Important:** New integrations should use SDK v0.3. Pass your `playgama_clid` in the script URL as shown below. For SDK v0.2 integration, see the [Standalone SDK](https://wiki.playgama.com/playgama-ad/integration/standalone-sdk.md) documentation.

Paste this into the `<head>` of your HTML page:

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

***

## Step 2. Initialize

Call `init()` once when your page loads, before requesting any ads:

```jsx
await window.pgAds.init();
window.pgAds.setGameId('YOUR_GAME_ID');
```

Replace `<clid>` with your partner ID and `YOUR_GAME_ID` with any string that identifies your game.

***

## Step 3. Show an Interstitial

```jsx
async function showInterstitial() {
    const ad = await window.pgAds.requestOutOfPageAd('interstitial');

    if (ad.state === 'ready') {
        ad.show();
    } else if (ad.state === 'empty') {
        resumeGame(); // no ad available — continue normally
        return;
    } else {
        ad.addEventListener('ready', () => ad.show());
        ad.addEventListener('empty', () => resumeGame());
    }

    ad.addEventListener('closed', () => resumeGame());
}
```

Call `showInterstitial()` at natural breakpoints — level end, game over, between rounds.

***

## Step 4. Show a Rewarded Ad

```jsx
async function showRewarded() {
    const ad = await window.pgAds.requestOutOfPageAd('rewarded');

    if (ad.state === 'ready') {
        ad.show();
    } else if (ad.state === 'empty') {
        resumeGame();
        return;
    } else {
        ad.addEventListener('ready', () => ad.show());
        ad.addEventListener('empty', () => resumeGame());
    }

    ad.addEventListener('rewarded', () => grantReward()); // grant reward here
    ad.addEventListener('closed', () => resumeGame());
}
```

Only grant the reward inside the `rewarded` event — not on `closed`.

***

## Step 5. Show a Banner

Add a container to your HTML:

```html
<div id="banner-ad" style="width: 728px; height: 90px;"></div>
```

Then request the ad:

```jsx
await window.pgAds.requestPageAd({
    el: 'banner-ad',
    type: 'banner_1',
    sizes: [[728, 90], [300, 250]]
});
```

> Your available banner **types** (`banner_1`, `banner_2`, …) and **sizes** are provided by your Playgama account manager — see [Standalone SDK](https://wiki.playgama.com/playgama-ad/integration/standalone-sdk.md) for the full `requestPageAd` reference.

***

## Complete Minimal Example

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://playgama.com/ads/v0.3.js?clid=<clid>"></script>
</head>
<body>

  <!-- Banner container -->
  <div id="banner-ad" style="width:728px; height:90px;"></div>

  <!-- Your game canvas -->
  <canvas id="game"></canvas>

  <script>
    async function initAds() {
        await window.pgAds.init();
        window.pgAds.setGameId('YOUR_GAME_ID');

        // Pre-roll on load
        const preroll = await window.pgAds.requestOutOfPageAd('interstitial_preroll');
        if (preroll.state === 'ready') preroll.show();
        else if (preroll.state !== 'empty') {
            preroll.addEventListener('ready', () => preroll.show());
        }
        preroll.addEventListener('closed', () => startGame());
        preroll.addEventListener('empty',  () => startGame());

        // Banner
        window.pgAds.requestPageAd({
            el: 'banner-ad',
            type: 'banner_1',
            sizes: [[728, 90], [300, 250]]
        });
    }

    initAds();
  </script>
</body>
</html>
```
