UI SDK - Vanilla Javascript integration

SDK library integration

The Amberflo UI Kit SDK is a Vanilla Javascript development kit for our customers to be able to consume and make use of principal Amberflo views, for one of their customers, on their own site.

The SDK is responsible of making the API calls and rendering the components on a destination <div> on the final HTML code.

πŸ“˜

Requisites

These are some of the languages where the SDK can be used: in React, Javascript, Angular, Vue.

Getting Started


  1. Include the script in the <head> of your site:
<script
  type="module"
  src="https://js.amberflo.io/index.1.0.17.js">
</script>

πŸ“˜

Make sure to use to the latest available version in the script (e.g.: 1.0.17). You can check versions under Releases section.

  1. Retrieve your session token to access Amberflo API endpoints. With that session id, you will need to make a new instance of the AmberfloSDK included on the script above. To do that, you will have to add this code snippet under the first script tag you added:
<script>
  window.onload = () => {
    amberflo = new AmberfloSDK("{{YOUR_SESSION_TOKEN}}");
  };
</script>

πŸ“˜

Replace {{YOUR_SESSION_TOKEN}} with the token you got. To know more about how to get your session token read Get Session Token section.

  1. Since sessions can expire, on your new instance of AmberfloSDK there is a method to set the new sessionId. You can call it anytime to amberflo.setSessionId("{{YOUR_NEW_SESSION_TOKEN}}");.
    The app will continue to work the same with the same ID.

  2. To add a new Amberflo view, you will need to place a <div> on your code, with the class amberflo and a data-amberflo-type attribute to setup the element. This data-amberflo-type attribute is responsible for rendering the different views that we support.

It's also possible to customize the components by adding a specific color, choose to show the widget container and its title, the font size, font family, and even a custom font. To do that, use the following attributes:

  • data-amberflo-colors
    Set a HEX code or string value of the primary color of your brand. We will automatically create a palette based
    on that color for all the components. By default it will use Amberflo colors.

  • data-amberflo-font-size
    Enter a number, this is the base font size, since not all part of this views has the same font size, all internal
    components will calculate percentage to show the desired font size for each internal view. Default value is 16,
    which is the default font size for all Amberflo components.

  • data-amberflo-font-family
    This is a comma separated name of fonts, it can be any font that is already supported and imported on your
    site. The browser will try to use the first font on that list, but if for some reason the font is not available, it will
    fallback to the right until a font is available. This is not common, bit could happen so we recommend to have
    more than a font in the list.

  • data-amberflo-font-custom
    If the font you are trying to use is not supported by the browser, nor one already added by you, you could use
    this prop to import a custom google font to your app. Besides importing the font, you need to specify the font
    name on the attributedata-amberflo-font-family.

  • data-amberflo-with-container
    It receives a string saying "true" or "false", if true, it will show the container around the widget, similar to the ones on our app

  • data-amberflo-with-title
    It receives a string saying "true" or "false", if true, it will show the title of the widget, it requires that the container is visible

  • data-amberflo-title
    It receives a string specifying a custom title for the widget, if not provided, will use the widget default title

All the styles attributes above are optional, if none is provided, it will use Amberflo design system.

<div
  class="amberflo"
  data-amberflo-type="usage-table"
  data-amberflo-colors="#1565c0"
  data-amberflo-font-size="16px"
  data-amberflo-font-family="Roboto, Helvetica, Arial, serif"
  data-amberflo-font-custom="https://fonts.googleapis.com/css2?family=DynaPuff:[email protected];500&family=Great+Vibes&family=Rubik&display=swap"
  data-amberflo-with-container="true"
  data-amberflo-with-title="true"
  data-amberflo-title="Custom Title"
></div>

Some views may require to use other attributes. Attributes can be updated programmatically at any time to render a different view or state. For example, you can render a Usage Table with a meter, and when you click a button, change that attribute to render the same view but with a different meter.

Get Session Token


You must create a session token to interact with Amberflo, either directly with the API or through the AmberfloSDK.

To do so, you can retrieve it from an endpoint on your server using the browser’s fetch function on the client side. This is generally the best approach when your client side is a single page application, especially if it’s built with a modern frontend framework such as React.

For more information check API Reference

