# Custom Widgets

In this article, you’ll learn everything about Custom Widgets in Happeo — what they are, how to create them, and how they can extend your intranet’s functionality.

**Accessibility:** Custom Widgets are available in the **Enterprise Package** only.

## What are Custom Widgets?

**Custom Widgets** cover two types of widgets you can add into your intranet:

- **Embedded Widgets:** These display external content inside an iframe. They’re straightforward to set up and useful when you simply want to show dashboards, tools, or web pages inside Happeo.
- **Custom Apps:** These go a step further, allowing deeper integrations with Happeo, such as creating fully integrated Page Widgets or Custom Search Connectors. Developers can use code templates and Happeo’s UI Kit to build them.

Together, these two options give organizations flexibility: sometimes you only need a quick embed, and other times you want a custom-built app that interacts more closely with your intranet.

Unlike the standard iFrame Widget, Custom Widgets bypass some sandboxing restrictions. This means they can display web content or applications that wouldn’t normally load in a secured iframe — opening opportunities to:

- Bring specialized tools and dashboards directly into the intranet.
- Streamline workflows by reducing the need to switch between platforms.
- Centralize external applications so employees always have a single place of truth.

⚠️ Because Custom Widgets are not sandboxed, only platform **admins** should create and manage them, with careful attention to security and governance.

## Use Cases

Custom Widgets are most valuable when your organization needs integrations or tools in Pages that are **unique to your internal workflows** and not available in Happeo’s App Marketplace.

Some practical examples of how organizations use Custom Widgets include:

- **Internal dashboards:** Embed real-time business dashboards (e.g. sales performance, project KPIs, or customer service metrics).
- **Proprietary tools:** Bring your organization’s own applications — such as a custom CRM, HR portal, or expense management tool — directly into Happeo so employees can access them without switching platforms.
- **Custom Search Connectors:** Create search integrations that pull results from your own internal knowledge bases, databases, or other systems.

By building these integrations as Custom Widgets, organizations **extend their intranet beyond the standard app ecosystem** and centralize access to all the digital tools employees need — whether they’re off-the-shelf Marketplace Apps or custom-built solutions.

## Best Practices

To get the most value from Custom Widgets while keeping your intranet secure and maintainable, consider the following best practices:

- **Validate URLs and hosting environments:** Always confirm that the URL of your Custom Widget works within an iframe and is served over HTTPS. Where possible, host applications on secure, reliable servers with clear access policies.
- **Test before publishing:** Keep apps in the **In development** or **Testing** stage until they have been fully validated. Only move them to **Published** once they’ve been reviewed for both functionality and security.
- **Define ownership and lifecycle:** Assign clear ownership for each Custom Widget. Owners should be responsible for ongoing updates, support, and removal when the widget is no longer relevant.
- **Document and communicate:** Document how each Custom Widget works, who manages it, and what it should be used for. Share this information on your intranet so employees know which apps are official and supported.

## Create a Custom Widget

**🔑 Permissions:** Custom Widgets can be created only by **platform admins** or users with **admin rights**.

1. Click your **avatar** in the top-right corner and open the **Admin Settings**.
2. Then go to **Apps** > **Custom apps**.
3. Select **Add custom widget**. You will then be presented with two options:

### Option 1: Embedded Widget

An **Embedded Widget** is displayed inside an iframe. This option allows you to show external content in Happeo Pages, but the content does not interact directly with Happeo itself.

When creating an embedded widget, you’ll be asked to provide:

- Widget name
- Widget URL
- Scopes (you can select multiple)  - User ID  - User primary email  - User organization ID

**What are scopes?**– Scopes define what user-related information can be passed into the iframe when the widget loads. They are essentially permissions that allow the external content to “know” something about the person viewing it.

#### What is the “Secret?”

The _**Secret**_ is a private key generated by Happeo. It’s used to **encode the JWT (JSON Web Token)** that Happeo injects into the iframe name tag whenever the Embedded Widget runs. That JWT contains the scopes (permissions) you requested, along with user and organization identifiers. Your app can then use the _Secret_ to **verify the integrity** of the JWT and confirm that the request truly comes from Happeo (not a malicious actor).

- **Expiry:** The JWT has a **1-hour lifetime**. After that, clients should expect to receive/refresh a new token; expired tokens will fail verification.
- **Rotation:** Treat the Secret like a password. **Rotate it periodically** (and immediately if you suspect exposure). When you rotate, **update your server-side verification** to use the new Secret; previously issued JWTs will fail once verification switches.
- **Storage:** **Never** expose the Secret in client-side code, repositories, or logs. Keep it in a secure server-side store and log verification failures for monitoring.

#### Ensuring the URL Works

The ability of your chosen URL to display depends on the server hosting the domain. Some domains have security restrictions in place that may prevent them from loading inside an iframe.

To check if your URL will work as a Custom Widget:

