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:
React Component: Use the
AhoraCryptoWidget
component in your JSX/TSX.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
Install the SDK and Capacitor:
npm install ahoracrypto-react-sdk @capacitor/core @capacitor/ios @capacitor/android
Initialize Capacitor (if not already done):
npx cap init
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:
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:
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 debuggingIn 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:
Widget Not Displaying: Ensure the container has sufficient width and height
Communication Issues: Check the console for errors in development mode
Iframe Not Loading: Verify your internet connection and that the domain is accessible
Last updated