Eliq modules

At Eliq, you can use our modules 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! This guide is helpful for front-end developers who have a basic understanding of HTML, JavaScript, and CSS.

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

What are Eliq modules

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

• Eliq energy saving an advice card (advisory-card-v1)
• Eliq energy saving an advice detailed view (advisory-detail-v1)
• Eliq energy saving advises list view (advisory-list-v1)
• Eliq energy consumption chart (chart-v1)
• Eliq CO2 savior visualizer (co2-v1)
• Eliq Energy consumption compared to your previous usage (comparison-v1)
• Eliq EUC (Energy Usage Category) of your home (euc-v1)
• Eliq energy saving full advises view (full-advisory-v1)
• Eliq energy full insights view (full-insights-v1)
• Eliq home profile completion wizard (home-profile-v1)
• Eliq Energy consumption compared to your similar homes (similar-homes-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 Home Profile feature is designed to collect this info. From a user experience perspective, it’s highly recommended to include the Home Profile during on-boarding. Once we have that data, Eliq can calculate the following insights:

• EUC
• Similar Homes
• Customized Energy Advice

How can you use Eliq modules

You can use Eliq components in 2 ways:

• As web-components.
• By loading components in an iFrame.

Web-modules

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.

Implementation of Eliq web-modules

Using Eliq web-modules is simple! Just extract the webcom-v1.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 modules do we have available.
• What are each modules inputs.
• What are each modules 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🥳

The special component

There’s one special module among all of the other ones! That special module is called: eliq-core-initializer-v1. 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 module first, and then your desired module, because you already know it! It’s the foundation for other module.

Work-flow to initialise all modules

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. Get inspired from the sample codes of index.html file in the .zip file to learn how to initialize eliq-core-initializer-v1 module along with your desired component.
4. Use Eliq authentication API to receive a ticket-id with status = completed.
5. After having the ticket-id, provide it to the eliq-core-initializer-v1 component. And that’s it🥳

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.0.0/eliq-core.css">
• Include the following in your <body>: <script type="module" src="https://general-webcomponents.eliq.com/v1.0.0/eliq-core.js"></script>, and <script type="module" src="https://general-webcomponents.eliq.com/v1.0.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.

Loading modules in an iFrame

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

Implementation of Eliq iFrame web-app

Using the Eliq iFrame web-app is straightforward! Just extract the webcom-v1.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 🙌

Note! Where the src attribute of your iFrame window in your site or app should point to? To 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.

The special module

When loading the web-app, always include the initializer-v1 component 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.

Important! 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.

Here’s an important note: 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.

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 initialiser-v1 module 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.

So 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
}

What if the token expire during a session?
If the JWT token expire while an end user are using the web (should happen very rarely) an info message in the web component will ask the end user to reload the page. When the page is reloaded a new token should be generated and the user can continue to use the web.

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.