> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama/guides/monetization/intrinsic-ads/javascript.md).
# JavaScript
{% file src="/files/DbclEB28aoqinqcbZ3zz" %}
## Guide
Complete guide for integrating intrinsic in-game ads with vanilla JavaScript, without a framework or game engine.
### Table of Contents
* Quick Start
* Basic Integration
* 2D Canvas Example
* WebGL Example
* Multiple Billboards
* Advanced Features
* Complete Examples
***
### Quick Start
#### Minimal HTML Setup
```html
Anzu Ads - Vanilla JS
```
***
### Basic Integration
#### 1. Initialize Anzu SDK
```javascript
// game.js
// Initialize Anzu (call once at startup)
AnzuCore.initialize({
appKey: "YOUR_ANZU_APP_KEY", // Get from Anzu dashboard
logLevel: 1, // 0=Debug, 1=Info, 2=Warn, 3=Error, 4=None
gdprConsentStatus: -1, // -1=unknown, 0=no consent, 1=consent
gdprConsentString: "", // Optional GDPR consent string
isCoppaRegulated: false // Set to true if COPPA applies
});
console.log("Anzu SDK initialized!");
```
#### 2. Create an Ad Billboard
```javascript
// Create an ad instance
const billboard = new AnzuAd({
channelName: "billboard_01", // Unique identifier
aspectRatio: 16 / 9, // Width / Height ratio
isDynamic: true, // Allow dynamic ad switching
isClickable: true, // Enable click interactions
allowVideo: true, // Allow video ads
allowAudio: false, // Mute videos (better for autoplay)
shrinkToFit: true // Adjust to maintain aspect ratio
});
// Initialize the billboard
billboard.initialize();
console.log("Billboard created:", billboard.getChannelName());
```
#### 3. Main Game Loop
```javascript
let lastTime = performance.now();
function gameLoop(currentTime) {
// Calculate delta time in seconds
const deltaTime = (currentTime - lastTime) / 1000;
lastTime = currentTime;
// Update Anzu SDK (required every frame)
AnzuCore.update(deltaTime);
// Get the ad canvas
const adCanvas = billboard.getCanvas();
if (adCanvas) {
// Use the canvas in your rendering
// (see examples below)
}
// Report visibility to Anzu
billboard.updateVisibility({
angle: 0, // Viewing angle (0-90 degrees)
visibility: 1.0, // Screen coverage (0-1)
viewability: 1.0 // Viewability score (0-1)
});
// Continue loop
requestAnimationFrame(gameLoop);
}
// Start the game loop
requestAnimationFrame(gameLoop);
```
***
### 2D Canvas Example
#### Complete 2D Billboard Implementation
```html
Anzu 2D Canvas Example
```
***
### WebGL Example
#### Complete WebGL Billboard Implementation
```html
Anzu WebGL Example
```
***
### Multiple Billboards
#### Managing Multiple Ad Placements
```javascript
// Billboard manager
class BillboardManager {
constructor() {
this.billboards = [];
}
createBillboard(config) {
const billboard = {
ad: new AnzuAd({
channelName: config.name,
aspectRatio: config.aspectRatio || 16/9,
isDynamic: true,
isClickable: true,
allowVideo: true,
allowAudio: false
}),
x: config.x || 0,
y: config.y || 0,
width: config.width || 400,
height: config.height || 225,
visible: true
};
billboard.ad.initialize();
this.billboards.push(billboard);
return billboard;
}
update(deltaTime) {
// Update all billboards
this.billboards.forEach(billboard => {
// Calculate visibility for each billboard
const visibility = this.calculateVisibility(billboard);
billboard.ad.updateVisibility({
angle: 0,
visibility: visibility,
viewability: visibility > 0 ? 1 : 0
});
});
}
render(ctx) {
this.billboards.forEach(billboard => {
if (!billboard.visible) return;
const adCanvas = billboard.ad.getCanvas();
if (adCanvas && adCanvas.width > 0) {
ctx.drawImage(
adCanvas,
billboard.x,
billboard.y,
billboard.width,
billboard.height
);
}
});
}
calculateVisibility(billboard) {
// Simple screen coverage calculation
const screenArea = window.innerWidth * window.innerHeight;
const billboardArea = billboard.width * billboard.height;
return Math.min(1, billboardArea / screenArea);
}
handleClick(x, y) {
// Check click against all billboards
for (const billboard of this.billboards) {
if (x >= billboard.x && x <= billboard.x + billboard.width &&
y >= billboard.y && y <= billboard.y + billboard.height) {
billboard.ad.interact();
return true;
}
}
return false;
}
destroy() {
this.billboards.forEach(b => b.ad.destroy());
this.billboards = [];
}
}
// Usage
const manager = new BillboardManager();
manager.createBillboard({
name: "top_banner",
x: 100,
y: 50,
width: 600,
height: 100,
aspectRatio: 6
});
manager.createBillboard({
name: "sidebar",
x: 50,
y: 200,
width: 200,
height: 200,
aspectRatio: 1
});
// In game loop
function gameLoop(deltaTime) {
AnzuCore.update(deltaTime);
manager.update(deltaTime);
manager.render(ctx);
}
```
***
### Advanced Features
#### 1. GDPR Consent Management
```javascript
// Check if user is in GDPR region
function isGDPRRegion() {
// Implement your own logic or use a service
return true; // Example
}
// Show consent dialog
function showConsentDialog() {
return new Promise((resolve) => {
// Your consent UI logic
const hasConsent = confirm("Do you consent to personalized ads?");
resolve(hasConsent ? 1 : 0);
});
}
// Initialize with GDPR
async function initializeWithGDPR() {
let consentStatus = -1; // Unknown
if (isGDPRRegion()) {
consentStatus = await showConsentDialog();
}
AnzuCore.initialize({
appKey: "YOUR_ANZU_APP_KEY",
logLevel: 1,
gdprConsentStatus: consentStatus,
gdprConsentString: "", // Optional CMP consent string
isCoppaRegulated: false
});
}
initializeWithGDPR();
```
#### 2. URI Schema Callbacks
```javascript
// Register custom URI scheme for deep linking
UriSchema.registerHook("myapp", (data) => {
console.log("URI callback triggered!");
console.log("Base URI:", data.baseUri);
console.log("Arguments:", data.arguments);
// Handle the callback
if (data.arguments.action === "product") {
const productId = data.arguments.id;
showProduct(productId);
}
});
function showProduct(productId) {
console.log("Showing product:", productId);
// Your product display logic
}
```
#### 3. Ad Statistics and Monitoring
```javascript
// Track ad performance
class AdMonitor {
constructor(anzuAd) {
this.ad = anzuAd;
this.startTime = Date.now();
}
getStats() {
const stats = this.ad.getChannelStats();
const uptime = (Date.now() - this.startTime) / 1000;
return {
channelName: this.ad.getChannelName(),
impressions: stats.impressions,
empties: stats.empties,
uptime: uptime.toFixed(1) + 's',
angle: this.ad.getAngle().toFixed(1),
visibility: (this.ad.getVisibility() * 100).toFixed(1) + '%',
viewability: (this.ad.getViewability() * 100).toFixed(1) + '%'
};
}
displayStats(ctx, x, y) {
const stats = this.getStats();
ctx.fillStyle = 'rgba(0, 0, 0, 0.7)';
ctx.fillRect(x, y, 200, 140);
ctx.fillStyle = '#00ff00';
ctx.font = '12px monospace';
let lineY = y + 20;
Object.entries(stats).forEach(([key, value]) => {
ctx.fillText(`${key}: ${value}`, x + 10, lineY);
lineY += 18;
});
}
}
// Usage
const monitor = new AdMonitor(billboard.ad);
// In render loop
monitor.displayStats(ctx, 10, 10);
```
#### 4. Responsive Billboards
```javascript
// Auto-resize billboards on window resize
function createResponsiveBillboard(config) {
const billboard = {
ad: new AnzuAd(config),
baseWidth: config.width,
aspectRatio: config.aspectRatio || 16/9,
scale: 1
};
billboard.ad.initialize();
// Calculate responsive size
function updateSize() {
const maxWidth = window.innerWidth * 0.8;
billboard.scale = Math.min(1, maxWidth / billboard.baseWidth);
billboard.width = billboard.baseWidth * billboard.scale;
billboard.height = billboard.width / billboard.aspectRatio;
}
updateSize();
window.addEventListener('resize', updateSize);
return billboard;
}
```
#### 5. Performance Optimization
```javascript
// Lazy update for off-screen billboards
class OptimizedBillboard {
constructor(config) {
this.ad = new AnzuAd(config);
this.ad.initialize();
this.isOnScreen = true;
this.updateInterval = 0;
}
update(deltaTime, isVisible) {
this.isOnScreen = isVisible;
if (isVisible) {
// Update every frame when visible
this.updateVisibility();
} else {
// Update less frequently when off-screen
this.updateInterval += deltaTime;
if (this.updateInterval >= 1.0) {
this.updateVisibility();
this.updateInterval = 0;
}
}
}
updateVisibility() {
this.ad.updateVisibility({
angle: 0,
visibility: this.isOnScreen ? 0.5 : 0,
viewability: this.isOnScreen ? 1 : 0
});
}
render(ctx, x, y, width, height) {
if (!this.isOnScreen) return;
const canvas = this.ad.getCanvas();
if (canvas) {
ctx.drawImage(canvas, x, y, width, height);
}
}
}
```
***
### Complete Examples
#### Example 1: Simple Billboard Game
```html
Billboard Runner
```
***
### Best Practices
#### 1. Initialization
* ✅ Initialize `AnzuCore` once at app startup
* ✅ Wait for initialization before creating ads
* ✅ Use appropriate log level for production (2-4)
#### 2. Performance
* ✅ Call `AnzuCore.update()` every frame
* ✅ Reuse canvas references, don't fetch every frame
* ✅ Update visibility only when billboard position/size changes
* ✅ Use `requestAnimationFrame` for smooth rendering
#### 3. Visibility Tracking
* ✅ Report accurate visibility (0-1 range)
* ✅ Set `viewability: 0` when billboard is off-screen
* ✅ Use `AnzuMath` utilities for complex calculations
* ✅ Update visibility every frame or when state changes
#### 4. Memory Management
* ✅ Call `ad.destroy()` when removing billboards
* ✅ Remove event listeners when cleaning up
* ✅ Clear references to destroyed ads
#### 5. Click Handling
* ✅ Implement proper hit testing
* ✅ Only call `interact()` when ad is clickable
* ✅ Verify billboard bounds before triggering interaction
***
### Troubleshooting
#### Ad not displaying
```javascript
// Debug checklist
console.log("Anzu initialized?", AnzuCore.isInitialized());
console.log("Canvas exists?", billboard.getCanvas() !== null);
console.log("Canvas size:", billboard.getTextureSize());
```
#### Visibility not tracking
```javascript
// Verify visibility reporting
const vis = billboard.getVisibility();
const view = billboard.getViewability();
console.log("Visibility:", vis, "Viewability:", view);
```
#### Click not working
```javascript
// Debug click detection
canvas.addEventListener('click', (e) => {
const rect = canvas.getBoundingClientRect();
const x = e.clientX - rect.left;
const y = e.clientY - rect.top;
console.log("Click at:", x, y);
console.log("Billboard bounds:", billboard.x, billboard.y, billboard.width, billboard.height);
});
```
***
### Resources
* **Main Documentation**: `README.md`
* **Migration Guide**: `MIGRATION_GUIDE.md`
* **Three.js Guide**: `examples/three-js/README.md`
* **Pixi.js Guide**: `examples/pixi-js/README.md`
* **Phaser Guide**: `examples/phaser-js/README.md`
* **Anzu Dashboard**:
***
### Support
For issues or questions:
1. Check the main `README.md`
2. Review error messages in browser console
3. Verify all SDK files are loaded in correct order
4. Contact Playgama support with your app key