@playanext/playa-yield-sdk

Production-ready Chrome Extension Ad Monetization SDK for Manifest V3

A lightweight, fully TypeScript-based SDK that allows Chrome extension developers to easily display ads and earn money through the PlayaYield platform. Built from the ground up for Manifest V3 compliance with zero remote script execution.


✨ Features

- 🚀 Manifest V3 Compliant - No remote script execution, all code bundled
- 📦 Lightweight - < 35 KB minified and tree-shakeable
- 🔒 Secure - All network requests routed through background service worker
- 🎯 Type-Safe - Full TypeScript support with excellent IDE autocomplete
- 🎨 Flexible - Returns ready-to-append HTML elements for full styling control
- 📊 Auto-Tracking - Automatic impression and click tracking with sendBeacon
- ✅ Consent-Ready - Built-in support for user consent callbacks
- 🧪 Environment Support - Configure test vs production via env and/or baseUrl

📦 Installation

``bash
npm install @playanext/playa-yield-sdk
`

🚀 Quick Start

$3

In your background.ts:

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

// Initialize PlayaYield with your configuration
initializePlayaYield({
apiKey: 'your-api-key',
env: 'production',
consentCallback: async () => {
// Check user consent here
return await checkUserConsent();
},
});
`

$3

Add the background service worker:

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

$3

In your content script, popup, or options page:

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

// No initialization needed! Just use createAd directly
const { element, impressionId } = await createAd({
placement: 'banner',
size: { width: 300, height: 250 },
categories: ['tech', 'gaming'],
});

// Append to your DOM
document.getElementById('ad-slot')!.appendChild(element);
`

📚 API Reference

$3

Initialize the PlayaYield SDK in your background service worker. Call this once with your API key and configuration.

Parameters:

`typescript
interface SDKConfig {
apiKey: string; // Your PlayaYield API key (required)
env?: 'production' | 'test'; // Environment mode (default: 'production')
baseUrl?: string; // Custom API URL (optional, default: https://www.playayield.com)
}
`

Example:

`typescript
// background.ts
import { initializePlayaYield } from '@playanext/playa-yield-sdk';

initializePlayaYield({
apiKey: 'prod_abc123xyz',
env: 'production',
});
`

---

$3

Request and create an ad element. Returns a ready-to-append div element containing the ad HTML.

No initialization needed - just call this function from any content script, popup, or page. The SDK configuration is stored in the background worker.

Parameters:

`typescript
interface AdOptions {
placement: 'internal' | 'popup' | 'sidebar' | string; // Ad placement type
size: { width: number; height: number }; // Ad dimensions
categories?: string[]; // Optional targeting
[key: string]: any; // Custom metadata
}
`

Returns:

`typescript
interface AdResult {
element: HTMLDivElement; // Ready-to-append div element
impressionId: string; // Unique impression ID
clickUrl?: string; // Optional click-through URL
}
`

Example:

`typescript
try {
const { element, impressionId } = await createAd({
placement: 'internal',
size: { width: 300, height: 250 },
categories: ['tech', 'productivity'],
});

document.getElementById('ad-container')!.appendChild(element);
console.log('Ad displayed:', impressionId);
} catch (error) {
console.error('Failed to load ad:', error);
}
`

🎯 Common Use Cases

$3

`typescript
// popup.ts
import { createAd } from '@playanext/playa-yield-sdk';

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

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

$3

`typescript
// content.ts
import { createAd } from '@playanext/playa-yield-sdk';

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

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

sidebar.appendChild(element);
`

$3

`typescript
// Load multiple ads
const [ad1, ad2] = await Promise.all([
createAd({ placement: 'internal', size: { width: 300, height: 250 } }),
createAd({ placement: 'internal', size: { width: 300, height: 250 } }),
]);

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

$3

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

// Apply custom styles to the div 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);
`

🧪 Test Mode

Use test mode during development to point your extension at a PlayaYield test environment.

`typescript
// background.ts
import { initializePlayaYield } from '@playanext/playa-yield-sdk';

initializePlayaYield({
apiKey: 'dev_test_key',
env: 'test',
// If PlayaYield provides you a dedicated test API URL, set it here:
// baseUrl: 'https://'
});
`

Then in your content scripts/popups:

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

Note: The SDK does not generate local placeholder creatives in test mode. It still requests ads from the configured backend.

📊 Tracking

The SDK automatically tracks impressions and clicks:

- Impressions: Tracked when the ad element loads
- Clicks: Tracked when the user clicks on the ad

All tracking uses navigator.sendBeacon for fire-and-forget reliability, with automatic fallback to fetch if needed.

🏗️ Build Configuration

The SDK is built with tsup and outputs:

- ESM: dist/index.mjs
- CJS: dist/index.js
- Types: dist/index.d.ts

All formats are tree-shakeable and optimized for minimal bundle size.

🔧 Advanced Configuration

$3

`typescript
// background.ts
initializePlayaYield({
apiKey: 'your-api-key',
baseUrl: 'https://custom-api.example.com',
});
`

🐛 Error Handling

The SDK throws typed errors for different failure scenarios:

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

try {
await createAd({ placement: 'internal', size: { width: 300, height: 250 } });
} 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);
}
}
`

📝 Complete Example

See the example/ directory for a complete working Chrome extension that demonstrates:

- Background service worker setup
- Popup with ad display
- User controls for placement and size
- Error handling and status messages
- Beautiful UI with modern styling

To run the example:

`bash
cd example
npm install
npm run build
`

Then load the example/` directory as an unpacked extension in Chrome.

🤝 Support

- Documentation: https://docs.playanext.com
- API Reference: https://api.playanext.com/docs
- Issues: GitHub Issues
- Email: support@playanext.com

📄 License

MIT © PlayaYield

---

Made with ❤️ for Chrome extension developers