PlayaYield SDK Documentation

1Quick Start

ℹ️Chrome Web Store Description Checklist

Google requires plain-language disclosure when you monetize an extension. Use this guidance in your Chrome Web Store description to show reviewers and users that PlayaYield ads stay compliant and do not rely on additional user permissions.

This extension uses PlayaYield to show ads only inside internal extension pages (popup, side panel, and settings UI). Ads never inject into websites, never modify search, and never require new user permissions or data access.

• •Clearly list every surface where ads appear (popup, side panel, internal pages) and emphasize that they never touch user-facing webpages.
• •State that PlayaYield does not grant or request additional user permissions and operates entirely within your existing extension scopes.
• •Reiterate that no personal data is collected or sold through these ad units and that users can disable monetization anytime via your extension settings.

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"
  },
  "permissions": ["storage"]
}

4Where 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',
  env: 'production'
});

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 },
  categories: ['tech', 'gaming']
});

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

createManagedRefreshableAd()

Use refreshable ads for long-lived surfaces like side panels. The SDK automatically refreshes ads every 40 seconds and enforces a 29-impression limit per rolling 30-minute session window. These values are managed internally and cannot be configured. The SDK appends the ad to your container and automatically cleans up when the element is removed from the DOM.

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

// Using CSS selector
const managed = await createManagedRefreshableAd({
  container: '#ad-slot',
  placement: 'sidebar',
  size: { width: 300, height: 250 }
});

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

// Check if active
if (managed.isActive()) {
  console.log('Ad is running');
}

// Manual cleanup (optional - auto-cleans when removed from DOM)
managed.stop();

Complete Integration Example

Here's a complete 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',
  env: 'production' // or 'test' for development
});

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 {
    const managed = await createManagedRefreshableAd({
      container: '#ad-slot',
      placement: 'sidebar',
      size: { width: 300, height: 250 }
    });

    console.log('Refreshable ad started');

    // Optional: Stop when user navigates away
    window.addEventListener('beforeunload', () => managed.stop());
  } 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: 'sidebar',
  size: { width: 300, height: 600 }
});

document.getElementById('sidebar-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: 728, height: 90 } })
]);

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. The SDK still calls your configured backend in test mode.

initializePlayaYield({
  apiKey: 'dev_test_key',
  env: 'test',
  // Optional: baseUrl: 'https://your-test-host.example'
});

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