🪙Currency Formatting Engine

This page outlines how to set and use the XCE Currency Formatting Engine (CFE)

Overview

Our Currency Formatting Engine ensures a consistent and user-friendly experience for your customers by allowing you to configure how currency values are displayed within the XCE widget.

This ensures that your customers have a seamless experience across your platform and within our widget.

Usage

Our currency formatting API is built on top of the Intl.NumberFormat ECMAScript Internationalization API configuration options.

The currency configuration options are an object passed in to the data object of the set signal.

Here's an example of a currency_config object set to:

• Display currency as symbol

• No cents display when cents equals zero

const currencyConfig = {
    currencyDisplay: 'symbol',
    trailingZeroDisplay: 'stripIfInteger'
};

Now, an example using currency configuration object together with our set signal.

window.signalLayer.push({
  signal: 'set',
  element: 'xce-protection-offer',
  onSet: '{{onset_promise_function}}',
  data: {
    quote_request: {
      currency: "IDR", 
      customer_language: "id",
      customer_country: "AU",
      request: [
        {
          policy_type: "event_ticket_protection",
          policy_start_date: "{{policy_start_date}}",
          event_datetime: "{{policy_end_date}}",
          event_name: "Cover Genius Event",
          event_country: "AU",
          number_of_tickets: 1,
          tickets: [
            {
              price: 99.5
            }
          ],
        }
      ]
    },
    currency_config: currencyConfig,
    order_total: 99.5,
  }
});

Set signal is used to set the desired currency and language(locale) values for the currency formatting engine. This means that the currency locale equals the user's preferred language at all times, this is to always keep our widget content language and currency locale aligned.

In order to provide the desired currency format, when needed, we must update the currency configuration object every time a set signal is called. If no currency configuration object is passed, the element will render currency format using the defaults from Intl.NumberFormat API which could result in an undesired currency format.

Custom options

Additionally to the default Intl.NumberFormat API options we have included a custom options property to override the currency symbol and/or placement of both the symbol and the amount:

• marker is used to replace in place the currency symbol or code with a custom value.

• format is used to format the placement of the currency symbol or code and the amount value. There's a special character assigned to both the symbol and the value:

  • %m stands for marker and represents the currency symbol or code.

  • %v stands for value and represents the number amount value.

  • You can also add or remove blank spaces, even include extra characters if needed.

Here are a couple of examples setting a custom symbol and placement using the marker and format properties:

// & as marker and spaces
const currencyConfig = {
    currencyDisplay: 'symbol',
    trailingZeroDisplay: 'stripIfInteger',
    customOptions: {
        marker: '&',
        format: '%m%v', // renders: '&200'
    }
};

// & as marker and marker after value with spaces
const currencyConfig = {
    currencyDisplay: 'symbol',
    trailingZeroDisplay: 'stripIfInteger',
    customOptions: {
        marker: '&',
        format: '%v %m', // renders: '200 &'
    }
};

Custom options are independent from each other:

// default symbol and no blank spaces
const currencyConfig = {
    currencyDisplay: 'symbol',
    trailingZeroDisplay: 'stripIfInteger',
    customOptions: {
        format: '%m%v', // renders: '$200'
    }
};

// & as symbol and no format
const currencyConfig = {
    currencyDisplay: 'symbol',
    trailingZeroDisplay: 'stripIfInteger',
    customOptions: {
        marker: '&', // renders: '& 200'
    }
};

Customer language values and currency values are critical for our currency formatting engine to provide the expected format. Be aware that mixing them can result in undesired formats. Please make sure to test your combinations before committing to the values.