Ads Module

This page explains how to integrate rewarded and interstitial ads using the Playol SDK. The SDK provides a streamlined monetization pipeline with automatic revenue tracking — no need for third-party ad networks, approval processes, or payout management. Everything is handled by the platform so you can focus on building your game.

---

📌 1. Use Cases

• Rewarded ads: Users watch a full video to earn a reward (e.g., revive, coins, items, retries);
• Interstitial ads: Shown after level completion, failure, or pause — generating passive revenue;
• The SDK automatically determines ad fill status, skip behavior, and completion;
• All ad flows invoke the afterAd callback, even if ads are skipped or unavailable;
• Revenue is attributed to the current game and processed by the platform;
• Default ad pacing: one request per 30 seconds (controlled by Google Ads logic).

---

🧩 2. Methods & Usage

🎥 Show Rewarded Ad

openRewardAd(callbacks)

Opens a rewarded ad. Users receive rewards after watching the full video.

window.playolSDK.ad.openRewardAd({
  beforeAd: () => console.log('Ad starting...'),
  adViewed: (duration) => console.log('Ad fully watched:', duration, 'seconds'),
  adDismissed: (duration) => console.log('Ad skipped, watched:', duration, 'seconds'),
  afterAd: (res) => console.log('Ad status:', res)
})

📌 Callback Reference:

Callback	Type	Description
beforeAd	() => void	Triggered before the ad plays
adViewed	(duration?: number)	Called when ad is fully watched
adDismissed	(duration?: number)	Called when user skips the ad
afterAd	(msg: adMsg)	Always triggered at ad completion

📦 adMsg Structure:

Field	Type	Description
status	`-1	0	1`	-1: Not filled / 0: Skipped / 1: Watched
msg	string	Status message
duration	number?	View duration (in seconds) if present

⚠️ You should only grant rewards when status === 1.

---

📺 Show Interstitial Ad

openNormalAd(callbacks)

Displays a standard interstitial ad (no rewards), e.g. after pause or level end.

window.playolSDK.ad.openNormalAd({
  beforeAd: () => console.log('Interstitial ad starting'),
  afterAd: (res) => console.log('Ad result:', res)
})

📌 Notes:

• Interstitials are non-skippable; no need to check ad status;
• afterAd is always called, even when no ad is filled.

---

✅ Unified Ad Entry

openAd(adType, callbacks)

A generic method to call either type of ad.

window.playolSDK.ad.openAd('reward', callbacks)

📦 adType Options:

Value	Description
'reward'	Rewarded video ad
'normal'	Interstitial ad

---

🧪 Adblock Detection

hasAdblock()

Detects if the current environment has an ad blocker enabled.

const isBlocked = await window.playolSDK.ad.hasAdblock()
if (isBlocked) {
  console.warn('Adblock detected. Consider prompting the user to disable it.')
}

📌 Tips:

• You may limit certain features (e.g., skins, bonuses) to encourage users to disable ad blockers;
• Ensure data is saved before prompting for a page refresh.

---

🛠️ 3. Recommended Use Patterns

Scenario	Recommended Method
Revive after failure	openRewardAd()
Bonus after level clear	openRewardAd()
Ad break after pause	openNormalAd()
Check for adblock usage	hasAdblock()

---

📦 4. FAQ

Q: Will afterAd trigger if the ad fails to show?

A: Yes. Whether the ad is skipped, unavailable, or completed, afterAd will always be called with a status.

Q: How are ad frequencies controlled?

A: Ad pacing (e.g., 30s cooldown) is managed internally by the ad provider. You only need to trigger ads appropriately.

Q: How are ad revenues settled?

A: Revenue is tracked per game and distributed by the platform. Earnings and payout information will be available in the developer dashboard.

Q: Do ad methods support Promises?

A: Currently, all ad methods use callbacks. Promise/async support is planned for future versions.

---

🔗 Related Docs

👉 User Module ｜ Game Module ｜ Payment Module ｜ Invite Module