Iframes

Current version of integration provides you with 4 types of widgets to represent data of Norwegian companies on your website.

Overall integration looks like on the diagram

Authentication

To start using iframes you need to have an auth token. An auth token can be retrieved by calling generate-token endpoint. Here’s an example of the request:

curl --location --request POST 'https://stg-dashboard.energi.ai/api/auth/generate-token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "orgNumber": "927611074",
    "secret": "<<a string provided by Energi.ai>>"
    }'

orgNumber parameters is an organisation number of company you are requesting data for. You can find an example in Brønnøysundregistrene (opens in a new tab)
secret parameter is a token provided by Energi.ai. It’s your integration key and must be stored securely.

⚠️

Secret must not appear in any way in browser including headers, cookies or whatever. If the secret has been (or one even suspects it has been) leaked - please reach Energi.AI for regenerating it.

Rendering the widget iframe

The iframe element needs to be simply added somewhere on a page with the following URL:

{baseUrl}/embed/widget/{widgetName}?lang={lang}&token={authToken}

For example:

<iframe id="widget" frameborder="0" src="https://dashboard.energi.ai/embed/widget/basic?lang=no&token=d118c4f39d8f6033fb81fbd349e26d9d70cc0fff42b7d82ecfd08275d3eac8aa0b1b910be48c90ac0bac2c2f9d21c88d3cf35ee7411aa6af7e99aa77f0d1e5e4e05d87ece322532da5528d50744f99e20cd97c3f0cd03e363ec90b47ab65f655e4a26f869236365b63b715714ec35ea3331b53bcc311a43aa84d0aded12911aa28a8d8717b484a6caa29f9b4368997efef15efd3452c4dcec504536f6c3c44de4dfd4afaa6d2491acf3cea0aaef3fbe156ed722e25e361f847be304ba99be8c7991cbd7612d1d763ee659484a8eb187e8d2283b55ac41ebac6f5e0debf84cc90ac8539ff6a6a16256bd48e1c40e22e79.74b8bd96dd2c7dc1904353d93dc1e61d"></iframe>

Domains for different environments

Stage (for testing)	Prod
`https://stg-dashboard.energi.ai`	`https://dashboard.energi.ai`

ℹ️

For each domain you should have a separate SECRET

URL parameters

Parameter	Description	Required
`baseUrl`	Environment domain (see Domains for different environments)	Yes
`widgetName`	Widget to be displayed. Allowed values: `basic` - Basic carbon accounting `spend-based` - Spend-based calculation of GHG `finance` - Emission view based on the financial structure `ghg` - Greenhouse gas protocol view	Yes
`lang`	Widget localization. Allowed values: `no` - Norwegian `en` - English (default)	No
`token`	Generated authentication token (see Authentication token retrieval).	Yes

Widget message events

Message interface

Every widget emits events using the browser's postMessage method. All messages are sent as an object in format:

interface Message {
  source: string;
  payload: {
    status: string;
    message: string;
  };
}

or more strict

interface Message {
  source: 'energi-widgets';
  payload:
    | {
        status: 'error';
        message: 'invalid_auth_token' | 'data_error';
      }
    | {
        status: 'success';
        message: 'data_loaded' | 'data_updated';
      };
}

Message types

The following event payload could be received:

Name	Description
`{` `status: 'error',` `message: 'invalid_auth_token'` `}`	Authorization failed. A user cannot access the widget data with the token provided.
`{` `status: 'error',` `message: 'data_error'` `}`	An error while loading the widget data.
`{` `status: 'success',` `message: 'data_loaded'` `}`	The widget data was successfully loaded. It happens on the first render only.
`{` `status: 'success',` `message: 'data_updated'` `}`	The widget data was successfully updated. It happens when a widget’s data is changed after some user’s action.

Event handler example

Your handler may look like this:

window.addEventListener('message', (event) => {
  const data = event.data;
  if (data.source === 'energi-widgets' && data.status === 'error') {
     // handle error
  }
});

🛠️ External API