At Eliq, you can use our components in your site or app, regardless of the technology you’ve used to build it. As long as your platform supports displaying web elements (HTML, JavaScript, and CSS), you’re all set!

Note! Using Eliq components, requires you to have a basic understanding of HTML, JavaScript, and CSS.

Tip! Though, before being able to start using Eliq components, you need to have some back-end knowledge in order to use Eliq API and authenticate the user.

Download webcom-v1.1.0.zip (sample codes)

What are Eliq components

Any functionality that we are providing across our apps, that can also be provided individually as a single component. Here’s the list:

• One single advice details (advisory-detail-v1)
• List of advices (advisory-list-v1)
• One or more random advices (advisory-card-v1)
• User's energy bills (bill-v1)
• User's latest energy bill (bill-card-v1)
• Energy data in a chart (chart-v2)
• CO2 savior visualizer (co2-v2)
• Energy consumption compared to your previous usage (comparison-v1)
• Summary of the electricity prices (elec-price-card-v1)
• User's location Energy Usage by Category (EUC) (euc-v1)
• Sample image of user's location (location-image-v1)
• Location profile update (location-profile-update-v1)
• Location profile wizard (location-profile-wizard-v1)
• Electricity today's market price (market-price-card-v1)
• Energy consumption compared to your similar homes (similar-homes-v1)
• PV sufficiency (sufficiency-card-v1)
• Summary of user's energy consumption (summary-card-v1)
• Energy saving full advises view (full-advisory-v1)
• Energy full insights view (full-insights-v1)

Important note from product perspective:

There are some key inter dependencies between a few of these components. To provide accurate, customized insights, Eliq needs to gather certain details about the end user’s property. The Location Profile feature is designed to collect this info. From a user experience perspective, it’s highly recommended to include the Location Profile during on-boarding. Once we have that data, Eliq can calculate the following insights:

• EUC
• Similar Homes
• Customized Energy Advice

Before using Eliq components

In this documentation our main focus is on the front-end implmentation of Eliq components… But in order to use the components in your site/app (via iframe window or web-components), first you must use Eliq API to receive a ticket-id with status = completed. In order to do so, please read 'Authentication of the user by Eliq API' section of the documentation.

Optional! For using some components, you not only need to fetch a ticket-id but you also must call some protected Eliq Insights API endpoints for your user (such as GET {url}/v3/locations) to gather some information about your user's locations data. For example for using ‘full-insights' component, you don’t need to provide any inputs, but for using ‘chart' component, you need to provide it some inputs which requires you to have some sort of data about your user’s location(s). Calling these API endpoints can happen on front-end (because you already have the ticket-id which means you also have your user's access-token to call the Eliq Insights API endpoints on behalf of your user), or on back-end, depending on your site/app logic.

So in general, before using any component you need to fetch a ticket-id. Now if the component requires some inputs, you need to fetch your user’s location data as well. For example, to use the 'chart' component, you need to provide it with some inputs such as from, to, fuel, and etc. So to satisfy such components' required inputs, first you need to call GET {url}/v3/locations API endpoint, and then load the component. In such cases, you should already know that for example '123456' location ID (which is one of your user's locations) has Electricity meters, supports '30min' resolution (at highest), its data can be fetched in a specific date-range (from & to), and in 'energy' or 'cost' units... Only after that, you can initialize the component and provide its required inputs with valid values.

Tip! Before fetching the ticket-id you already receive your user’s access-token to be able to call Eliq Insights protected API endpoints… But (if you ever needed) there’s also another API endpoint which lets you fetch the user’s access-token via the ticket-id: GET {url}/authentication/oauth/token?grant_type=ticket&client_id={clientId}&ticket_id={ticketId}.

How can you use Eliq components

You can use Eliq components in 2 ways:

• As web-components.
• As an iframe window.

Web-components

