PlayaYield SDK Documentation

1Quick Start

ℹ️Chrome Web Store Description Checklist

Language for Implementation

Our extension provides ads within the extension interface, including in the popup, the side panel, and/or other internal extension pages.

This extension may display advertisements provided by third-party partners, including PlayaYield. To deliver and measure advertising, limited technical information such as IP address, device type, browser type, and interaction data may be transmitted to advertising partners. For more information, see PlayaYield's Privacy Policy: https://www.playayield.com/privacy

2Installation

Install the SDK using your preferred package manager:

npm install @playanext/playa-yield-sdk

3Configuration

Configure your manifest.json to work with PlayaYield:

{
  "manifest_version": 3,
  "name": "Your Extension",
  "version": "1.0.0",
  "background": {
    "service_worker": "background.js"
  }
}

4Supported Ad Sizes

PlayaYield currently supports the following standard ad sizes. Attempting to request any other size will result in an error.

5Where Ads Can Appear

PlayaYield ads are designed to appear only within your extension's own UI surfaces. This ensures Chrome Web Store compliance and a non-intrusive user experience.

Error: PlayaYield Ads can only be displayed in extension pages (Side Panel, Popup, or Internal Pages). Content script injection is not allowed.

initializePlayaYield()

Initialize the SDK in your background service worker. Call this once when your extension starts.

import { initializePlayaYield } from '@playanext/playa-yield-sdk';

initializePlayaYield({
  apiKey: 'your-api-key'
});

createAd()

Request and create an ad element. Returns a ready-to-append div containing the ad HTML. This must run in extension pages (popup, side panel, or internal extension UI) and is blocked in content scripts.

import { createAd } from '@playanext/playa-yield-sdk';

const { element, impressionId } = await createAd({
  placement: 'popup',
  size: { width: 300, height: 250 }
});

document.getElementById('ad-slot')!.appendChild(element);
console.log('Ad displayed with impression:', impressionId);

createManagedRefreshableAd()

Use refreshable ads for long-lived surfaces like side panels to maximize your earnings. By automatically rotating new ads, refreshable units lead to significantly higher revenues compared to static placements. The SDK automatically refreshes ads every 40 seconds and enforces a 29-impression limit per rolling 30-minute session window.

import { createManagedRefreshableAd } from '@playanext/playa-yield-sdk';

// Using CSS selector - SDK handles everything automatically
await createManagedRefreshableAd({
  container: '#ad-slot',
  placement: 'sidepanel',
  size: { width: 300, height: 250 }
});

// Or using element reference
await createManagedRefreshableAd({
  container: document.getElementById('ad-slot')!,
  placement: 'sidepanel',
  size: { width: 300, height: 250 }
});

Live Integration Example

Here's a live example showing how to integrate PlayaYield into your Chrome extension from start to finish.

import { initializePlayaYield } from '@playanext/playa-yield-sdk';

// Initialize once when your extension loads
initializePlayaYield({
  apiKey: 'your-api-key-here'
});

console.log('PlayaYield SDK initialized');

import { createAd } from '@playanext/playa-yield-sdk';

async function loadAd() {
  try {
    const { element, impressionId } = await createAd({
      placement: 'popup',
      size: { width: 300, height: 250 }
    });

    document.getElementById('ad-container')!.appendChild(element);
    console.log('Ad loaded:', impressionId);
  } catch (error) {
    console.error('Failed to load ad:', error);
    // Hide ad container or show fallback
  }
}

// Load ad when popup opens
document.addEventListener('DOMContentLoaded', loadAd);

import { createManagedRefreshableAd } from '@playanext/playa-yield-sdk';

async function loadRefreshableAd() {
  try {
    await createManagedRefreshableAd({
      container: '#ad-slot',
      placement: 'sidepanel',
      size: { width: 300, height: 250 }
    });

    console.log('Refreshable ad started');
  } catch (error) {
    console.error('Failed to load ad:', error);
  }
}

document.addEventListener('DOMContentLoaded', loadRefreshableAd);

<!DOCTYPE html>
<html>
<head>
  <title>My Extension</title>
  <style>
    #ad-container {
      width: 300px;
      min-height: 250px;
      margin: 16px auto;
    }
  </style>
</head>
<body>
  <div id="app">
    <!-- Your extension content -->
  </div>
  
  <div id="ad-container"></div>
  
  <script src="popup.js"></script>
</body>
</html>

More Examples

Additional patterns for common use cases.

import { createAd } from '@playanext/playa-yield-sdk';

const { element } = await createAd({
  placement: 'popup',
  size: { width: 300, height: 250 }
});

document.getElementById('banner-slot')!.appendChild(element);

import { createAd } from '@playanext/playa-yield-sdk';

// Run this in your sidepanel, popup, or internal page
// (not a content script)
const { element } = await createAd({
  placement: 'sidepanel',
  size: { width: 320, height: 100 }
});

document.getElementById('sidepanel-ad')!.appendChild(element);

import { createAd } from '@playanext/playa-yield-sdk';

const { element } = await createAd({
  placement: 'popup',
  size: { width: 300, height: 250 }
});

// Apply custom styles to the ad container
element.style.borderRadius = '8px';
element.style.boxShadow = '0 4px 6px rgba(0,0,0,0.1)';
element.style.margin = '20px auto';

document.getElementById('ad-slot')!.appendChild(element);

import { createAd } from '@playanext/playa-yield-sdk';

// Load multiple ads in parallel
const [ad1, ad2] = await Promise.all([
  createAd({ placement: 'popup', size: { width: 300, height: 250 } }),
  createAd({ placement: 'popup', size: { width: 320, height: 50 } })
]);

document.getElementById('ad-slot-1')!.appendChild(ad1.element);
document.getElementById('ad-slot-2')!.appendChild(ad2.element);

Test Mode

Use test mode during development to request ads with your test API key. Test mode delivers realistic ads for integration testing but does not generate revenue or fire tracking events.

initializePlayaYield({
  apiKey: 'dev_test_key'
});

Tracking & Compliance

PlayaYield handles all tracking automatically. You don't need to implement any tracking code.

Error Handling

The SDK throws typed errors that extend PlayaYieldError. Always wrap your ad requests in try-catch blocks.

import { createAd } from '@playanext/playa-yield-sdk';

try {
  const { element } = await createAd({
    placement: 'popup',
    size: { width: 300, height: 250 }
  });
  
  document.getElementById('ad-slot')!.appendChild(element);
} catch (error) {
  if (error instanceof Error) {
    switch (error.name) {
      case 'NetworkError':
        console.error('Network request failed:', error.message);
        // Show fallback UI or retry
        break;
      case 'ConfigError':
        console.error('Configuration error:', error.message);
        // Check SDK initialization
        break;
      default:
        console.error('Unexpected error:', error);
    }
  }
}