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

This guide demonstrates how to integrate the Pi SDK into many application frameworks. This example shows how to initialize the Pi SDK, authenticate a Pioneer, and create a payment request inside a Pi app.

The pi-sdk-js package is part of the “Ten Minutes to Transactions” effort described in this video.

If you, or your GenAI agent, are planning to use the Pi SDK modules in this documentation for your app, it is highly suggested that you use this package rather than implement transaction processing by hand with the core Pi SDK. The three way handshake between client, server, and the Pi servers required is provded for you.

Note: Pi SDK authentication and payment features require the application to run inside the Pi Browser.

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.