# Embedding Search

Using the following steps, you can embed (using iFrame) components of Tellius (Vizpads, Insights, Search) into your app.

{% hint style="info" %}
The **embedded app** refers to Tellius, whereas the **embedding app** refers to the app in which Tellius components are to be integrated.
{% endhint %}

1. Get the embedding URL from Tellius.
2. Include the embedding URL in the HTML of the required app.
3. Connect the app with Tellius.

### **Getting the embedding URL**

1. Navigate **Settings → Embed → Search**.

<figure><img src="https://content.gitbook.com/content/8GaK1h3pmgbR63x0ftET/blobs/Pvw2RaqzEpy3h7SZiTcd/image.png" alt="" width="563"><figcaption><p>URL from Settings page</p></figcaption></figure>

2. Click on **Generate Embed URL**. The following window will be displayed.

<figure><img src="https://files.helpdocs.io/6dnnwn52e3/articles/l5ga7pjexm/1745926654168/image.png" alt="" width="563"><figcaption><p>Generating Embed URL</p></figcaption></figure>

### **Direct Access URL (toggle):**

When enabled, users accessing the embedded URL are taken directly to the embedded Search interface (no login prompt). This only works when the token (passed via `utm_source`) has valid session context.

When disabled, users will be redirected to the Tellius login screen before reaching the embedded component. Use this when you want user-level authentication to be enforced on access.

**Expiry Time of URL:** Controls how long the generated embedding URL remains valid. Specify the duration in hours, days, or months. After the set time, the token (`utm_source` or similar context ID) expires, and the link becomes invalid.

**Select Business View:** Choose the Business View (BV) in which the search queries should execute.

Click on the **Copy** icon to copy the embedding URL.

### **Including the obtained URL**

An embedding URL looks like the following:

`https://domain/search?utm_source=ID`

Once you embed the URL, the Search page will be loaded.

If you want to deploy row-level permissions to the embedded Search, ensure that appropriate user-level policies are configured.

### **Connecting with Tellius**

1. The embedding app needs to send a message `INITIALIZE` to connect with Tellius.
2. Tellius validates and responds with `TELLIUS_INITIALIZED` message as an acknowledgment.

The following is a sample code to connect with Tellius:

```javascript
var telliusFrame ;
    document.querySelector("iframe").addEventListener("load", function() {
        telliusFrame = document.getElementsByTagName("iframe")[0].contentWindow;
        telliusFrame.postMessage('INITIALIZE', "*");
    })
    function receiveMessage(event) {
        if(event.data === 'TELLIUS_INITIALIZED') { 
            telliusFrame.postMessage({  //if you want to include an actionType 
                actionType: "required_actionType",
             }, "*");
        }
    }
window.addEventListener("message", receiveMessage, false);
```

As furnished in the code above, we use `window.postMessage` for communication between Tellius and the embedding app (two-way communication). The messages which are sent to Tellius from the embedding app are included in `telliusFrame.postMessage()`. With the help of the function `postMessage`, required actions can be performed.

To enable this communication and to receive messages, the embedding app needs to have `eventListener`. For every point clicked, or area selected/highlighted in the chart, Tellius will send a message to the embedding app.