React SDK

This is the official React SDK for the AhoraCrypto payment widget, allowing you to easily integrate cryptocurrency payments into your React applications, including those using Capacitor for mobile apps.

Installation

npm install ahoracrypto-react-sdk

or

yarn add ahoracrypto-react-sdk

Key Features

• Optimized Performance: Improved initialization process eliminates double loading issues

• Development Logging: Detailed logs only appear in development mode, not in production builds

• Enhanced Iframe Attributes: Complete set of permissions for optimal integration

• Responsive Themes: Automatic light/dark mode detection with manual overrides

• Cross-Domain Communication: Reliable iframe messaging system

• Auto Container ID: No need to provide a container ID when using the React component

Usage

The SDK provides two ways to integrate the AhoraCrypto widget:

1. React Component: Use the AhoraCryptoWidget component in your JSX/TSX.

2. Function API: Use the renderWebwidget function to render the widget programmatically (similar to the vanilla JavaScript SDK).

React Component Approach

import React, { useRef } from 'react';
import { AhoraCryptoWidget } from 'ahoracrypto-react-sdk';

function MyPaymentPage() {
  const controllerRef = useRef(null);

  return (
    <div className="payment-container">
      <h2>Complete Your Payment</h2>
      
      <div>
        <AhoraCryptoWidget 
          config={{
            cryptoCurrency: 'BTC',
            fiatCurrency: 'EUR',
            borderWithShadow: true,
            theme: 'light'
          }}
          onReady={(controller) => {
            // Save controller reference to interact with the widget later
            controllerRef.current = controller;
            console.log('Widget is ready!');
          }}
        />
      </div>
      
      <div className="actions">
        <button onClick={() => controllerRef.current?.setWalletAddress('0x1234567890abcdef1234567890abcdef12345678')}>
          Set wallet address
        </button>
      </div>
    </div>
  );
}

Function API Approach

import React, { useEffect } from 'react';
import { renderWebwidget } from 'ahoracrypto-react-sdk';

function MyPaymentPage() {
  useEffect(() => {
    // Initialize widget
    const widget = renderWebwidget({
      containerId: 'widget-container', // Required for function API
      cryptoCurrency: 'ETH',
      fiatCurrency: 'USD',
      borderWithShadow: true
    });
    
    // Listen for widget ready event
    widget.onReady(() => {
      console.log('Widget is ready!');
      
      // You can interact with the widget using the controller
      // widget.setWalletAddress('0x1234...');
    });
    
    // Clean up on unmount (not strictly necessary)
    return () => {
      // Cleanup code if needed
    };
  }, []);
  
  return (
    <div className="payment-container">
      <h2>Complete Your Payment</h2>
      <div id="widget-container" style={{ maxWidth: '416px', margin: '0 auto' }}></div>
    </div>
  );
}

Capacitor Integration

The SDK works seamlessly with Capacitor for building mobile apps. Here's how to use it in a Capacitor-based project:

Setup in Capacitor

1. Install the SDK and Capacitor:

npm install ahoracrypto-react-sdk @capacitor/core @capacitor/ios @capacitor/android

1. Initialize Capacitor (if not already done):

npx cap init

1. Add platforms:

npx cap add ios
npx cap add android

Example Usage in a Capacitor App

import React, { useEffect, useRef } from 'react';
import { AhoraCryptoWidget } from 'ahoracrypto-react-sdk';
import { Device } from '@capacitor/device';
import { App } from '@capacitor/app';

function CapacitorPaymentScreen() {
  const controllerRef = useRef(null);
  const [deviceTheme, setDeviceTheme] = useState('light');

  useEffect(() => {
    // Get device preferences for theming
    const getDevicePreferences = async () => {
      try {
        // Check if device is using dark mode
        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
        setDeviceTheme(prefersDark ? 'dark' : 'light');
      } catch (error) {
        console.error('Error detecting theme:', error);
      }
    };

    getDevicePreferences();
    
    // Handle app state changes
    const handleAppStateChange = ({ isActive }) => {
      if (isActive && controllerRef.current) {
        // Refresh widget data when app comes back to foreground if needed
      }
    };
    
    App.addListener('appStateChange', handleAppStateChange);
    
    return () => {
      App.removeAllListeners();
    };
  }, []);

  return (
    <div className="capacitor-payment-container">
      <div>
        <AhoraCryptoWidget 
          config={{
            cryptoCurrency: 'BTC',
            fiatCurrency: 'EUR',
            theme: deviceTheme,
            // Optimize for mobile screens
            iframeHeight: 550,
            borderRadius: 16
          }}
          onReady={(controller) => {
            controllerRef.current = controller;
            console.log('Widget ready in Capacitor app');
          }}
        />
      </div>
    </div>
  );
}

Building for iOS/Android

After integrating the widget into your React app, build and sync the project:

npm run build
npx cap sync

Open the native projects:

npx cap open ios
# or
npx cap open android

Configuration Options

The widget accepts the following configuration options:

Option	Type	Description
containerId	string	Required only for Function API. ID of the container element
language	string	Optional language code for the widget
cryptoCurrency	string	Cryptocurrency symbol to select by default
fiatCurrency	string	Fiat currency symbol to select by default
logoUrl	string	Custom logo image URL
backgroundColor	string	Background color (HEX)
buttonColor	string	Button color (HEX)
borderRadius	number	Border radius of components
borderWithShadow	boolean	Whether to apply a styled border with shadow
theme	'light' | 'dark'	Force a specific theme
iframeWidth	number	Custom iframe width
iframeHeight	number	Custom iframe height
paymentIntentId	string	Payment intent ID
referral	string	Referral identifier for traffic tracking

Controller Methods

The widget controller provides the following methods for interacting with the widget:

Method	Description
setWalletAddress(address)	Sets the wallet address
setPaymentIntentId(id)	Sets the payment intent ID
sendSignedMessage(signature, address, messageHash?)	Sends a signed message to the widget
requestMessageToSign()	Requests a message for signing
connectWeb3Wallet(provider, address, chainId)	Connects a Web3 wallet to the widget
setTheme(theme)	Sets the widget theme ('light' or 'dark')
onReady(callback)	Registers a callback for when the widget is ready
ready()	Returns a promise that resolves when the widget is ready
isReady()	Returns whether the widget is ready

Development and Debugging

Logging System

The SDK includes a smart logging system that only displays logs in development environments:

• In development mode (NODE_ENV === 'development'), detailed logs appear to help with debugging

• In production builds, logs are automatically suppressed to avoid cluttering the console

This helps developers debug during development while ensuring a clean console in production.

Performance Optimizations

Recent optimizations include:

• Single Initialization: Widget now initializes only once, preventing duplication of events

• Improved Loading: Enhanced initialization process with better handling of the "ready" state

• No Message Queuing: Messages are only sent when the widget is ready, preventing potential timing issues

• Memory Efficiency: Better state management to reduce memory usage and avoid leaks

• Auto Container ID: When using the React component, a unique container ID is generated automatically

Troubleshooting

If you encounter issues with the widget:

1. Widget Not Displaying: Ensure the container has sufficient width and height

2. Communication Issues: Check the console for errors in development mode

3. Iframe Not Loading: Verify your internet connection and that the domain is accessible