Currency Region

The Despia Currency Region SDK enables your application to detect a user's store location, providing their country code. This allows you to adjust pricing, display appropriate currency symbols, and create localized experiences that match regional formats - significantly improving user experience for your global audience.

Quick Start

1. Request Store Location

Request the user's store location with a simple API call.

Copy// Get user's store location
window.despia = "getstorelocation://"

2. Access the Store Location Value

The SDK will return the user's country code, which you can then use in your application.

// If successful (example United States of America) var storeLocation = 'US'; // If no country code is found var storeLocation = null;

3. Implement Location-Based Logic

Use the store location value to provide localized experiences for your users.

Copyconsole.log(storeLocation);

How It Works

The Currency Region SDK works by detecting the user's store location based on their device settings and network information. Once detected, it returns a standard two-letter country code (ISO 3166-1 alpha-2) that represents the user's region. This allows your application to make intelligent decisions about currency formatting, pricing, and other region-specific content.

Implementation Examples

Below are implementation examples for various platforms, including both code and no-code solutions.

Copy// Basic implementation
window.despia = "getstorelocation://";

// Example handling the result
if (storeLocation) {
    // EXAMPLES FOR REGIONAL CURRENCY DETECTION (for NoCode/LowCode Tools)
    
    // ---------- WEWEB ----------
    // WEWEB example using wwWorkflow to handle regional currency detection
    
    // 1. Create a Native WeWeb Global Workflow to receive following parameters:
    // A. countryCode
    // B. timestamp
    
    // 2. Add Logic to that Workflow to load appropriate pricing based on region
    
    // 3. Call your Workflow from exactly this line of code here:
    wwLib.wwWorkflow.executeGlobal('YOUR WEWEB WORKFLOW ID', {
        countryCode: storeLocation,
        timestamp: new Date().getTime()
    });
    
    // ---------- WIZED ---------- 
    // WIZED example using Wized's JS API
    
    // Store the detected region in a Wized variable
    v.userRegion = storeLocation;
    
    // OPTIONAL - Create a request (API Call) that will send region information to load correct pricing
    const result = await Wized.requests.execute('REQUEST NAME TO PROCESS LOCATION');
    console.log(result); // Or set result as variable for pricing display
    
    // ---------- NORDCRAFT / TODDLE ---------- 
    // For Nordcraft / Toddle - simply trigger an event with the region data
    // Create a custom event handler in your project settings
    ctx.triggerActionEvent("onRegionDetected", {
        countryCode: storeLocation,
        timestamp: new Date().getTime(),
    });
}

Data Structure

The SDK returns a simple string value representing the user's country code.

Copy// Example return value for United States
var storeLocation = 'US';

// Example values for other regions
// United Kingdom: 'GB'
// Germany: 'DE'
// France: 'FR'
// Japan: 'JP'
// Australia: 'AU'
// etc.

Best Practices

Integration

• Always check if the storeLocation value is null before using it

• Provide fallback pricing/currency for unsupported regions

• Initialize the SDK early in your application lifecycle

User Experience

• Allow users to manually override detected region if needed

• Display currency symbols appropriate to the detected region

• Format numbers according to regional conventions

• Consider timezone differences for time-sensitive content

Complete Implementation Example

Here's a complete example showing how to implement the Currency Region SDK with fallback handling and regional pricing.

Copy// Request the store location
window.despia = "getstorelocation://";

// Function to handle regional pricing
function updatePricing() {
    // Define regional pricing
    const pricingMap = {
        'US': { currency: 'USD', symbol: '$', value: 9.99 },
        'GB': { currency: 'GBP', symbol: '£', value: 7.99 },
        'DE': { currency: 'EUR', symbol: '€', value: 8.99 },
        'FR': { currency: 'EUR', symbol: '€', value: 8.99 },
        'JP': { currency: 'JPY', symbol: '¥', value: 1100 }
        // Add more regions as needed
    };
    
    // Default pricing (fallback)
    let pricing = pricingMap['US'];
    
    // If we have a valid store location, use that pricing
    if (storeLocation && pricingMap[storeLocation]) {
        pricing = pricingMap[storeLocation];
    }
    
    // Update the UI
    document.getElementById('price-value').textContent = 
        `${pricing.symbol}${pricing.value.toLocaleString(storeLocation || 'en-US')}`;
    
    // You might also want to update the currency code displayed
    document.getElementById('currency-code').textContent = pricing.currency;
}

// Call the function to update pricing
updatePricing();

Troubleshooting

Common Issues

Store Location Returns Null

• Check internet connectivity

• Verify the SDK is properly initialized

• Try requesting the location again after a short delay

• Consider adding a manual country selector as fallback

Incorrect Region Detection

• Some users may be using VPNs that affect region detection

• Allow users to manually select their region

• Consider using multiple signals to determine location

Implementation Errors

• Ensure you're checking for null values before using storeLocation

• Verify the correct syntax is used for the API call

• Check browser console for any JavaScript errors