Currency Conversion

SDK currency conversion support

The Verb SDK allows you to query data in stored in various currency formats and consolidate the output into a single, comparable currency.

ISO Codes

At the core of currency versions are ISO Codes. Typical schemas store currency values along side an ISO code value. For example, an e-commerce platform with North American customers may store transactions in Pesos (MXN), Canadian Dollars (CAD), and US Dollars (USD). ISO Codes are a standard way to differentiate currencies by country. While any text field can be used during the conversion process, it is recommended that standard ISO codes be used for simplicity when aggregating data.

Conversions

The SDK takes in a series of input values to configure the underlying data conversion process. Each collection requires the following definitions:

• Base Rate ISO Code (Required)

  • The base rate ISO code instructs Verb queries which rate to base all conversions on. This rate is effectively a one-to-one rate. Any values matching this ISO code will not be converted. Values with other ISO codes will be converted to reflect the ratio between the base rate.

• Display Rate ISO Code (Optional; defaults to base rate)

  • This optional field allows differentiation between the base rate and the value displayed to users. Once conversions are calculated, the output will target the display rate during data query operations. For example, a base rate of $1 US dollar (USD) with a display rate of Canadian dollars (CAD) will render all calculations in CAD using USD as the basis for all calculations.

• Precision (Optional; default is 2 decimal places)

  • Precision allows for control over calculated values during Verb data query operations. Two decimal places is the default given most currency formatting is relevant to one cent. However the calculations can be controlled with this setting when a higher precision is required.

• ISO Rates (Required)

  • ISO Rates are a list of ISO codes and their value compared to the base rate. For example, a base rate of $1 USD may include $20.02 MXN and $1.33 CAD. ISO codes will map to your data and the rate will be used to calculate the conversion

Mismatch Handling

The Verb query process had two different modes of handling currency conversions when data is encountered for which an ISO Code and Rate are not provided. The default option is to ignore the data value and instead convert the currency into a zero value.

The alternative is to return the record's raw value without any conversion.

Tiles display in indicator when the underlying tile data contains conversions that do not contain a matching ISO Code.

SDK Currency Configuration

JavaScript Implementation

The following example shows how to configure vanilla JavaScript implementations with currency conversion details:

 <div 
   x-verb-dashboard="true"
   x-collection-id="..."
   x-conversion='{"displayCode": "CAD","baseCode": "USD", "rates": [{"code": "EUR", "rate": 1.2345},{"code": "CAD", "rate": 1.9823},{"code": "JYP", "rate": 1.1356}]}'
 ></div>

The JS implementation creates a JSON object as an attribute. The Verb SDK will puck up the details and send them as part of the data query payload.

Angular Implementation

The following example shows how to configure an Angular implementation using the verb-dashboard Angular component:

<verb-dashboard
    [params]='{
      collectionId: "...",
      conversion: {"displayCode": "EUR","baseCode": "USD", 
      "rates": [{"code": "EUR", "rate": 1.2345},
      {"code": "CAD", "rate": 1.9823},
      {"code": "JYP", "rate": 1.1356}]}
}'
></verb-dashboard>

React Implementation

The following example shows how to configure a React implementation using the VerbDashboard React component:

const App = () => (
    <div>
        {
            window.VerbDashboard({
                collectionId: "...",
                conversion: {
                    "displayCode": "EUR",
                    "baseCode": "USD", 
                    "rates": [
                        {"code": "EUR", "rate": 1.2345},
                        {"code": "CAD", "rate": 1.9823},
                        {"code": "JYP", "rate": 1.1356}]
                    },
                React: React,
                ReactDOM: ReactDOM
            })
        }
    </div>
)

Vue Implementation

The following example shows how to configure a Vue implementation using the verb-dashboard React component:

<script>
  new Vue({
    el: '#root',
    template: `
      <verb-dashboard
        v-bind:params='{
          collectionId: "93a22ffa-2736-43a9-a324-447d1a018e3c",
           conversion: {
             "displayCode": "EUR",
             "baseCode": "USD", 
             "rates": [
                {"code": "EUR", "rate": 1.2345},
                {"code": "CAD", "rate": 1.9823},
                {"code": "JYP", "rate": 1.1356}]
             }
        }'
      />
    `
  });
</script>

Additional Currency Functionality

If you don't need to convert currency values but need to adjust the currency symbols based on the viewer see the Currency Symbol Section.