Web components are a set of web platform APIs that allow developers to create reusable, encapsulated HTML elements. In simple terms, they are a modern standard in web development that enable you to build the building blocks of your site or app faster and more efficiently. Click here to read more about them.

Intro to web-components

Using Eliq web-components is simple! Just extract the .zip file and check out the index.html file inside. This file will give you a clear understanding of how to initialize each web-component, provide inputs, and listen for outputs. It’s as easy as ABC 🙌

So only by looking at index.html file, you will learn the following:

• What components do we have available.
• What are each component's required/optional inputs.
• What are each components outputs.

Want to dive deeper? You can learn more about authentication, customizing styles, or configuring the components! Keep reading to explore these topics and unlock even more capabilities🥳

Our special component

There’s one special component among all of the other ones! That special component is the initializer. What does it do? Well, it acts as the foundation, preparing the environment for other components to get loaded successfully and show data to the user.

Important! Whenever you like to initialize a component. you MUST always initialize the eliq-core-initializer-v1 component first, and then your desired component, because you already know it! It’s the foundation for other components.

How to use web-components

1. Edit eliq-assets/DEP_config.json file to your desire configurations.

Important! You MUST define two essential properties: base_url and client_id. These are mandatory for the proper functionality of the components. While other properties come with default values, without these two, nothing will work. Where to get these? Contact us.

2. Edit eliq-assets/DEP_style.css file to your desire styles (colors and feeling).
3. As explained earlier, use Eliq API to receive a ticket-id with status = completed.
4. After having the ticket-id, provide it to the initializer component. This component itself will automatically authenticates the user… So you can easily initialize any other component right after that🥳
5. Now to use Eliq web-components in your site/app, get inspired from the sample codes of index.html in the .zip file.

Tip! Technical tips and explanations are all detailed in the sample index.html file provided.

Important files

• index.html file: Everything start from here! You feed your HTML file with the required CSS and JS files, and start initializing web-components inside of it.
• eliq-core.css file: Holds the core style-sheet to style the components. It can rest anywhere, as long as you provide the correct path to it in the HTML file.
• eliq-core.js file: Holds the core codes to load the components. It can rest anywhere, as long as you provide the correct path to it in the HTML file.
• webcom-v1.js file: Holds the main codes of the components. It can rest anywhere, as long as you provide the correct path to it in the HTML file.
• eliq-assets folder: Holds the components’ assets. It MUST rest right beside the HTML file.

Note! Eliq hosts the following assets:

• eliq-core.css
• eliq-core.js
• webcom-v1.js

If you prefer not to host these files yourself, you can load them from the Eliq CDN. Here’s how:

• Include the following in your <head>: <link rel="stylesheet" href="https://general-webcomponents.eliq.com/v1.1.0/eliq-core.css">
• Include the following in your <body>: <script type="module" src="https://general-webcomponents.eliq.com/v1.1.0/eliq-core.js"></script>, and <script type="module" src="https://general-webcomponents.eliq.com/v1.1.0/webcom-v1.js"></script>.

Tip! Some of the modules use ‘Bootstrap icons‘ in their UI! That’s why in the .zip file, you can also see the following files:

• bootstrap-icons.css
• bootstrap-icons.woff
• bootstrap-icons.woff2

If you prefer not to host these files yourself, you can load ‘Bootstrap icons’ CSS file (+ its font files) from CDN:

• Include the following in your <head>: <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">

Important assets (inside eliq-assets folder)

eliq-assets folder hold the modules’ assets, right? Let’s see what are these assets.

• DEP_style.css file: Holds the styles that you can customize! It basically holds some :root and element-specific CSS variables. So you like to change Eliq components color palette to match the look and feel of your own site or app? No worries! Edit and save this file 🚀
• DEP_config.json file: Holds the configuration for all components! It holds path to the components required icons/images, base_url, client_id, and etc.
• fonts folder: Holds the font files that all components use. If they cannot find the font files, They will fallback to ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif.
• images folder: Animations, images, and icons that have been used across different components.

