PlayaYield SDK Documentation

1Quick Start

2Chrome Web Store Description Checklist

Language for Implementation

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

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

3Installation

Install the SDK using your preferred package manager:

npm install @playanext/playa-yield-sdk

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 within your extension's own UI surfaces by default, with optional support for content scripts controlled subject to approval by PlayaYield. Contact us to request approval for content script placements.

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'
});

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 }
});

createAd()

Request and create an ad element. Returns a ready-to-append div containing the ad HTML. Must be called from an extension page (popup, side panel, or internal page) or from a content script. Note that content scripts must use the 'content_script' placement.

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

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, internal page, or content script
// Content scripts must use placement: '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';

// 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);
    }
  }
}