How to activate the donation feature?

@blocklet/payment-react offers a robust tipping and donation feature. Using the CheckoutDonate component and the optional DonateProvider, developers can easily integrate donation support for articles, content, and other services, seamlessly leveraging Blocklet's payment infrastructure.

This guide details how to enable tipping, including installing dependencies and integrating the necessary code.

Step 1: Install the Payment Kit

Payment Kit powers the tipping feature. You need to download and install Payment Kit from the Blocklet Store:

Test Store

Payment Kit

Store

Payment Kit

Installation

Visit the link above to select the appropriate store for your environment (test or production).
Download and deploy the Payment Kit to your Blocklet application.
After installation, retrieve the session and connectApi configurations to connect to the Payment Kit's authentication and payment services.

Note: Use the test store for development and debugging, and the production store for production environments. Ensure your Payment Kit is running and communicating with your front-end application.

Step 2: Install the @blocklet/payment-react package

Install the component library in your React project:

npm install @blocklet/payment-react

Step 3: Integrate the tipping component

You can integrate tipping functionality in two ways, depending on your needs:

Method 1: Basic Usage — CheckoutDonate

Use the CheckoutDonate component directly for a simple, pre-configured donation integration.

import { PaymentProvider, CheckoutDonate } from '@blocklet/payment-react';

function DonationButton() {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutDonate
        settings={{
          target: "post-123", // Required: Unique identifier for the donation instance (e.g., post ID)
          title: "支持作者", // Required: Title of the donation popup
          description: "如果这篇文章对你有帮助，不妨请我喝杯咖啡", // Required: Description for the donation
          reference: "https://your-site.com/posts/123", // Required: Reference link for the donation
          beneficiaries: [
            {
              address: "tip user did", // Required: Beneficiary address (replace with actual DID)
              share: "100", // Required: Percentage for the beneficiary
            },
          ],
          amount: {
            presets: ['1', '5', '10'], // Predefined donation amounts
            custom: false, // Whether to allow users to enter a custom amount
          },
          appearance: {
            button: {
              text: '打赏', // Text displayed on the button
              icon: '<Like />', // Custom icon (replace with actual JSX component)
              size: 'large', // Button size
              color: 'error', // Button color
              variant: 'contained', // Button style
            },

            history: {
              variant: 'default', // Display style for donation history
            },
          },
        }}
      />
    </PaymentProvider>
  );
}

export default DonationButton;

Method 2: Advanced Usage — DonateProvider (Recommended)

From Payment Kit version 1.18.7 onward, DonateProvider allows centralized management of donation settings and activation status within Payment Kit, simplifying front-end code and facilitating dynamic control over donations.

import { PaymentProvider, DonateProvider, CheckoutDonate } from '@blocklet/payment-react';

function DonationButton() {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <DonateProvider mountLocation="your-unique-donate-instance" description="Help locate this donation instance">
        <CheckoutDonate
          settings={{
            target: "post-123", // Required: Unique identifier
            title: "Support Author", // Required: Modal title
            description: "Buy me a coffee if this helped!", // Required: Description
            reference: "https://your-site.com/posts/123", // Required: Reference link
            beneficiaries: [{ address: "tip user did", share: "100" }], // Required: Beneficiaries
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}

export default DonationButton;

Configuration

target: A unique string identifying the reward recipient (e.g., an article or other content).
beneficiaries.address: Replace with the actual beneficiary's DID.
DonateProvider: Requires Payment Kit version 1.18.7 or later for integrated management.

Important Considerations

Version Compatibility: To use DonateProvider, you must use Payment Kit version 1.18.7 or later. Otherwise, use the basic method.