Some styling considerations

When dealing with the styles of the components, there are generally two main considerations to keep in mind:

• We are using Tailwindcss & Daisyui front-end frameworks to style our components. So when our web-components are used in your site or app, if you’re also using the already reserved CSS classes by such frameworks, then it might effect the styling of Eliq components as well.
• Rather than using the reserved CSS classes by the above mentioned front-end frameworks in our components, we are styling our components by some of our own CSS classes that have e- prefix, plus p to style paragraphs, hr to style <hr> tags, and h1, h2, h3, h4, h5, and h6 to style headings.

With the above mentioned styling considerations, styling conflicts may happen rarely… But if they do, here’s what needs to be done:

• If our CSS classes effect your site or app styles: You can write some new CSS rules to override the effected elements of your own site or app, by using more specific CSS selectors, or !important flag. e.g., .more .specific .selector p { color: inherit; }.
• If your CSS classes effect our components styles: You can write some new CSS rules to override the effected elements of our components, by using .e-main selector and mentioning the target element under it. e.g., .e-main p { color: inherit; }. Yes, when you’re initializing the components, you already define class attribute for them and set it to e-main.

iframe window

You can load an iFrame web-app inside of your site or app to show Eliq components in there!

Intro to iframe window

Using the Eliq iframe web-app is straightforward! Just extract the .zip file and open the index.iframe-v1.html file inside. Treat this sample HTML file as if it were your own site or app. It demonstrates how to load the iframe, handle authentication, and display various components. It’s an easy way to understand how to integrate and use the iframe setup effectively 🙌

Our special component

When loading the web-app, always include the initializer-v1 component (in the URL Query Parameters) along with your desired components. Why is that? Well, it prepares the environment for other components to get loaded successfully and show data to the user.

As indicated in the sample index.iframe-v1.html file, the Eliq web-app supports only specific URL Query Parameters, which vary depending on the components you are loading. The file details all possible scenarios and the parameters for each component.

Important! Component-specific parameters (like location-id) are optional and depend on the component being loaded. The com parameter is ALWAYS required and must include at least two components:

• initializer-v1 component, which prepares the environment for the successful loading and display of other components.
• Any other supported component. For a full list of supported components, refer to the index.iframe-v1.html sample file.

How to use iframe window

1. As explained earlier, use Eliq API to receive a ticket-id with status = completed.
2. Setup an iframe in your HTML. Its src attribute should point the Eliq hosted web-app which holds all of the components. Contact us to receive the URL.

Generally speaking, all you need to do is to load the Eliq hosted web-app with some special URL Query Parameters and that’s it! Based on the provided parameters, the web-app loads a special component. e.g., {url}/?com=initializer-v1,full-advisory-v1&ticket-id=xxx&location-id=123456 will do the following operations:

• Loads initializer-v1 component and authenticates the user with the provided ticket-id.
• Loads full-advisory-v1 component and gives it location-id to show the data of the desired location ID.

Important files or assets

There’s none! With the iframe approach, you’re simply embedding the Eliq web-app within your site or app. Unlike the web-component method, where you host assets yourself and adjust files like DEP_style.css, DEP_config.json, or icons/images in the eliq-assets folder, you don’t need to manage these customizations yourself. Instead, you can contact us directly to request any customizations you need.

‍

The initializer component responsibilities

• Authenticate the user: So if you like to authenticate/unauthenticate the user, the only component that you need to deal with is actually the initializer-v1 component! All of the other components are in contact with the Initializer behind the scenes, and they automatically get authenticated/unauthenticated. Cheers🍺
• Change the language: You just tell the Initializer to load in your desired language, all of the other components change automatically.

Tip! Of course Eliq should already support your target language! i.e., not any language is supported. We’re constantly adding new languages to our databases… To learn more about what languages we support today, please contact us. en-GB is our default language.

