Skip to content

SDK Reference

Jump to bottom
alxspiker edited this page Feb 26, 2024 · 9 revisions

Pi Network SDK Reference

Table of Contents

Introduction

The Pi Network SDK is a JavaScript library that allows developers to integrate Pi Network features into their web applications. The SDK provides a set of methods that can be used to authenticate users, create payments, open share dialogs, and more.

Installation

To install the Pi Network SDK, add the following script tag to your HTML document:

<script src="https://sdk.minepi.com/pi-sdk.js"></script>

Usage

Once the SDK is installed, you can initialize Pi:

Pi.init({ version: "2.0", sandbox: false }); //Set sandbox to true if deploying in a sandbox enviroment

The Pi class provides a number of methods that can be used to interact with Pi Network. For example, to authenticate a user, you can use the authenticate method:

// Authenticate the user, and get permission to request payments from them:
const scopes = ['payments'];

// Read more about this callback in the SDK reference:
function onIncompletePaymentFound(payment) { /* ... */ };

Pi.authenticate(scopes, onIncompletePaymentFound).then(function(auth) {
    console.log(`Hi there! You're ready to make payments!`);
}).catch(function(error) {
    console.error(error);
});

Sandbox Environment

(Development)

  • Purpose: The sandbox allows you to test and develop your app in a simulated environment before deploying it to production.
  • Configuration:
    • Set the sandbox: true flag in your SDK initialization.
    • Obtain your Sandbox URL from the Developer Portal.
  • Sandbox Authorization: Follow these steps:
    1. Open the Pi App on your mobile device.
    2. Navigate to Pi Utilities.
    3. Click "Authorize Sandbox" and follow the instructions.

Functions and Methods

Authentication

  • Pi.authenticate(scopes, callback): Authenticates the user and returns a promise that resolves to an object containing the user's data and an access token.
    • Parameters:
      • scopes: An array of scopes to request.
      • callback: A callback function that is called with the error and result of the authentication.
    • Returns: A promise that resolves to an object containing the user's data and an access token also known as an AuthResult Object.
    {"user":{"uid":"userid","credentials":{"scopes":["payments","platform"],"valid_until":{"timestamp":1709007140,"iso8601":"2024-02-27T04:12:20Z"}}},"accessToken":"accessToken"}
  • Pi.Error.auth(errorMessage): Reports an authentication error to the Pi Network platform.
    • Parameters:
      • errorMessage: The error message to report.
  • Pi.Error.unknown(errorMessage): Reports an unknown error to the Pi Network platform.
    • Parameters:
      • errorMessage: The error message to report.

App Presence

  • Pi.checkUserHasMiningApp(): Checks if the user has the Pi Mining App installed.
    • Parameters: None
    • Returns: A promise that resolves to a boolean indicating whether the user has the Pi Mining App installed.
    {"userHasMiningApp":true}
  • Pi.checkUserHasPiBrowser(): Checks if the user has the Pi Browser installed.
    • Parameters: None
    • Returns: A promise that resolves to a boolean indicating whether the user has the Pi Browser installed.
    {"userHasPiBrowser":true}

Clipboard

  • Pi.copyText(text): Copies the specified text to the clipboard.
    • Parameters:
      • text: The text to copy.
  • callback: A callback function that is called when the text has been copied.

Payments

  • Pi.createPayment(paymentData): Prepares a payment flow.
    • Parameters:
      • paymentData: The payment data.
      • callbacks: The payment data.
        • Callbacks you need to implement:
        • onReadyForServerApproval: function(paymentId) { /* ... */ }
        • onReadyForServerCompletion: function(paymentId, txid) { /* ... */ }
        • onCancel: function(paymentId) { /* ... */ }
        • onError: function(error, payment) { /* ... */ }
    • Returns: A promise that resolves to a PaymentDTO Object.
  • Pi.Payments.preparePaymentFlow(paymentData): Prepares a payment flow.
    • Parameters:
      • paymentData: The payment data.
    • Returns: A promise that resolves to the payment ID.
  • Pi.Payments.startPaymentFlow(paymentId): Starts a payment flow.
    • Parameters:
      • paymentId: The payment ID.
    • Returns: A promise that resolves when the payment flow has been started.
  • Pi.Payments.waitForTransaction(paymentId): Waits for a transaction to complete.
    • Parameters:
      • paymentId: The payment ID.
    • Returns: A promise that resolves to the transaction details.
  • Pi.Payments.showPrePaymentError(errorMessage): Shows a pre-payment error.
    • Parameters:
      • errorMessage: The error message to show.

App Info

  • Pi.getPiHostAppName(): Gets the name of the Pi host app.
    • Parameters: None
    • Returns: The name of the Pi host app.
  • Pi.getPiHostAppInfo(): Gets information about the Pi host app.
    • Parameters: None
    • Returns: A promise that resolves to an object containing the information about the Pi host app.
    {"hostApp":"pi-browser","appVersion":"1.8.0","os":"android","osVersion":"33","webviewVersion":"121.0"}