1. Open this [testing tool](http://w3schools.com/tags/tryit.asp?filename=tryhtml_iframe).
2. Replace the default content with the following snippet:   1. `<iframe src="https://www.[your-url]"></iframe>`
3. Click **Run** in the top-left menu.

- If the URL appears in the right-hand preview, it will also work as an Embedded Widget in Happeo.
- If the preview is blank, the URL will not load in Happeo.

#### Formatting the URL Correctly

- Always include _**https://**_ before the domain. For example:  - **Correct:** _https://hs.fi_ or _https://www.hs.fi_
  - **Incorrect:** _hs.fi_ or _www.hs.fi_
- If the URL is misspelled or formatted incorrectly, Happeo will flag the error in the preview.

#### Finalizing Your Widget

Once you’ve entered all required fields, click **Add widget**. You’ll be redirected back to the Custom Apps panel in the Admin Settings, where you’ll see a confirmation of your new embedded widget.

### Option 2: Custom App

A **Custom App** extends Happeo’s functionality by allowing deeper integration, such as creating fully integrated Page Widgets or custom Search Connectors.

You will need to provide:

1. Widget name.
2. Target section.   1. Pages – Page widgets.   2. Search – Search Connectors/Apps.
3. [Slug](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry) (the portal to rendering inside Happeo; required for initialization of the component).
4. Code from your computer.   - 💡 To help you get started, Happeo provides prebuilt templates in React, VanillaJS, and Lit. These templates offer a quick foundation so developers don’t have to start from scratch. Browse our [Custom Widget templates](https://github.com/happeo/custom-widget-templates).
5. (Optional): Setup URL.

#### What is a Setup URL?

- The **Setup URL** is displayed only to admins who are configuring the app.
- When opened, Happeo automatically appends a **JWT token** (as a URL parameter called _**token**_).
- That token allows your app to recognize which user and which organization is opening the setup page.
- This means the Setup URL can be used to guide the admin through additional configuration steps for the app (for example: connecting an external service, choosing data sources, or setting permissions).

The Setup URL is valuable because it gives organizations a controlled way to integrate external systems. Instead of pushing configuration into the code itself, admins can manage and update integrations dynamically through this dedicated endpoint — making the intranet both extensible and easier to maintain securely.

💡 For a consistent look and feel, developers can also use [Happeo’s UI Kit](https://uikit.happeo.com/), which provides ready-made design components so that Custom Apps visually match the rest of your intranet.

#### Finalizing Your App

Once you’ve entered all required fields, click **Add widget**. You’ll be redirected back to the Custom Apps panel in the Admin Settings, where you’ll see a confirmation of your new Custom App.

## Manage Custom Widgets

⚠️ **Important:** New Custom Widgets automatically start in _Development_ mode, where **only admins can see them**. To make them available more broadly, move them to _Testing_ or _Published_ once you’ve validated functionality and security.

Once you’ve created Custom Apps or Embedded Widgets, you can manage them from the **Custom Apps panel**. The panel provides key details for each app, including:

- Widget name.
- Status.
- Widget URL.
- Scope.
- Date modified.

When you open a specific app, you’ll have several management options:

- **Share:** Control who can access the app. You can share it with your entire organization or restrict it to specific users and groups. This ensures that the right tools are available to the right people, without cluttering the intranet for those who don’t need them.
- **Permissions:** Assign roles such as _Developer_, _Tester_, _Viewer_, or _No permissions_.
- **App Progress:** Define the stage of the app — _In development_, _Testing_, _Published_, or _Unpublished_. This staging process supports good governance practices by ensuring only validated apps are widely used, while experimental apps remain safely in testing.
- **Edit:** Update the widget’s details as needed. Remember to click **Save changes** at the bottom to apply your updates.
- **Delete:** Remove the app.

## FAQ

### General Usage

#### How do Custom Widgets differ from Marketplace Apps?

Custom Widgets and Marketplace Apps share the same underlying concept. The difference lies in availability:

- **Marketplace Apps** are available publicly for installation.
- **Custom Widgets** are built for and restricted to your Happeo environment only.

#### Can I use Custom Widgets on mobile?

Yes. In the Happeo mobile app, Pages (including Custom Widgets) render in a webview much like on desktop, scaled for smaller screens.

### Where can I find technical documentation?

You can find the full technical documentation [here](https://developers.happeo.com/reference/customwidgets).

### Security & Governance

#### Can Custom Widgets access all intranet data?

No. Custom Widgets can only access the user information that you explicitly allow via scopes. They do not automatically gain access to Happeo content, posts, or files.

### Functionality & Limitations

#### Can Custom Widgets trigger actions inside Happeo (e.g. update a page)?

**Partly.** Developers can use the **widget-sdk** to perform specific, scoped actions within the widget’s context using the current user’s permissions.

#### Can I reuse the same Custom Widget across multiple pages?

Yes. Once a Custom Widget is created, it can be added to any Page just like other widgets.

#### Is there a limit to how many Custom Widgets I can create?

There is no hard technical limit within Happeo, but best practice is to keep the number manageable and relevant to avoid cluttering your Admin panel and intranet.

#### What happens if I disable or delete a Custom App or Embedded Widget that’s already added to a page?

If a Custom Widget is disabled or deleted, its preview within the page will show an error placeholder. Page editors can then remove the widget if they wish.

### Maintenance & Troubleshooting

#### What should I do if a Custom Widget stops working?

First, check if the external application or URL is down or has changed. If the app is still online, verify that the URL formatting, scopes, and Secret are still valid.

#### Can I update a Custom Widget without removing it from all pages?

Yes. Editing a Custom Widget in Admin Settings will update it everywhere it is used.