• show/hide errors: Other components may throw errors if something goes wrong. Initializer can show such error message in a popup to the user. Turning this ability on, would make debugging easier.

Error handling

It doesn’t matter what approach you’re taking (whether it’s ‘web-component’ or ‘iframe’), you may receive errors from our components… Such errors might be because of different reasons, such as wrong JSON configurations, or server errors. Here’s the list of probable errors and the next steps that you can take to resolve them:

• Code initializer-config error message: May be shown ONLY IF you’re using the ‘web-component’ approach. It happens, if the Initializer component won’t be able to load the DEP_config.json file.
  Next step? You can:
  1. Make sure you have already uploaded the config file in the correct path: eliq-assets/DEP_config.json. Yes, eliq-assets folder MUST rest right beside your HTML file.
  2. Make sure DEP_config.json file’s JSON structure is correct. Obviously, wrong structures, make the codes to not be able to parse the file correctly.
• Any other error messages: Any error messages may happen, if components won’t be able to connect to the server successfully or receive an error from our server.
  Next step? You can open ‘Developer Tools‘ of your browser, open the ‘Console‘ tab, take a screenshot and send it to us.

Authentication of the user by Eliq API

In the sample HTML files for both the ‘web-component’ and ‘iFrame’ approaches, the crucial first step is user authentication. To achieve this, you need to provide the initializer-v1 component with a ticket-id that has a status of completed.

How to authenticate in brief

In order to authenticate the user, you need to do the following on the back-end side:

1. Get your own (client) access-token.
2. Get your user’s data.
3. Get your user’s access-token on behalf of them.
4. Get your user’s ticket id.
5. Mark your user’s ticket id as completed.

How to authenticate in details

Here’s the step by step guide on how to do that via the Insights API:

‍

‍1. Get access token on a user level (you can go to step 2 below if access token is retrieved already)

‍

1.1. Retrieve client token
The client token gives access to query data for all users/locations in the Eliq API.
Note! This should be kept safe and never distributed to the web components.

API endpoint:
POST {{url}}/v3/auth/token (documentation)

Request body:

POST
{
    "grant_type":"client_credentials",
    "client_id":"{{client_id}}",
    "client_secret":"{{client_secret}}"
}

Response 200 OK:

{
    "access_token": "JWT TOKEN",
    "token_type": "bearer",
    "expires_in": 3600
}

‍

1.2 Get user by external reference
Client will likely not know the user’s Eliq internal id (used later in Insights API), so let’s get user’s object.

API endpoint:
GET {{url}}/v3/users?extref={{user_ext_ref}} (documentation)
(authenticate with Bearer token access_token from previous step’s response)

Response 200 OK:

{
    "id":1234,
    "ext_ref":"external_reference",
    ...
}

‍

1.3. Retrieve user token
The user token gives access to query data for a specific user in Insights API.

API endpoint:
POST {{url}}/v3/auth/user/token (documentation)

Request body:
(use id from previous response as user_id)

POST
{
    "grant_type": "client_credentials",
    "user_id": {{user_id}},
    "client_id": {{client_id}},
    "client_secret": {{client_secret}},
    "requested_token_use": "on_behalf_of"
}

Response 200 OK:

{
    "access_token": "JWT TOKEN",
    "token_type": "bearer",
    "expires_in": 1800
}

‍

2. Get Ticket for WebComponents
(authenticate with Bearer token access_token from previous step’s response)

‍

2.1 Get autologin ticket

API endpoint:
GET {{url}}/v3/authentication/autologin/ticket (documentation)

Response 200 OK:

{
    "ticket_id": "TICKET_ID"
}

‍

2.2 Get completed ticket

API endpoint:
GET {{url}}/v3/authentication/tickets/:ticket_id
(use ticket_id from the previous response)

Response 200 OK:

{
    "id": "TICKET_ID"
    "status": "completed"
}

You can now use the id from the response in order to authenticate user in components.