客户端 SDK 参考

初始化

script在所有需要调用 Pi Apps SDK 的页面中添加以下标签：

<script src="https://sdk.minepi.com/pi-sdk.js"></script>
<script>
  Pi.init({ version: "2.0" });
</script>

传递给 init 函数的 config 对象接受以下键：

• version（字符串，必填） - 此项为必填项，用于确保您的应用与可能带来重大变更的新 SDK 版本兼容（在这种情况下，重大变更将在更高的版本号下实现）。

• sandbox: (布尔值，可选) - 这允许您配置 SDK 在沙箱中运行。

在沙盒模式下使用 SDK：

<script src="https://sdk.minepi.com/pi-sdk.js"></script>
<script>
  Pi.init({ version: "2.0", sandbox: true });
</script>

您现在可以在沙盒环境 ( https://sandbox.minepi.com ) 中运行您的应用程序，前提是您已在开发者门户中配置了开发 URL。要配置此 URL 并查看您的沙盒 URL，请在 Pi 浏览器中打开 develop.pi 访问开发者门户。

通常情况下，如果您使用的框架或样板支持此功能，您应该能够设置沙箱标志以匹配您的开发环境。例如，大多数优秀的 Node 样板会将 `--sandbox-mode` 的值设置process.env.NODE_ENV为 `--sandbox-mode`"development"或`--sandbox "production"-mode`，您可以执行类似这样的操作： Pi.init({ version: "2.0", sandbox: <%= process.env.NODE_ENV !== 'production' %> })`--sandbox-mode`。这取决于您的设置，但通常情况下，当您的应用程序在开发环境中运行时，Pi SDK 就会以沙箱模式运行。

验证

警告：通过此方法获取的用户信息不应传递到后端，而应仅用于展示逻辑（例如显示用户名）。 后端应使用平台 API 作为权威数据源。您可以使用通过此方法获取的访问令牌，通过后端请求 `/me` 端点来验证用户身份。

Pi.authenticate(scopes: Array<Scope>, onIncompletePaymentFound: Function<PaymentDTO>): Promise<AuthResult>

返回值：

type AuthResult = {
  accessToken: string;
  user: {
    uid: string;
    username: string;
  };
};

scopes

可用范围：username，，paymentswallet_address

以下是对象上各种可用键的详细说明AuthResult['user']，以及这些键存在所需的作用域：

onIncompletePaymentFound

签名：(payment: PaymentDTO) => void

每次用户通过身份验证并尝试启动新的支付流程时，SDK 都会检查该用户是否存在未完成的支付。在此上下文中，未完成的支付是指已提交到 Pi 区块链但尚未处理的支付status.developer_completed（false即开发者尚未调用 /complete该支付的端点）。

如果发现付款不完整，则会调用此回调函数并传入付款信息PaymentDTO。

当此回调被调用时，您有责任完成相应的付款（您很可能需要将付款 DTO 发送到您的服务器，并根据您的业务逻辑进行处理）。您需要在向用户请求新的付款之前完成此操作。

付款

创建新的付款方式：

type PaymentData = {
  amount: number,
  memo: string,
  metadata: Object,
};
type PaymentCallbacks = {
  onReadyForServerApproval: (paymentId: string) => void,
  onReadyForServerCompletion: (paymentId: string, txid: string) => void,
  onCancel: (paymentId: string) => void,
  onError: (error: Error, payment?: PaymentDTO) => void,
};
Pi.createPayment(paymentData: PaymentData, callbacks: PaymentCallbacks): void;

该createPayment方法接受两个参数：paymentData和callbacks。

它将立即启动支付流程，该流程将在您的应用程序顶部打开，使用户能够查看付款并提交区块链交易，或拒绝该交易。

警告：同时进行多笔付款：

创建新付款时，如果当前用户已在您的应用中存在未结付款：

如果用户尚未完成区块链交易，则未完成的付款将被取消。

如果用户已经进行了区块链交易，则新的付款将被拒绝（onError将调用），并且onIncompletePaymentFound传递给该authenticate 方法的回调函数将使用现有的付款进行调用（使用此回调函数来解决此问题，例如，将先前的付款发送到您的服务器以完成服务器端操作）。

paymentData关键信息：

amount

这是用户需要向您的应用支付的金额。

例子：3.1415。

memo

本次付款的备注。此备注将在付款确认页面对用户可见。请在此处简要说明用户付款的用途。

例子：Digital kitten #1234。

metadata

您可以将此任意 JavaScript 对象附加到此付款。此对象仅供您自己使用。您应该使用此对象将此付款与您的内部业务逻辑关联起来。

例子：{ orderId: 1234, itemIds: [11, 42, 314] }

callbacks关键信息：

onReadyForServerApproval

签名：(paymentId: string) => void

当从 Pi 服务器获取到支付标识符 (paymentId) 时，会调用此函数。在审批期间，如果审批失败，此回调函数将被多次调用。如果初始尝试失败，Pi SDK 将继续大约每 10 秒调用一次该函数，直到审批计时器结束。

使用此回调函数将 paymentId 发送到您的后端进行服务器端审批。有关服务器端审批和完整支付流程的更多信息，请参阅专门的 “支付”页面。

onReadyForServerCompletion

签名：(paymentId: string, txid: string) => void

当用户将交易提交到 Pi 区块链后，会调用此函数。在完成期间，如果交易失败，此回调函数将被多次调用。如果初始尝试失败，Pi SDK 将继续大约每隔 10 秒调用一次该函数，直到完成计时器结束。

使用此回调函数将区块链交易标识符 (txid) 和支付 ID 发送到您的后端，以便进行服务器端完成。有关服务器端完成和完整支付流程的更多信息，请参阅专门的 “支付”页面。

onCancel

签名：(paymentId: string) => void

当付款被取消时（无论是用户操作还是通过程序取消），都会调用此函数。

付款可能因用户手动拒绝而取消，也可能因其他阻止情况而取消：例如，用户账户余额不足无法支付，或者同时创建了另一笔付款……

onError

签名：(error: Error, payment?: PaymentDTO) => void

当发生错误且无法完成付款时，将调用此函数。如果付款已创建，则会提供第二个参数，您可以使用该参数来调查错误。否则，只会提供第一个参数。

类型PaymentDTO

onIncompletePaymentFound这种类型用于传递给和的参数onError。

type PaymentDTO = {
  // Payment data:
  identifier: string; // payment identifier
  user_uid: string; // user's app-specific ID
  amount: number; // payment amount
  memo: string; // a string provided by the developer, shown to the user
  metadata: Object; // an object provided by the developer for their own usage
  from_address: string; // sender address of the blockchain transaction
  to_address: string; // recipient address of the blockchain transaction
  direction: Direction; // direction of the payment
  created_at: string; // payment's creation timestamp
  network: AppNetwork; // a network of the payment
  // Status flags representing the current state of this payment
  status: {
    developer_approved: boolean; // Server-Side Approval
    transaction_verified: boolean; // blockchain transaction verified
    developer_completed: boolean; // server-Side Completion
    cancelled: boolean; // cancelled by the developer or by Pi Network
    user_cancelled: boolean; // cancelled by the user
  };
  // Blockchain transaction data:
  transaction: null | {
    // This is null if no transaction has been made yet
    txid: string; // id of the blockchain transaction
    verified: boolean; // true if the transaction matches the payment, false otherwise
    _link: string; // a link to the operation on the Blockchain API
  };
};

类型Direction

开发者可以通过这种类型检查付款方向。

type Direction = "user_to_app" | "app_to_user";

类型AppNetwork

显示付款正在使用的网络。

type AppNetwork = "Pi Network" | "Pi Testnet";

类型Scope

您可以向用户请求权限。

type Scope = "username" | "payments" | "wallet_address";

原生功能列表

使用此方法可获取用户正在使用的特定版本 Pi Browser 的可用原生功能列表。某些 SDK 功能可能需要特定版本才能正常工作。

type NativeFeature = "inline_media" | "request_permission" | "ad_network";
Pi.nativeFeaturesList(): Promise<Array<NativeFeature>>;

分享对话框

打开原生共享对话框：

Pi.openShareDialog(title: string, message: string): void;

使用此方法打开原生分享对话框（由手机操作系统提供），使用户能够与朋友分享您应用中的内容。

• title：所分享消息的标题

• message当用户在共享流程中选择目标应用时，将发送此消息。

广告

SDK 包含一个Ads模块（对象），允许开发者向用户展示广告。它提供了多种方法，可用于插页式广告和激励广告。所有方法都利用了基于 Promise 的异步特性。

type AdType = "interstitial" | "rewarded";

显示广告

使用showAd(adType: "interstitial" | "rewarded")此方法向用户展示广告。它返回一个 Promise，该 Promise 会解析为以下类型的对象ShowAdResponse：

type ShowAdResponse =
  | {
      type: "interstitial";
      result: "AD_CLOSED" | "AD_DISPLAY_ERROR" | "AD_NETWORK_ERROR" | "AD_NOT_AVAILABLE";
    }
  | {
      type: "rewarded";
      result: "AD_REWARDED" | "AD_CLOSED" | "AD_DISPLAY_ERROR" | "AD_NETWORK_ERROR" | "AD_NOT_AVAILABLE" | "ADS_NOT_SUPPORTED" | "USER_UNAUTHENTICATED";
      adId?: string;
    };
Pi.Ads.showAd(adType: AdType): Promise<ShowAdResponse>

• "AD_NOT_AVAILABLE"表示广告加载失败。

• "AD_CLOSED"表示广告已成功展示并关闭。

• "AD_REWARDED"表示广告已成功展示并获得奖励（仅适用于rewarded广告）。

• "AD_DISPLAY_ERROR"表示广告已成功加载但未能显示。

• "AD_NETWORK_ERROR"这表明用户可能遇到了网络连接问题。

• "ADS_NOT_SUPPORTED"- 表示用户使用的应用版本不支持广告，

• "USER_UNAUTHENTICATED"- 表示用户未经身份验证，因此无法显示激励广告（仅限rewarded广告）。

Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在每次显示时重新加载。这确保广告始终处于可显示状态。然而，在极少数情况下，广告加载可能会中断，或者第三方应用可能会showAd()过快地使用方法（甚至在下一个广告准备就绪之前）。为了方便开发者处理这些情况，Pi SDK 提供了额外的方法：isAdReady()和requestAd()。

笔记：

• 如果您的应用已获 Pi Developer Ad Network 批准，则响应Pi.Ads.showAd('rewarded')中将包含其他adId字段，您可以使用 Pi Platform API 验证奖励状态。

• 如果您的申请未获 Pi 开发者广告网络批准，则响应adId中将缺少该字段Pi.Ads.showAd('rewarded')。您不应在未adId使用Pi 平台 API进行验证的情况下向用户发放奖励。

检查广告是否已准备就绪

使用此isAdReady(adType: "interstitial" | "rewarded")方法检查特定类型的广告是否可用。此方法返回一个 Promise，该 Promise 会解析为IsAdReadyResponse.

type IsAdReadyResponse = {
  type: "interstitial" | "rewarded";
  ready: boolean;
};
Pi.Ads.isAdReady(adType: AdType): Promise<IsAdReadyResponse>

Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在每次显示时重新加载。这确保广告始终处于可显示状态。然而，在极少数情况下，广告加载可能会中断，或者第三方应用可能会showAd()过快地使用方法（甚至在下一个广告准备就绪之前）。为了解决此类问题，Pi SDK 提供了此方法，允许开发者显式地检查广告的可用性。

请求广告

使用requestAd(adType: "interstitial" | "rewarded")此方法请求插页式广告或激励广告。它返回一个 Promise，该 Promise 会解析为以下类型的对象RequestAdResponse：

type RequestAdResponse = {
  type: "interstitial" | "rewarded";
  result: "AD_LOADED" | "AD_FAILED_TO_LOAD" | "AD_NOT_AVAILABLE";
};

Pi.Ads.requestAd(adType: AdType): Promise<RequestAdResponse>

与广告可用性策略一样，Pi 浏览器内部会管理请求新广告以替换已显示广告的过程。虽然不能保证广告始终可用，但开发者可以使用requestAd()方法手动重试广告请求，以防请求返回的 Promise 解析isAdReady()失败false。

在系统浏览器中打开 URL

请使用系统浏览器而不是 Pi Browser 打开 URL。

Pi.openUrlInSystemBrowser(url: string): Promise<void>

该方法返回一个 Promise，当 URL 成功打开时，该 Promise 会被解析；Error如果出现错误，则会被拒绝。可能的错误信息包括：

• "Failed to open URL"这表明系统浏览器无法打开该网址，可能是由于网址错误造成的。

• "No minimal requirements"这表明最终用户使用的是较旧版本的Pi浏览器，该版本不支持此SDK方法。

• "Unexpected error"

根据错误信息，您可以在应用程序中针对每种错误情况采取不同的处理方式。但是，如果收到"No minimal requirements"错误提示，强烈建议您鼓励用户更新 Pi 浏览器。

打赏 Pi 打赏 微信打赏