PlayaYield SDK Documentation

ℹ️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.

1Quick Start

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"]
}

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. Can be called from any content script, popup, or page.

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

Common Use Cases

Real-world examples to get you started quickly.

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

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

// Create sidebar container
const sidebar = document.createElement('div');
sidebar.id = 'my-extension-sidebar';
document.body.appendChild(sidebar);

// Load ad
const { element } = await createAd({
  placement: 'sidebar',
  size: { width: 300, height: 600 }
});

sidebar.appendChild(element);

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

// Apply custom styles
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);

// Load multiple ads
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 display dummy ads without making real API calls or affecting your analytics.

initializePlayaYield({
  apiKey: 'dev_test_key',
  env: 'test' // Returns dummy placeholder ads
});

Error Handling

The SDK throws typed errors for different failure scenarios. Always wrap your ad requests in try-catch blocks.

try {
  const { element } = await createAd({
    placement: 'popup',
    size: { width: 300, height: 250 }
  });
  
  document.getElementById('ad-slot').appendChild(element);
} catch (error) {
  switch (error.name) {
    case 'NetworkError':
      console.log('Network request failed');
      break;
    case 'ConfigError':
      console.log('Invalid configuration');
      break;
    default:
      console.log('Unknown error:', error);
  }
}