Initialization

  • Pi.init(options): Initializes the SDK.
    • Parameters:
      • options: The initialization options.
    • Returns: A promise that resolves when the SDK has been initialized.

Features

  • Pi.nativeFeaturesList(): Gets a list of the native features that are supported by the SDK.
    • Parameters: None
    • Returns: A promise that resolves to a list of the native features that are supported by the SDK.
    inline_media,request_permission,ad_network

User Actions

  • Pi.openConversation(conversationId): Opens a conversation with the specified conversation ID.
    • Parameters:
      • conversationId: The conversation ID.
    • Returns: A promise that resolves when the conversation has been opened.
  • Pi.openShareDialog(title, sharingMessage): Opens a share dialog with the specified title and sharing message.
    • Parameters:
      • title: The title of the share dialog.
      • sharingMessage: The sharing message.
    • Returns: A promise that resolves when the share dialog has been opened.
  • Pi.openUrlInSystemBrowser(url): Opens the specified URL in the system browser.
    • Parameters:
      • url: The URL to open.
    • Returns: A promise that resolves when the URL has been opened.
  • Pi.requestPermission(permission): Requests the specified permission.
    • Parameters:
      • permission: The permission to request.
    • Returns: A promise that resolves to a boolean indicating whether the permission was granted.
  • Pi.scanQrCode(config): Scans a QR code.
    • Parameters:
      • config: The configuration object.
    • Returns: A promise that resolves to the scanned data.

SDK

  • Pi.SDK.communicationInformationRequest(): Requests communication information from the host app.
    • Parameters: None
    • Returns: A promise that resolves to an object containing the communication information.
  • Pi.SDK.setThirdPartyAppUserId(userId): Sets the third-party app user ID.
    • Parameters:
      • userId: The third-party app user ID.
  • Pi.SDK.decideCallbackRetrial(callbackId, shouldRetry): Decides whether to retry a callback.
    • Parameters:
      • callbackId: The callback ID.
      • shouldRetry: Whether to retry the callback.
  • Pi.SDK.openConsentModal(): Opens the consent modal.
    • Parameters: None
  • Pi.SDK.requestHostAppInfo(): Requests information about the host app.
    • Parameters: None
    • Returns: A promise that resolves to an object containing the information about the host app.
  • Pi.SDK.checkNativeFeatures(): Checks for native features.
    • Parameters: None
    • Returns: A promise that resolves to a list of the native features that are supported by the SDK.
  • Pi.SDK.requestNativePermission(permission): Requests a native permission.
    • Parameters:
      • permission: The permission to request.
    • Returns: A promise that resolves to a boolean indicating whether the permission was granted.
  • Pi.SDK.isAdReady(type): Checks if an ad is ready to be shown.
    • Parameters:
      • type: The type of ad.
    • Returns: A promise that resolves to a boolean indicating whether the ad is ready to be shown.
  • Pi.SDK.requestAd(type): Requests an ad.
    • Parameters:
      • type: The type of ad.
    • Returns: A promise that resolves to an ad object.
  • Pi.SDK.showAd(type): Shows an ad.
    • Parameters:
      • type: The type of ad.

Code Examples

Authenticate a user:

// Authenticate the user, and get permission to request payments from them:
const scopes = ['payments'];

// Read more about this callback in the SDK reference:
function onIncompletePaymentFound(payment) { /* ... */ };

Pi.authenticate(scopes, onIncompletePaymentFound).then(function(auth) {
    console.log(`Hi there! You're ready to make payments!`);
}).catch(function(error) {
    console.error(error);
});

Create a payment:

Pi.Payments.createPayment({
    amount: 100,
    currency: 'USD',
    description: 'Test payment'
}, (error, result) => {
    if (error) {
        // Handle the error
    } else {
        // The payment has been created
    }
});

Open a conversation:

Pi.openConversation('1234567890', (error) => {
    if (error) {
        // Handle the error
    } else {
        // The conversation has been opened
    }
});

Open a share dialog:

Pi.openShareDialog(
    'Share this awesome content!',
    'This is some great content that you should check out.'
);

Open a URL in the system browser:

Pi.openUrlInSystemBrowser('https://minepi.com');

Request a permission:

Pi.requestPermission('storage', (hasPermission) => {
    if (hasPermission) {
        // The permission has been granted
    } else {
        // The permission has been denied
    }
});

Scan a QR code:

Pi.scanQrCode((error, result) => {
    if (error) {
        // Handle the error
    } else {
        // The QR code has been scanned
    }
});

NAVIGATION

REFERENCES

TOPICS

Terms

White Paper

Clone this wiki locally