@capgo/native-purchases
TypeScript icon, indicating that this package has built-in type declarations

6.0.33 • Public • Published

native-purchases

Capgo - Instant updates for capacitor

In-app Purchases Made Easy

This plugin allows you to implement in-app purchases and subscriptions in your Capacitor app using native APIs.

Install

npm install @capgo/native-purchases
npx cap sync

Android

Add this to manifest

<uses-permission android:name="com.android.vending.BILLING" />

Usage

Import the plugin in your TypeScript file:

import { NativePurchases } from '@capgo/native-purchases';

Check if billing is supported

Before attempting to make purchases, check if billing is supported on the device: We only support Storekit 2 on iOS (iOS 15+) and google play on Android

const checkBillingSupport = async () => {
  try {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (isBillingSupported) {
      console.log('Billing is supported on this device');
    } else {
      console.log('Billing is not supported on this device');
    }
  } catch (error) {
    console.error('Error checking billing support:', error);
  }
};

Get available products

Retrieve information about available products:

const getAvailableProducts = async () => {
  try {
    const { products } = await NativePurchases.getProducts({
      productIdentifiers: ['product_id_1', 'product_id_2'],
      productType: PURCHASE_TYPE.INAPP // or PURCHASE_TYPE.SUBS for subscriptions
    });
    console.log('Available products:', products);
  } catch (error) {
    console.error('Error getting products:', error);
  }
};

Purchase a product

To initiate a purchase:

const purchaseProduct = async (productId: string) => {
  try {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: productId,
      productType: PURCHASE_TYPE.INAPP // or PURCHASE_TYPE.SUBS for subscriptions
    });
    console.log('Purchase successful:', transaction);
    // Handle the successful purchase (e.g., unlock content, update UI)
  } catch (error) {
    console.error('Purchase failed:', error);
  }
};

Restore purchases

To restore previously purchased products:

const restorePurchases = async () => {
  try {
    const { customerInfo } = await NativePurchases.restorePurchases();
    console.log('Restored purchases:', customerInfo);
    // Update your app's state based on the restored purchases
  } catch (error) {
    console.error('Failed to restore purchases:', error);
  }
};

Example: Implementing a simple store

Here's a basic example of how you might implement a simple store in your app:

import { Capacitor } from '@capacitor/core';
import { NativePurchases, PURCHASE_TYPE, Product } from '@capgo/native-purchases';

class Store {
  private products: Product[] = [];

  async initialize() {
    if (Capacitor.isNativePlatform()) {
      try {
        await this.checkBillingSupport();
        await this.loadProducts();
      } catch (error) {
        console.error('Store initialization failed:', error);
      }
    }
  }

  private async checkBillingSupport() {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) {
      throw new Error('Billing is not supported on this device');
    }
  }

  private async loadProducts() {
    const productIds = ['premium_subscription', 'remove_ads', 'coin_pack'];
    const { products } = await NativePurchases.getProducts({
      productIdentifiers: productIds,
      productType: PURCHASE_TYPE.INAPP
    });
    this.products = products;
  }

  getProducts() {
    return this.products;
  }

  async purchaseProduct(productId: string) {
    try {
      const transaction = await NativePurchases.purchaseProduct({
        productIdentifier: productId,
        productType: PURCHASE_TYPE.INAPP
      });
      console.log('Purchase successful:', transaction);
      // Handle the successful purchase
      return transaction;
    } catch (error) {
      console.error('Purchase failed:', error);
      throw error;
    }
  }

  async restorePurchases() {
    try {
      const { customerInfo } = await NativePurchases.restorePurchases();
      console.log('Restored purchases:', customerInfo);
      // Update app state based on restored purchases
      return customerInfo;
    } catch (error) {
      console.error('Failed to restore purchases:', error);
      throw error;
    }
  }
}

// Usage
const store = new Store();
await store.initialize();

// Display products
const products = store.getProducts();
console.log('Available products:', products);

// Purchase a product
try {
  await store.purchaseProduct('premium_subscription');
  console.log('Purchase completed successfully');
} catch (error) {
  console.error('Purchase failed:', error);
}

// Restore purchases
try {
  await store.restorePurchases();
  console.log('Purchases restored successfully');
} catch (error) {
  console.error('Failed to restore purchases:', error);
}

This example provides a basic structure for initializing the store, loading products, making purchases, and restoring previous purchases. You'll need to adapt this to fit your specific app's needs, handle UI updates, and implement proper error handling and user feedback.

Backend Validation

It's crucial to validate receipts on your server to ensure the integrity of purchases. Here's an example of how to implement backend validation using a Cloudflare Worker:

