> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/classic/embedded-integrations/getting-started-with-fastns-embedded-experience/previewing-and-integrating-widgets.md).
# Previewing and Integrating Widgets
## Previewing Widgets
* On the **Widgets** page, click the **Integrate** button.
* Click **Preview**.
* The **Preview** button opens the widget preview in a new browser tab.\
You can change the default `tenantId` by updating the query parameters in the URL.
> ⚠️ The preview page always shows the **DRAFT** version of the widget.\
> Use the `env` query parameter if you want to preview a widget that has been deployed to another environment.
## Setting up Custom Authentication
* A custom authentication flow can be created to validate user tokens whenever the widget is loaded.
**To enable custom authentication:**
1. On the **Widgets** page, click **Integrate**.
2. Go to the **Settings** tab.
3. Enable **Custom Authentication** and click **Save**.
* Once saved, a flow called `fastnCustomAuth` is automatically imported into your workspace and can be customized as needed.
By default, this flow uses a Fastn user token, but you can update it with your own logic or API calls to validate the token.
> ✅ When custom authentication is enabled, the `customAuth=true` parameter must be included in the widget URL.\
> This applies to both preview and iframe integration and ignores any `apiKey` passed in the URL.
If authentication succeeds, the widget loads normally. If it fails, an error message is displayed.
## Integrating Widgets in Your App
### Iframe Integration
* In the **Widgets** page, click **Integrate**.
* Select **Iframe** to generate the React or HTML code snippet.
* Copy and paste the code into your React application.
Update the configuration values in the snippet:
```javascript
projectId: "", // Workspace ID where the widget is configured
tenantId: "", // Tenant/end user identifier
authToken: "" // Token used in the custom auth flow
```
You can customize the default widget styling by clicking the **Styling** tab, making changes, and pressing **Save**.
### Headless React Package
The iframe approach uses Fastn’s UI and offers limited flexibility.\
For full customization, Fastn provides a **headless React package** that exposes the APIs and lets you build your own UI.
* Package:
* Example App:
* Live Demo:
## Overriding Widget Connector Auth Attributes
* You can override the default auth attributes used by a widget’s dependency connector.
#### **Steps**
1. On the **Widgets** page, click the widget name to open its configuration.
2. Under **Dependency Connectors**, click **Auth Attributes** for the connector you want to override.
3. Enter the auth attribute overrides as JSON.
#### **Example (Slack)**
```json
{
"clientId": "",
"clientSecret": "",
"params": {
"scope": "app_mentions:read,channels:history,channels:join,channels:manage,channels:read,chat:write.customize,chat:write.public,chat:write,files:read,files:write,groups:history,groups:read,groups:write,im:history,im:read,im:write,links:read,links:write,mpim:history,mpim:read,mpim:write,pins:read,pins:write,reactions:read,reactions:write,reminders:read,reminders:write,team:read,usergroups:read,usergroups:write,users:read,users:write,users.profile:read,users:read.email"
}
}
```
Click **Done**, then **Update** to save.
> From this point forward, the override credentials will be used every time a tenant uses the Slack widget.
## Filtering Widgets
Fastn allows you to dynamically show or hide widgets or actions based on tenant-specific logic.
**To enable filtering:**
1. Go to **Integrate** → **Settings**.
2. Enable **Widgets Filter**.
This will import a flow called `fastnWidgetsFilter` into your workspace.
{% hint style="info" %}
Every time the widget page loads, the widget list is sent to this flow for processing.
{% endhint %}
### **Example Input**
```json
"widgets": [
{
"id": "_knexa_c9085d88-85d0-4436-82c6-4e42d6aba4c6",
"name": "Slack",
"hidden": false,
"disable": false,
"subscribed": true,
"hideActions": [],
"disableMessage": "",
"subscriptionUrl": "",
"hideActionsByName": []
}
]
```
You can then update these configurations in the flow to reflect business logic (e.g., hide widgets for specific tenants).
### **Example Output**
```json
"widgets": [
{
"id": "_knexa_c9085d88-85d0-4436-82c6-4e42d6aba4c6",
"name": "Slack",
"hidden": true,
"disable": false,
"subscribed": false,
"hideActions": [],
"disableMessage": "",
"subscriptionUrl": "",
"hideActionsByName": []
}
]
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fastn.ai/classic/embedded-integrations/getting-started-with-fastns-embedded-experience/previewing-and-integrating-widgets.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
