Table of Contents

What you should know before embedding

Ramya Priya Updated by Ramya Priya

Embedding supports app-in-app capability and allows integration of Tellius components (Search, Vizpads, Insights) into another application.

Benefits of embedding

  • Enables white labeling
  • Facilitates unlimited customization as per unique requirements
  • Promotes reusability and adoption
  • Native apps can be powered by Tellius engines

Types of embedding

Tellius provides two types of embedding:

  1. via embedding URL (static and dynamic)
  2. via backend APIs

Embedding URL

Using the iFrame method, users can embed Tellius as part of another application. Here's how it works:

  • The embedding URL for different components will be available on Tellius platform.
  • Copy and code the URL into the required page.
  • Tellius interface will be retained in the embedding app.
  • The embedding app and Tellius communicate via postMessages. For every activity, the embedding app needs to send a request to Tellius, and Tellius will send the response. 

Choose embedding URLs if you need to,

  • Visualize results in Tellius interface
  • Cut down time and effort on development
Variations of using embedding URL

The embedding URL (obtained from Tellius) consists of the jwt (JSON Web Token). The jwt is a user token associated with the user who is logged in. Thus, it will be unique for each individual user. Based on the way the token is deployed, there are two different variations: static and dynamic. 

Static token

The embedding link is generated from Tellius and the required component is directly embedded in the host application. The view will be static irrespective of the user who is logged in to the application.

In this case, the jwt that comes with the embedding URL will be used. Say, if user X is logged in and embeds a Vizpad into another app, then users Y and Z will be able to view the same data as that of user X.

Choose static token method if you want to,

  • Embed Tellius components with read-only mode
  • Integrate Tellius components with minimal effort and control
Dynamic token

The embedding link is generated from login API and the required component is directly embedded in the host application. The view will be dynamic based on the user who is logged in to the application.

Here, the jwt will differ according to the user who is logged in. By this method, if a Vizpad belonging to user X is embedded, then users Y and Z will be able to view the Vizpad based on their roles and permissions.

Choose dynamic token method if you want to,

  • Deploy row-level policies
  • Enable customized views for different user roles
In the embedding URL, the jwt points to the user who is logged in. So, by static method, users Y and Z will be able to view the same Vizpad of user X. Dynamic method allows each user to have a customized view based on the user roles/permissions. Different jwt tokens → different users → thus different permissions.

The jwt can be changed dynamically using login API. The following are the steps to obtain the jwt.

How to get the jwt?

A login API needs to be called to generate the jwt. Since the login API depends on the username and password, each user will get a unique jwt.

  • The user sends a request using username and password.
  • Tellius sends a response with the token.
  • Include the token in the embedding URL.
Sample CURL request for Login API
curl 'https://qa.app.tellius.com/api/login' \
-H 'Connection: keep-alive' \
-H 'sec-ch-ua: "Chromium";v="92", " Not A;Brand";v="99", "Google Chrome";v="92"' \
-H 'Accept: application/json, text/plain, */*' \
-H 'sec-ch-ua-mobile: ?0' \
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)
						
Chrome/92.0.4515.107 Safari/537.36' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Origin: https://qa.app.tellius.com' \
-H 'Sec-Fetch-Site: same-origin' \
-H 'Sec-Fetch-Mode: cors' \
-H 'Sec-Fetch-Dest: empty' \
-H 'Referer: https://qa.app.tellius.com/log' \
-H 'Accept-Language: en-US,en;q=0.9' \
--data-raw '{"username":"superUser","password":"NewTellius11$"}' \ --compressed
Sample response with token
id: "fbd6e7ce-e2b4-4465-98cd-8151570d69d"8
refreshToken: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ...” token: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ7...”

APIs

In this method, Tellius provides you with the backend APIs for different functionalities. Tellius interface is not retained, and users are free to create their own UI. APIs call for more technical expertise.

Choose APIs if you need,

  • To develop own UI using Tellius APIs
  • More customization and control over your interface

Performing actions on embedded Tellius

Once Tellius is embedded into an app, the required actions can be performed from the Tellius interface. If not (in situations where only individual components are embedded), please make use of actionTypes provided for each Tellius component that is communicated via postMessage.

Glossary

  • iFrame - An inline frame (iframe) is an HTML element that embeds an HTML page within another app. 
  • JWT - JSON Web Token (JWT) is a unique encoded string that represents the identity of a user and securely transmits communication between two parties during an interaction.
  • postMessage() - A browser API that facilitates secure communication between Tellius and the embedding app.
  • WebSockets - A WebSocket is a bidirectional, stateful, faster (than HTTP) protocol used for client-server communication (mostly used for the Search component).

Limitations

  • SSO is not supported in iFrame.
  • For now, embedding of individual components (search bar, query results panel, list views) is not available.

Troubleshooting

  1. If you have any trouble with the embedding, go to the browser and open developer tools (or press F12).
  2. Click on the Console tab and check for any page loading errors.
  3. If the following error is found, then the cross-domain (CORS) setting is incorrect.
No 'Access-Control-Allow-Origin' header is present on the requested resource.

  1. Please reach out to the Tellius support team for assistance.

For more information, please check out the Embedding FAQs page.

Did we help you?

Contact