configuration - saltict/Demo-Docs GitHub Wiki
Comprehensive guide for configuring the SubWallet Services SDK for different environments and use cases.
📖 Navigation
- Basic Configuration
- Platform-Specific Configuration
- Environment Configuration
- Advanced Configuration
- Configuration Validation
- Dynamic Configuration Updates
The SDK comes with sensible defaults that work out of the box:
import subwalletApiSdk from '@subwallet-monorepos/subwallet-services-sdk';
// Default configuration values
console.log('Default settings:', {
version: subwalletApiSdk.version, // "0.1.3-beta.5"
headers: subwalletApiSdk.headers // Platform and version headers
});
interface SDKOption {
baseUrl?: string; // API endpoint URL
platform: 'extension' | 'mobile' | 'webapp'; // Platform type
chainListVersion?: string; // Chain list version
}
interface SDKConfig extends SDKOption {
sdkVersion: string; // SDK version (read-only)
}
// Update SDK configuration
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: 'https://sw-services.subwallet.app',
chainListVersion: '0.2.108'
});
// Verify configuration is applied
console.log('Updated headers:', subwalletApiSdk.headers);
Optimized for browser extension environments with appropriate headers and security settings.
// Extension-specific configuration
subwalletApiSdk.updateConfig({
platform: 'extension'
});
// Headers generated for extension platform:
// {
// 'SW-SDK-ChainList-Version': '0.2.108',
// 'SW-SDK-Platform': 'extension',
// 'SW-SDK-Version': '0.1.3-beta.5'
// }
Extension Manifest Configuration:
{
"manifest_version": 3,
"host_permissions": [
"https://sw-services.subwallet.app/*"
],
"content_security_policy": {
"extension_pages": "script-src 'self'; connect-src https://sw-services.subwallet.app"
}
}
Optimized for mobile environments with appropriate timeouts and retry logic.
// Mobile-specific configuration
subwalletApiSdk.updateConfig({
platform: 'mobile'
});
// Additional mobile-specific settings
const mobileConfig = {
timeout: 30000, // Longer timeout for mobile networks
retryAttempts: 3, // Retry failed requests
cacheEnabled: true // Enable response caching
};
React Native Setup:
// App.tsx
import { useEffect } from 'react';
import subwalletApiSdk from '@subwallet-monorepos/subwallet-services-sdk';
export default function App() {
useEffect(() => {
// Configure for mobile on app start
subwalletApiSdk.updateConfig({
platform: 'mobile'
});
}, []);
return (
// Your app components
);
}
Standard configuration for web applications with CORS and performance optimizations.
// Web application configuration
subwalletApiSdk.updateConfig({
platform: 'webapp'
});
// Development vs Production configuration
const isDevelopment = process.env.NODE_ENV === 'development';
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: isDevelopment
? 'http://localhost:3001/api' // Local proxy
: 'https://sw-services.subwallet.app'
});
// Development configuration
if (process.env.NODE_ENV === 'development') {
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: 'https://dev-api.subwallet.app',
chainListVersion: '0.2.108-dev'
});
// Enable debug logging in development
console.log('Development mode - SDK configured for dev environment');
}
// Staging configuration
if (process.env.NODE_ENV === 'staging') {
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: 'https://staging-api.subwallet.app',
chainListVersion: '0.2.108-staging'
});
}
// Production configuration
if (process.env.NODE_ENV === 'production') {
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: 'https://sw-services.subwallet.app',
chainListVersion: '0.2.108'
});
}
# .env file
REACT_APP_SUBWALLET_API_URL=https://sw-services.subwallet.app
REACT_APP_SUBWALLET_PLATFORM=webapp
REACT_APP_SUBWALLET_CHAIN_LIST_VERSION=0.2.108
REACT_APP_SUBWALLET_DEBUG=false
// Environment-based configuration
const config = {
baseUrl: process.env.REACT_APP_SUBWALLET_API_URL || 'https://sw-services.subwallet.app',
platform: (process.env.REACT_APP_SUBWALLET_PLATFORM || 'webapp') as 'extension' | 'mobile' | 'webapp',
chainListVersion: process.env.REACT_APP_SUBWALLET_CHAIN_LIST_VERSION || '0.2.108'
};
subwalletApiSdk.updateConfig(config);
// The SDK automatically generates headers based on configuration
// You cannot directly set custom headers, but you can influence them through config
subwalletApiSdk.updateConfig({
platform: 'webapp',
chainListVersion: '0.2.109' // This will update the chain list version header
});
// Generated headers will include:
// {
// 'SW-SDK-ChainList-Version': '0.2.109',
// 'SW-SDK-Platform': 'webapp',
// 'SW-SDK-Version': '0.1.3-beta.5'
// }
// Configure custom API endpoint
subwalletApiSdk.updateConfig({
baseUrl: 'https://your-custom-api.example.com'
});
// For proxy setup
subwalletApiSdk.updateConfig({
baseUrl: '/api/proxy' // Will be resolved relative to current origin
});
// For local development with proxy
subwalletApiSdk.updateConfig({
baseUrl: 'http://localhost:3001/subwallet-api'
});
While the SDK doesn't expose per-service configuration, you can create wrapper functions for service-specific behavior:
// Create service wrapper with custom behavior
class CustomPriceHistoryService {
constructor(private sdk: typeof subwalletApiSdk) {}
async getPriceHistoryWithCache(token: string, timeframe: string) {
const cacheKey = `price-${token}-${timeframe}`;
// Check cache first
const cached = localStorage.getItem(cacheKey);
if (cached) {
const { data, timestamp } = JSON.parse(cached);
if (Date.now() - timestamp < 60000) { // 1 minute cache
return data;
}
}
// Fetch fresh data
const data = await this.sdk.priceHistoryApi.getPriceHistory(token, timeframe);
// Cache the result
localStorage.setItem(cacheKey, JSON.stringify({
data,
timestamp: Date.now()
}));
return data;
}
}
const customPriceService = new CustomPriceHistoryService(subwalletApiSdk);
interface ConfigValidationResult {
isValid: boolean;
errors: string[];
}
function validateConfig(config: Partial<SDKOption>): ConfigValidationResult {
const errors: string[] = [];
// Validate platform
if (config.platform && !['extension', 'mobile', 'webapp'].includes(config.platform)) {
errors.push(`Invalid platform: ${config.platform}. Must be 'extension', 'mobile', or 'webapp'`);
}
// Validate baseUrl
if (config.baseUrl) {
try {
new URL(config.baseUrl);
} catch {
errors.push(`Invalid baseUrl: ${config.baseUrl}. Must be a valid URL`);
}
}
// Validate chainListVersion
if (config.chainListVersion && !/^\d+\.\d+\.\d+/.test(config.chainListVersion)) {
errors.push(`Invalid chainListVersion: ${config.chainListVersion}. Must follow semantic versioning`);
}
return {
isValid: errors.length === 0,
errors
};
}
// Usage
const newConfig = {
platform: 'webapp' as const,
baseUrl: 'https://sw-services.subwallet.app'
};
const validation = validateConfig(newConfig);
if (validation.isValid) {
subwalletApiSdk.updateConfig(newConfig);
} else {
console.error('Configuration validation failed:', validation.errors);
}
function checkConfiguration() {
const diagnostics = {
version: subwalletApiSdk.version,
headers: subwalletApiSdk.headers,
servicesAvailable: {
balanceDetection: !!subwalletApiSdk.balanceDetectionApi,
priceHistory: !!subwalletApiSdk.priceHistoryApi,
swap: !!subwalletApiSdk.swapApi,
xcm: !!subwalletApiSdk.xcmApi,
cardano: !!subwalletApiSdk.cardanoApi
},
timestamp: new Date().toISOString()
};
console.log('SDK Configuration Diagnostics:', diagnostics);
return diagnostics;
}
// Run configuration check
checkConfiguration();
The SDK supports dynamic configuration updates that will affect all subsequent API calls:
// Initial configuration
subwalletApiSdk.updateConfig({
platform: 'webapp',
baseUrl: 'https://sw-services.subwallet.app'
});
// Later, update to use staging environment
subwalletApiSdk.updateConfig({
baseUrl: 'https://staging-api.subwallet.app'
});
// Platform change (e.g., when detecting mobile environment)
if (window.innerWidth < 768) {
subwalletApiSdk.updateConfig({
platform: 'mobile'
});
}
While the SDK doesn't expose configuration change events, you can create a wrapper to track changes:
class ConfigurationManager {
private listeners: ((config: SDKOption) => void)[] = [];
private currentConfig: SDKOption;
updateConfig(newConfig: Partial<SDKOption>) {
const updatedConfig = { ...this.currentConfig, ...newConfig };
// Update SDK
subwalletApiSdk.updateConfig(newConfig);
// Notify listeners
this.listeners.forEach(listener => listener(updatedConfig));
this.currentConfig = updatedConfig;
}
onConfigChange(listener: (config: SDKOption) => void) {
this.listeners.push(listener);
// Return unsubscribe function
return () => {
const index = this.listeners.indexOf(listener);
if (index > -1) {
this.listeners.splice(index, 1);
}
};
}
}
const configManager = new ConfigurationManager();
// Listen for config changes
const unsubscribe = configManager.onConfigChange((config) => {
console.log('Configuration updated:', config);
});
// Update configuration
configManager.updateConfig({ platform: 'mobile' });
// Later, unsubscribe
unsubscribe();
// Configure based on environment detection
function configureBasedOnEnvironment() {
// Detect environment
const isExtension = typeof chrome !== 'undefined' && chrome.runtime && chrome.runtime.id;
const isMobile = /Mobi|Android/i.test(navigator.userAgent);
const isNode = typeof window === 'undefined';
let platform: 'extension' | 'mobile' | 'webapp';
if (isExtension) {
platform = 'extension';
} else if (isMobile) {
platform = 'mobile';
} else {
platform = 'webapp';
}
// Configure accordingly
subwalletApiSdk.updateConfig({
platform,
baseUrl: process.env.NODE_ENV === 'development'
? 'https://dev-api.subwallet.app'
: 'https://sw-services.subwallet.app'
});
console.log(`Configured for ${platform} platform`);
}
// Auto-configure on initialization
configureBasedOnEnvironment();
// Save configuration to localStorage
function saveConfiguration(config: SDKOption) {
localStorage.setItem('subwallet-sdk-config', JSON.stringify(config));
}
// Load configuration from localStorage
function loadConfiguration(): SDKOption | null {
const saved = localStorage.getItem('subwallet-sdk-config');
return saved ? JSON.parse(saved) : null;
}
// Initialize with saved configuration
const savedConfig = loadConfiguration();
if (savedConfig) {
subwalletApiSdk.updateConfig(savedConfig);
}
// Save configuration on updates
function updateAndSaveConfig(config: Partial<SDKOption>) {
subwalletApiSdk.updateConfig(config);
// Get current headers to determine current config
const currentConfig = {
platform: subwalletApiSdk.headers['SW-SDK-Platform'] as 'extension' | 'mobile' | 'webapp',
chainListVersion: subwalletApiSdk.headers['SW-SDK-ChainList-Version'],
...config
};
saveConfiguration(currentConfig);
}
🔗 Related Documentation