本文档介绍了广告及其示例流程。有关 Pi SDK 提供的纯函数定义，请参阅SDK 参考文档的“广告”部分。
介绍
Pi 应用平台让开发者有机会将广告集成到他们的 Pi 应用中并获得奖励。Pi 生态系统中的所有应用都可以展示广告，但只有经过 Pi 核心团队批准的应用才能实现盈利。目前支持三种类型的广告：插页式广告、激励式广告和横幅广告。
插页式广告
插播广告是全屏广告，旨在显示在某些内容之间，通常是在自然过渡点或休息时间，例如在活动或游戏关卡之间。
从技术上讲，插页式广告可以随时显示，但请查看我们的最佳实践文档以了解更多信息。
激励广告
激励广告是全屏广告，旨在向用户展示，用户观看后可在开发者的应用内获得奖励。例如，如果您正在开发一款游戏应用，玩家的生命值耗尽但仍想继续游戏，您可以提供观看激励广告来获得额外生命值的选项。
由于激励广告旨在奖励用户，因此只有经过应用身份验证的用户才能看到它们
横幅广告
横幅广告是一种叠加式广告，会在用户使用应用时出现在屏幕顶部或底部。与全屏广告相比，横幅广告的干扰性更小，并且可以在应用使用过程中持续显示。横幅广告非常适合在不干扰用户体验的前提下，保持广告的持续曝光。
由于横幅广告始终可见，因此应将其放置在不会干扰应用程序主要内容或功能的非侵入性位置。
目前 Pi SDK不支持横幅广告，但您可以通过在开发者门户的广告设置中启用“加载中横幅广告”选项来使用此功能。加载中横幅广告会在您的应用加载时自动向用户显示。要了解更多信息，请参阅“启用加载中横幅广告”部分。
先决条件
要获得 Pi 开发者广告网络的奖励，您必须在 Pi 开发者门户网站上申请。提交申请后，Pi 核心团队将审核您的申请。
注意：根据您的应用是否已获准加入 Pi 开发者广告网络，广告模块的某些方法可能会返回略有不同的响应。这些差异在SDK 参考文档的方法定义中均有说明。
开发者广告网络应用程序
即将推出...
支持用户树莓派浏览器上的广告网络
您的用户可能正在使用旧版本的 Pi Browser，这些版本不支持开发者广告网络。您可以使用Pi.nativeFeaturesListSDK 方法确保广告网络可用，该方法会返回一个数组，列出给定 Pi Browser 版本上可用的原生功能。为了使广告正常运行，原生功能列表数组中必须包含ad_network字符串。
// you usually would check the ads support ahead of time and store the information
(async () => {
await Pi.init({ version: "2.0" });
const nativeFeaturesList = await Pi.nativeFeaturesList();
const adNetworkSupported = nativeFeaturesList.includes("ad_network");
// store adNetworkSupported for later use
})();如果ad_network缺少该功能，并且您想向用户展示广告，您可以鼓励他们更新 Pi 浏览器。
当 promises 从Pi.Ads.requestAdandPi.Ads.showAd方法返回并解析为时"ADS_NOT_SUPPORTED"，它等同"ad_network"于原生功能列表数组中缺少该功能。
有关上面使用的 Pi SDK 方法的详细定义，请转到SDK 参考。
执行
基本用法
Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在需要显示时重新加载。这旨在确保广告始终处于可显示状态。因此，在大多数情况下，您只需调用相应Pi.Ads.showAd()方法并将广告类型作为参数传递，即可向用户展示广告。
插页式广告
插页式广告易于集成，通常显示在一些过渡节点附近。例如，一款关卡制游戏应用可以每隔三关显示一次插页式广告。
// we pretend that the game app has just reached end of 3rd level according to above example
completeLevel();
if (currentLevel % 3 === 0) {
await Pi.Ads.showAd("interstitial");
}
startNewLevel();激励广告
激励广告旨在奖励观看广告的用户。以游戏应用为例，如果你的游戏给用户一定数量的生命值，而当他用完生命值时，你可以让他观看广告来换取一条额外的生命值。
激励广告的展示依然简单，但需要更多努力来确保安全性并验证用户是否应该获得奖励。该Pi.Ads.showAd("rewarded")方法返回一个带有额外字段的 Promise adId，您可以使用该字段根据 Pi Platform API 验证 Pi SDK 响应的有效性。
用户可能正在使用你的应用作弊！
展示激励广告后，用户应该能在您的应用中获得某种奖励。由于用户可能运行的是破解版的 SDK 并拦截您的displayAd('rewarded')方法，因此您必须在奖励用户之前，使用 Pi Platform API 验证广告的激励状态。
有关 Pi 平台 API 的文档，请参阅平台 API 文档。
mediator_ack_status只有当给定的广告有效时，才应该向用户提供奖励"granted"。
const showAdResponse = await Pi.Ads.showAd("rewarded");
if (showAdResponse.result === "AD_REWARDED") {
// delegate rewarding user to your backend
// e.g.:
const result = await rewardUserForWatchingRewardedAd(showAdResponse.adId);
if (result.rewarded === true) {
grantUserAdditionalLive();
}
}启用加载横幅广告
您可以在开发者门户启用加载中横幅广告。https://develop.pinet.com在 Pi 浏览器中找到您想要启用加载中横幅广告的应用。前往“开发者广告网络”菜单项，然后选择“设置”。从那里切换“启用加载中横幅广告”选项。您可以随时禁用它。
您的应用广告相关设置已被缓存，因此要看到效果，您可能需要等待或重置 Pi Browser 以使缓存失效。
高级用法
虽然上一节中的示例足以让您的应用程序开始向用户显示广告，但您可能会发现自己需要执行其他操作，例如手动请求广告或检查广告可用性。
在某些情况下，广告加载可能会失败或中断。如果您发现某个广告不可用，可以尝试手动调用函数，Pi.Ads.requestAd()并将广告类型作为参数传递。
在其他情况下，您可能需要在调用方法之前知道广告是否已准备就绪Pi.Ads.showAd()。您可以使用Pi.Ads.isAdReady()传递广告类型作为参数的方法来检查这一点。
有关 Pi SDK 方法及其所有可能响应类型的完整定义，请查看SDK 参考文档。
插页式广告高级使用方法
// we pretend that the game app has just reached end of 3rd level according to previous example
completeLevel();
if (currentLevel % 3 === 0) {
const isAdReadyResponse = await Pi.Ads.isAdReady("interstitial");
if (isAdReadyResponse.ready === true) {
return Pi.Ads.showAd("interstitial");
}
const requestAdResponse = await Pi.Ads.requestAd("interstitial");
if (requestAdResponse.result !== "AD_LOADED") {
// indicate to user that ad could not be loaded
return;
}
const showAdResponse = await Pi.Ads.showAd("interstitial");
if (showAdResponse.result !== "AD_CLOSED") {
// indicate to user that ad could not be displayed
return;
}
}
startNextLevel();如您所见，结合这 3 种方法，您可以在广告流程的任何步骤中对不愉快的路径做出反应。
激励广告高级使用
假设您已获准在您的应用上展示广告，以下是向用户展示广告的大致流程。
用户访问您的应用后，希望观看广告以获得奖励。
您的应用使用 Pi SDK 广告模块在应用内显示广告。
*有关 Pi SDK 方法的文档，请参阅SDK 参考。
使用adId从 SDK 方法获取的信息后，您需要从 Pi 服务器验证广告状态。详情请参见下一节。
*有关 Pi 平台 API 的文档，请参阅平台 API 文档。
验证通过后，即可奖励用户。
使用 Pi Platform API 进行激励广告状态验证
用户可能正在使用你的应用作弊！
展示激励广告后，用户应该能在您的应用中获得某种奖励。由于用户可能运行的是破解版的 SDK 并拦截您的displayAd('rewarded')方法，因此您必须在奖励用户之前，使用 Pi Platform API 验证广告的激励状态。
mediator_ack_status只有当给定的广告有效时，才应该向用户提供奖励"granted"。
const showRewardedAd = async () => {
try {
const isAdReadyResponse = await Pi.Ads.isAdReady("rewarded");
if (isAdReadyResponse.ready === false) {
const requestAdResponse = await Pi.Ads.requestAd("rewarded");
if (requestAdResponse.result === "ADS_NOT_SUPPORTED") {
// display modal to update Pi Browser
return showAdsNotSupportedModal();
}
if (requestAdResponse.result !== "AD_LOADED") {
// display modal ads are temporarily unavailable and user should try again later
return showAdUnavailableModal();
}
}
const showAdResponse = await Pi.Ads.showAd("rewarded");
if (showAdResponse.result === "AD_REWARDED") {
// reward user logic:
// usually delegate rewarding user to your backend which would
// firstly verify `adId` against Pi Platform API, then decide whether to
// reward the user and rewarded user if the rewarded ad status is confirmed
// e.g.:
const result = await rewardUserForWatchingRewardedAd(adId);
if (result.rewarded === true) {
showRewardedModal(result.reward);
} else {
showRewardFailModal(result.error);
}
} else {
// fallback logic
showAdErrorModal();
}
} catch (err) {
// good practice to handle any potential errors
}
};
Pi 打赏
微信打赏