Custom apps

Jan Cerman

10 minutes

Custom apps are full-screen extensions that integrate seamlessly into Kontent.ai. Use them to embed external tools and data sources directly into your project. Unlike element-level custom elements, custom apps work at the environment level, letting you provide broader functionality to streamline workflows and improve collaboration.

Understand custom apps

With custom apps, you can extend the user experience and empower your teams by providing:

Centralized workflows: Streamline complex tasks by integrating external tools directly into the CMS. For example, you can add dashboards to monitor SEO metrics from tools like Google Analytics.
Enhanced content management: Enable custom views and enhanced functionality for content-related tasks. For example, you can create alternative views of content based on taxonomies or untranslated items for easier management.
Integrated analytics: Merge CMS data with third-party services for comprehensive insights. For example, you can develop a unified content analytics dashboard that combines internal data with external analytics tools.
Streamlined collaboration: Provide a single environment for accessing and managing content and related tools. For example, you can integrate a translation management system for real-time updates on translation progress.
Enhanced flexibility for developers: Build tailored solutions for specific business needs without altering core CMS functionalities. For example, you can develop bespoke dashboards to track CI/CD pipelines or manage environment-wide configuration.

Comparison: custom apps vs. custom elements

Both custom apps and custom elements are tools for adding new functionality to your Kontent.ai projects. But they serve different purposes. Review the comparison table below to make sure you choose the right one for your business needs.

Feature	Custom apps	Custom elements
Customizability	Extensive (UI navigation, dialogs)	Limited to content element customization
Development	Supports full applications, API-heavy	Lightweight, smaller widgets
Examples	Translation dashboards, analytics apps	Custom dropdowns, dynamic forms
Scope	Environment-level	Element-level
UI integration	Full-screen	Embedded in content items
Use cases	Broad workflows (e.g., dashboards)	Content-specific enhancements (e.g., widgets)

Create custom apps

Custom apps are HTML pages embedded within an <iframe> sandbox in a Kontent.ai environment. This means your custom app can be any web page or web application that meets your business needs.

Use custom app SDK for extra context

Using the Custom app SDK

, your custom apps can communicate with Kontent.ai to access information about the Kontent.ai environment, the signed-in user, and the app’s configuration. However, you only need to use the SDK if you require the extra context. To develop a custom app with access to your Kontent.ai data, start by creating a JavaScript application that uses the Custom app SDK.

Shell

npm install @kontent-ai/custom-app-sdk

The Custom app SDK provides the getCustomAppContext function, which lets the custom app retrieve its context in the form of a CustomAppContext object.

TypeScript

import { getCustomAppContext, CustomAppContext } from "@kontent-ai/custom-app-sdk";

const response: CustomAppContext = await getCustomAppContext();

if (response.isError) {
  console.error({ errorCode: response.code, description: response.description});
} else {
  console.log({ config: response.config, context: response.context });
}

The CustomAppContext provides the following information:

config object – contains the custom app JSON configuration as specified in the custom app settings, allowing you to adjust the way the custom app behaves dynamically.
context object – contains the context of where the custom app runs and who uses it.
- environmentId property – the environment ID is useful for making API requests against the environment.
- userId property – the user’s internal ID can be used to check if the user should have access or for logging purposes.
- userEmail property – the user’s account email can be used to ensure correct access levels, for example, only for users from a specific domain, such as @example.com.
- userRoles property – the user’s roles can be used to ensure correct access levels.
  - Each role is specified using its internal ID.
  - If the user has the Project manager role, you can also check the role’s codename property for project_manager. Custom roles don’t have a codename.

With this information, you can ensure the custom app works according to the provided settings and gives the current user only the information and controls they need. For example, a simple Hello World custom app that displays the information from the Custom app SDK might use the following code in its return statement:

// Uses the 'response' object from the previous code sample
<div>
  <div>
  <strong>Environment ID: </strong>
    <span> { response.context.environmentId } </span>
  </div>
  <div>
    <strong>User ID: </strong>
    <span> { response.context.userId } </span>
  </div>
  <div>
    <strong>User email: </strong>
    <span> { response.context.userEmail } </span>
  </div>
  <div>
    <strong>User roles: </strong>
    {
      response.context.userRoles.map(userRole => (
        <div>
        <strong>Id: </strong><span>{userRole.id}</span> <br />
        <strong> Codename: </strong><span>{userRole.codename}</span>
      </div>
      ))
    }
  </div>
  <br />
  <strong>Config: </strong>
  <pre>
    <code>{ JSON.stringify(response.config) } </code>
  </pre>
</div>

For details on how to work with CustomAppContext in your custom apps, check the Custom app SDK API reference

Host custom apps securely

Custom apps are HTML applications loaded in an <iframe>. They need to be hosted so the browser can fetch the file. You need to host your custom apps yourself or use a service like Netlify

If you decide to host your custom app on your own servers, you need to:
- Set up the appropriate domain certificate for the server.
- Make sure the server sends the X-frame-options (or Content-Security-Policy) header to specify an allowed origin, in this case, https://app.kontent.ai. For more details, see the MDN Web Docs.
If you’d like to test your custom apps locally, use a secure tunnel to your localhost. You can use a service like ngrok that connects to your local application and provides a secure public URL for access from Kontent.ai.

Your custom app is separated from the rest of Kontent.ai through the sandbox attribute

on the <iframe>. The following sandbox flags are enabled:

allow-forms – allows form submission
allow-scripts – allows JavaScript to run inside the <iframe>
allow-popups – allows popups
allow-downloads – allows downloading files from within the custom app
allow-same-origin – allows the document to maintain its origin
allow-modals – allows modal dialogs
allow-storage-access-by-user-activation – allows storage access (e.g. cookies or local storage)
- Keep in mind that this is a 3rd party context. You need to set cookies attributes SameSite=None; Secure to use cookies.

Add custom apps to your project

Once you have implemented your custom app, it’s time to add it to Kontent.ai. You can add as many custom apps as you need.

In Kontent.ai, navigate to Environment settings > Custom apps.
Click Create new custom app.
In App name, type the name for your custom app.
In Hosted code URL (HTTPS), enter the publicly available URL of your deployed custom app.
From the Roles that can work with this app dropdown, select which roles will be allowed to use the custom app in the UI.
(Optional) In Parameters {JSON}, enter a JSON object specifying configuration details for your custom app.
- The JSON parameters enable you to configure your custom app and reuse it in various contexts. For example, you can add your custom app multiple times and configure it differently for specific roles.
- Never store your API keys or any other sensitive data in the JSON object. It’s not secure! Use server-side proxy to store sensitive data.
Click Save changes.

The custom app becomes immediately available to users with matching roles.

You can also manage custom apps using Management API.

Use custom apps

With your custom app set up in your Kontent.ai environment, you can start using it.

In Kontent.ai, navigate to Custom apps.
From the list on the left, select your custom app.
- The list shows only the custom apps that are available based on your role.