Pi Network Ads

The Pi Network JS SDK provides a module for integrating native ads into your Pi app via the window.Pi.Ads namespace. This API enables you to show Pi-managed ad units in your web frontend using simple, promise-based methods. For a detailed explanation, please refer to the platform guide: Ads

Purpose

• Enable apps to programmatically show rewarded or interstitial ads in Pi Browser.
• Maintain compliance with Pi Network ad policies.
• Monetize or reward users with wallet-connected incentives.

Available Ad Types

• interstitial: Full-screen ads, typically shown between user actions (e.g., between game levels).
• rewarded: Ads that, once watched, allow the app to reward the user (e.g., unlock content, give discounts).

Overview

• Purpose: Manage/show platform advertisement units.
• Structure:

window.Pi.Ads.isAdReady(type)
window.Pi.Ads.requestAd(type)
window.Pi.Ads.showAd(type)

• type: 'interstitial'

  'rewarded'

• All methods are Promise-based.

window.Pi.Ads Methods

.isAdReady(type)

• Purpose: Checks if an ad unit of the specified type is available to show.
• Signature:

Pi.Ads.isAdReady('interstitial' | 'rewarded') : Promise<result>

• Returns: A promise that resolves to true if ad is available, otherwise false.

.requestAd(type)

• Purpose: Requests an ad of the given type from Pi Network. May cache/preload an ad for fastest showing.
• Signature:

Pi.Ads.requestAd('interstitial' | 'rewarded') : Promise<result>

• Returns: A promise resolved when the ad is preloaded/ready. If an ad is already ready, resolves immediately. Rejects if not available or request denied.

.showAd(type)

• Purpose: Shows an ad of the given type. Should be called only if isAdReady(type) returns true.
• Signature:

Pi.Ads.showAd('interstitial' | 'rewarded') : Promise<result>

• Returns: A promise resolved when the ad has finished showing, or rejected if unavailable, canceled, or failed.

Typical Usage Pattern

// Example: Show a rewarded ad, then give user a bonus
Pi.Ads.isAdReady('rewarded').then(function(ready) {
  if (ready) {
    Pi.Ads.showAd('rewarded').then(function(result) {
      // Ad finished! Give the user a reward
      grantUserBonus();
    }).catch(function(err) {
      // User canceled, ad failed, or unavailable
      alert('Could not show ad: ' + err.message);
    });
  } else {
    // Ad not ready; maybe preload
    Pi.Ads.requestAd('rewarded');
  }
});

Error Handling

• All ad methods return Promises; always use .catch to handle errors (ad not ready, request denied, unsupported type).
• Valid ad types: 'interstitial' and 'rewarded'. Any other string will reject with an error.

Best Practices

• Always check isAdReady(type) before showing an ad.
• Use requestAd(type) at app launch to preload ads for lowest latency.
• Handle edge cases (user cancels ad, ad fails to load) gracefully.
• Don’t spam ad requests or force user to watch too many ads per session (see Pi Network policy).
• Only reward users after successful completion of a rewarded ad.
• Do not attempt to show native ads outside Pi Browser; always feature-detect the available API.