This example shows how to create the server endpoint that serves the client secret:

const express = require('express');
const app = express();
const request = require('request');

app.get('/amberflo-session', async (req, res) => {
  request({
    method: 'POST',
    uri: 'http://app.amberflo.io/session',
    body: {
      "customerId": "{{DESIRED_CUSTOMER_ID}},
      "expirationEpochMilliSeconds": {{EXPIRATION_DATE_IN_MILLISECONDS}}
    },
    headers: {
      "X-API-KEY": "{{YOUR_API_KEY}}"
    }
  }, function (error, response, body) {
        if (!error && response.statusCode == 200) {
            res.json({ sessionToken: response.sessionToken })
        }
    }
  );
})

πŸ“˜

The above example is in Node.js.

You can get X-API-KEY from Amberflo site inside Settings -> Account -> API keys.

15261526

You can also get the customerId from Amberflo site inside Customers β†’ Click on one customer β†’ Copy Customer ID.

14621462

This example demonstrate how to fetch the session token with JavaScript in the client side:

const response = fetch('/amberflo-session').then(function(response) {
  return response.json();
}).then(function(responseJSON) {
  const sessionToken = responseJson.sessionToken
})

SDK Versions


πŸ“˜

Releases

10/20/2022 - Version 1.0.17
10/12/2022 - Version 1.0.16
10/04/2022 - Version 1.0.15
09/14/2022 - Version 1.0.14
09/12/2022 - Version 1.0.13
09/01/2022 - Version 1.0.12
08/29/2022 - Version 1.0.11
07/29/2022 - Version 1.0.10
07/12/2022 - Version 1.0.9
07/07/2022 - Version 1.0.8
07/06/2022 - Version 1.0.7
06/07/2022 - Version 1.0.6
05/09/2022 - Version 1.0.5
05/07/2022 - Version 1.0.4
04/26/2022 - Version 1.0.3
04/21/2022 - Version 1.0.2
04/20/2022 - Version 1.0.1
04/13/2022 - Version 1.0.0

Available Views


Usage Table

18801880
AttributeValue
data-amberflo-typeusage-table
data-amberflo-metersComma separated meters apiNames you want to see on the table.

e.g.:
ApiCalls,cluster_count,cluster_instance_hours,cluster_partitions,cluster_reads,cluster_storage,cluster_writes,CpuHours,DataVolumeGb,number_of_runs
EventValue
datechangeTriggered when a date picker on top changes
periodchangeTriggered when period selector on top changes

Example:

<div
  class="amberflo"
  data-amberflo-type="usage-table"
  data-amberflo-meters="ApiCalls,cluster_count,cluster_instance_hours,cluster_partitions,cluster_reads,cluster_storage,cluster_writes,CpuHours,DataVolumeGb,number_of_runs"
></div>

Usage Graph

18851885
AttributeValue
data-amberflo-typeusage-graph
data-amberflo-meterA single meter apiName you want to see on the graph.

e.g.:

"ApiCalls"

If not provided, a meter selector will show on top of the graph
data-amberflo-dimensions-mapA list of dimensions values and it's transformed value. For example, if you have a dimension called dim1 but you actually want to see in the graph as Dimension 1, you can pass this attribute:

data-amberflo-dimensions-map="dim1:Dimension 1"

You can add more than one, separating them by commas:

data-amberflo-dimensions-map="dim1:Dimension 1,dim2:Dimension 2"
data-amberflo-group-byA string representing the dimension to group the graph by
data-amberflo-dimensions-selectorA boolean value used to show/hide the dimensions selector that allows a user select a dimension to group usage data by.
EventValue
datechangeTriggered when a date picker on top changes
periodchangeTriggered when period selector on top changes
meterchangeTriggered when meter selector changes
dimensionchangeTriggered when dimension selector changes

Example

<div
  class="amberflo"
  data-amberflo-type="usage-graph"
  data-amberflo-meter="ApiCalls"
></div>

Cost Table

16301630
AttributeValue
data-amberflo-typecost-table
EventValue
datechangeTriggered when a date picker on top changes
periodchangeTriggered when period selector on top changes

Example

<div
  class="amberflo"
  data-amberflo-type="cost-table"
></div>

Invoice Details