Cloudflare Worker Setup Create a new Cloudflare Worker and follow the instructions in folder (validator)[/validator/README.md]

Then in your app, modify the purchase function to validate the receipt on the server:

import { Capacitor } from '@capacitor/core';
import { NativePurchases, PURCHASE_TYPE, Product, Transaction } from '@capgo/native-purchases';
import axios from 'axios'; // Make sure to install axios: npm install axios

class Store {
  // ... (previous code remains the same)

  async purchaseProduct(productId: string) {
    try {
      const transaction = await NativePurchases.purchaseProduct({
        productIdentifier: productId,
        productType: PURCHASE_TYPE.INAPP
      });
      console.log('Purchase successful:', transaction);
      
      // Immediately grant access to the purchased content
      await this.grantAccess(productId);
      
      // Initiate server-side validation asynchronously
      this.validatePurchaseOnServer(transaction).catch(console.error);
      
      return transaction;
    } catch (error) {
      console.error('Purchase failed:', error);
      throw error;
    }
  }

  private async grantAccess(productId: string) {
    // Implement logic to grant immediate access to the purchased content
    console.log(`Granting access to ${productId}`);
    // Update local app state, unlock features, etc.
  }

  private async validatePurchaseOnServer(transaction: Transaction) {
    const serverUrl = 'https://your-server-url.com/validate-purchase';
    try {
      const response = await axios.post(serverUrl, {
        transactionId: transaction.transactionId,
        platform: Capacitor.getPlatform(),
        // Include any other relevant information
      });

      console.log('Server validation response:', response.data);
      // The server will handle the actual validation with the Cloudflare Worker
    } catch (error) {
      console.error('Error in server-side validation:', error);
      // Implement retry logic or notify the user if necessary
    }
  }
}

// Usage remains the same
const store = new Store();
await store.initialize();

try {
  await store.purchaseProduct('premium_subscription');
  console.log('Purchase completed successfully');
} catch (error) {
  console.error('Purchase failed:', error);
}

Now, let's look at how the server-side (Node.js) code might handle the validation:

import express from 'express';
import axios from 'axios';

const app = express();
app.use(express.json());

const CLOUDFLARE_WORKER_URL = 'https://your-cloudflare-worker-url.workers.dev';

app.post('/validate-purchase', async (req, res) => {
  const { transactionId, platform } = req.body;

  try {
    const endpoint = platform === 'ios' ? '/apple' : '/google';
    const validationResponse = await axios.post(`${CLOUDFLARE_WORKER_URL}${endpoint}`, {
      receipt: transactionId
    });

    const validationResult = validationResponse.data;

    // Process the validation result
    if (validationResult.isValid) {
      // Update user status in the database
      // await updateUserStatus(userId, 'paid');
      
      // Log the successful validation
      console.log(`Purchase validated for transaction ${transactionId}`);
      
      // You might want to store the validation result for future reference
      // await storeValidationResult(userId, transactionId, validationResult);
    } else {
      // Handle invalid purchase
      console.warn(`Invalid purchase detected for transaction ${transactionId}`);
      // You might want to flag this for further investigation
      // await flagSuspiciousPurchase(userId, transactionId);
    }

    // Always respond with a success to the app
    // This ensures the app doesn't block the user's access
    res.json({ success: true });
  } catch (error) {
    console.error('Error validating purchase:', error);
    // Still respond with success to the app
    res.json({ success: true });
    // You might want to log this error or retry the validation later
    // await logValidationError(userId, transactionId, error);
  }
});

// Start the server
app.listen(3000, () => console.log('Server running on port 3000'));

Key points about this approach:

  1. The app immediately grants access after a successful purchase, ensuring a smooth user experience.
  2. The app initiates server-side validation asynchronously, not blocking the user's access.
  3. The server handles the actual validation by calling the Cloudflare Worker.
  4. The server always responds with success to the app, even if validation fails or encounters an error.
  5. The server can update the user's status in the database, log results, and handle any discrepancies without affecting the user's immediate experience.

Comments on best practices:

// After successful validation:
// await updateUserStatus(userId, 'paid');

// It's crucial to not block or revoke access immediately if validation fails
// Instead, flag suspicious transactions for review:
// if (!validationResult.isValid) {
//   await flagSuspiciousPurchase(userId, transactionId);
// }

// Implement a system to periodically re-check flagged purchases
// This could be a separate process that runs daily/weekly

// Consider implementing a grace period for new purchases
// This allows for potential delays in server communication or store processing
// const GRACE_PERIOD_DAYS = 3;
// if (daysSincePurchase < GRACE_PERIOD_DAYS) {
//   grantAccess = true;
// }