736736
AttributeValue
data-amberflo-typeinvoice-details
data-amberflo-invoice-date="1/30/2022"The date of the invoice in format l - M/D/YYYY - 1/9/2022

If not provided, it will use the last invoice for the customer.
data-amberflo-dimensions-mapHere you can send the dimension name between pipes (eg. |availability_zone|), followed by a list of value and remap value separated by commas.

So if you have a dimension called availability_zone, and it's value is zone1, and you want to change it to My Custom Zone 1, you can pass something like:

data-amberflo-dimensions-map="|availability_zone|zone1:My Custom Zone 1"

You can add more items, separating by commas

For instance:

data-amberflo-dimensions-map="|availability_zone|zone1:My Custom Zone 1,zone2:My Custom Zone 2|cloud_provider|aws:AWS"
data-amberflo-hide-breakdownString containing "true" or "false", if true, invoice breakdown will be hidden, and only titles will show the totals per product item

Example

<div
  class="amberflo"
  data-amberflo-type="invoice-details"
  data-amberflo-invoice-date="1/9/2022"
></div>

Invoices List

800800
AttributeValue
data-amberflo-typeinvoice-list
EventValue
rowclickTriggered when a invoice is clicked

Example

<div
  class="amberflo"
  data-amberflo-type="invoices-list"
></div>

Prepaid Summary

794794
AttributeValue
data-amberflo-typeprepaid-summary

Example

<div
  class="amberflo"
  data-amberflo-type="prepaid-summary"
></div>

Prepaid Wallet

804804
AttributeValue
data-amberflo-typeprepaid-table

Example

<div
  class="amberflo"
  data-amberflo-type="prepaid-table"
></div>

Stripe Payment Method

10861086
AttributeValue
data-amberflo-typestripe-payment-method
data-amberflo-publishable-keyPublishable key from stripe. You can get it by following the steps detailed below.
data-amberflo-button-textThis is the button text, where your customer will have to click to submit their credit card.
data-amberflo-return-urlThis is the URL where user will be taken after filling the credit card value, and everything worked.
<div
  class="amberflo"
  data-amberflo-type="stripe-payment-method"
  data-amberflo-publishable-key="pk_test_62MIq3eFMMJsb2ZF6ivl10ycy6kVNhPau9QnrwJE649HGEEz3vZNDo5XA5I6ZdHRosbjGq8eAGPBrE0wrl7Q0Fxn1i00CaNu0Ar"
  data-amberflo-button-text="Submit"
  data-amberflo-return-url="https://mysite.com/stripe"
  data-amberflo-colors="#1565c0"
></div>

Notes

Make sure that the data-amberflo-return-url page, includes the Amberflo script, and also is instantiated, the as you did for the page where this component is hosted.

Add the script:

<script
  type="module"
  src="https://js.amberflo.io/index.1.0.16.js"
></script>

And make sure you instantiate it:

<script>
  window.onload = () => {
    amberflo = new AmberfloSDK("{{YOUR_SESSION_TOKEN}}");
  };
</script>

Pricing Plan

561561
AttributeValue
data-amberflo-typepricing-plan
data-amberflo-pricing-planPricing Plan ID
data-amberflo-titlePricing Plan title. It could be the same as the pricing plan itself, or some other text
data-amberflo-product-item-linesComma separated strings for each line row
data-amberflo-fixed-priceBoolean defining if the plan has or not a fixed price
data-amberflo-priceString saying the fixed price of the plan. Only mandatory if fixed price is true.
EventValue
planselectTriggered when the select plan button is clicked
<div
  class="amberflo"
  data-amberflo-type="pricing-plan"
  data-amberflo-pricing-plan="65ad692f-b7ae-4886-ab8a-3d0146d0817d"
  data-amberflo-title="Plan Name"
  data-amberflo-product-item-lines="30$ / GB,Custom  Text"
  data-amberflo-fixed-price="true"
  data-amberflo-price="$40 Fixed Price"
  data-amberflo-colors="#0078D4"
></div>

How to get the Stripe publishable key


  • Go to stripe.com and login with your username and password
  • Once inside Stripe, go to Dashboard
  • Inside the dashboard copy the publishable key. Check the image below for reference:

17831783

Example