// For subscriptions, regularly check their status with the stores
// This ensures you catch any cancelled or expired subscriptions
// setInterval(checkSubscriptionStatuses, 24 * 60 * 60 * 1000); // Daily check

// Implement proper error handling and retry logic for network failures
// This is especially important for the server-to-Cloudflare communication

// Consider caching validation results to reduce load on your server and the stores
// const cachedValidation = await getCachedValidation(transactionId);
// if (cachedValidation) return cachedValidation;

This approach balances immediate user gratification with proper server-side validation, adhering to Apple and Google's guidelines while still maintaining the integrity of your purchase system.

API

restorePurchases()

restorePurchases() => any

Restores a user's previous and links their appUserIDs to any user's also using those .

Returns: any


purchaseProduct(...)

purchaseProduct(options: { productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; }) => any

Started purchase process for the given product.

Param Type Description
options { productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; } - The product to purchase

Returns: any


getProducts(...)

getProducts(options: { productIdentifiers: string[]; productType?: PURCHASE_TYPE; }) => any

Gets the product info associated with a list of product identifiers.

Param Type Description
options { productIdentifiers: {}; productType?: PURCHASE_TYPE; } - The product identifiers you wish to retrieve information for

Returns: any


getProduct(...)

getProduct(options: { productIdentifier: string; productType?: PURCHASE_TYPE; }) => any

Gets the product info for a single product identifier.

Param Type Description
options { productIdentifier: string; productType?: PURCHASE_TYPE; } - The product identifier you wish to retrieve information for

Returns: any


isBillingSupported()

isBillingSupported() => any

Check if billing is supported for the current device.

Returns: any


getPluginVersion()

getPluginVersion() => any

Get the native Capacitor plugin version

Returns: any


Interfaces

CustomerInfo

Prop Type Description
activeSubscriptions [string] Set of active subscription skus
allPurchasedProductIdentifiers [string] Set of purchased skus, active and inactive
nonSubscriptionTransactions {} Returns all the non-subscription a user has made. The are ordered by purchase date in ascending order.
latestExpirationDate string | null The latest expiration date of all purchased skus
firstSeen string The date this user was first seen in RevenueCat.
originalAppUserId string The original App User Id recorded for this user.
requestDate string Date when this info was requested
originalApplicationVersion string | null Returns the version number for the version of the application when the user bought the app. Use this for grandfathering users when migrating to subscriptions. This corresponds to the value of CFBundleVersion (in iOS) in the Info.plist file when the purchase was originally made. This is always null in Android
originalPurchaseDate string | null Returns the purchase date for the version of the application when the user bought the app. Use this for grandfathering users when migrating to subscriptions.
managementURL string | null URL to manage the active subscription of the user. If this user has an active iOS subscription, this will point to the App Store, if the user has an active Play Store subscription it will point there. If there are no active subscriptions it will be null. If there are multiple for different platforms, it will point to the device store.

Transaction

Prop Type Description
transactionId string RevenueCat Id associated to the transaction.

Product

Prop Type Description
identifier string Product Id.
description string Description of the product.
title string Title of the product.
price number Price of the product in the local currency.
priceString string Formatted price of the item, including its currency sign, such as €3.99.
currencyCode string Currency code for price and original price.
currencySymbol string Currency symbol for price and original price.
isFamilyShareable boolean Boolean indicating if the product is sharable with family
subscriptionGroupIdentifier string Group identifier for the product.
subscriptionPeriod SubscriptionPeriod The Product subcription group identifier.
introductoryPrice SKProductDiscount | null The Product introductory Price.
discounts {} The Product discounts list.

SubscriptionPeriod

Prop Type Description
numberOfUnits number The Subscription Period number of unit.
unit number The Subscription Period unit.

SKProductDiscount

Prop Type Description
identifier string The Product discount identifier.
type number The Product discount type.
price number The Product discount price.
priceString string Formatted price of the item, including its currency sign, such as €3.99.
currencySymbol string The Product discount currency symbol.
currencyCode string The Product discount currency code.
paymentMode number The Product discount paymentMode.
numberOfPeriods number The Product discount number Of Periods.
subscriptionPeriod SubscriptionPeriod The Product discount subscription period.

Enums

PURCHASE_TYPE

Members Value Description
INAPP "inapp" A type of SKU for in-app products.
SUBS "subs" A type of SKU for subscriptions.

Readme

Keywords

Package Sidebar

Install

npm i @capgo/native-purchases

Weekly Downloads

155

Version

6.0.33

License

MIT

Unpacked Size

148 kB

Total Files

26

Last publish

Collaborators

  • riderx