Custom apps

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 choose the right one for your business needs.

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.

Access context with the Custom app SDK

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 your app requires this 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.

Option 1: Retrieve context once with getCustomAppContext

Use the getCustomAppContext function when your custom app needs to retrieve its context only once, during the initial load. This function returns a CustomAppContext object containing details about the environment, user, and app configuration.

Option 2: React to context changes with observerCustomApp

If your custom app needs to stay in sync with context changes, use the observerCustomApp function. This function invokes your callback whenever the custom app’s context changes, passing the updated CustomAppContext.

About CustomAppContext

The CustomAppContext provides information depending on the context in which the custom app is opened. The following properties are available in all contexts (including the Full screen mode):

• context object
  • 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. 
  • appConfig 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.
  • path property – the full URL of the current page inside the Kontent.ai app where the custom app is running.
  • pageTitle property – the title of the current page as displayed in the Kontent.ai UI.

The following properties are available when the custom app is displayed in a dialog over a content item editing page in Kontent.ai:

• context object
  • contentItemId property - the ID of the content item currently opened by the user. You can use this ID to fetch item details via our Management or Delivery API.
  • languageId property - the ID of the language currently selected by the user.
  • validationErrors object - contains information about validation errors on elements shown to the user.
    • Keys – element IDs
    • Values – arrays of validation error messages (strings)
  • currentPage property - set to “itemEditor” indicating the app is displayed in a dialog over the item editing page.

The following properties are available when the custom app is displayed in a full-screen mode or in a dialog over other pages (other than the content item editing page):

• context object
  • currentPage property - set to “other” when the app is displayed in full-screen mode or in a dialog over pages other than the content item editing page.

With this information, you can ensure the custom app works according to the provided settings, includes information relevant to the app's current context, and provides the user only with 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: For details on how to work with CustomAppContext in your custom apps, check the Custom app SDK API reference.

Adjust the dialog size

When your custom app is displayed in the dialog mode, you can also modify the dialog dimensions using the custom app SDK. To do that, call the setPopupSize function. It accepts the following parameters:

• width object
  • unit property - "px" or "%" indicating the unit of measurement for width
  • value property - numeric value representing pixels (px) or percentage (%) of the window width
• height object
  • unit property - "px" or "%" indicating the unit of measurement for height
  • value property - numeric value representing pixels (px) or percentage (%) of the window height

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.

1. In Kontent.ai, navigate to Environment settings > Custom apps.
2. Click Create new custom app.
3. In App name, type the name for your custom app.
4. In Hosted code URL (HTTPS), enter the publicly available URL of your deployed custom app.
5. From the Roles that can work with this app dropdown, select which roles will be allowed to use the custom app in the UI.
6. In Display mode, choose how the app will appear in the UI:
   • Full screen – opens from the main navigation for standalone workflows
   • Dialog – opens in a dialog in the bottom-right corner of the page for quick, contextual interactions
     • Custom apps opened in dialogs can access the context of the currently edited content item.
7. (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. Use a server-side proxy to store sensitive data.
8. 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 based on its display mode:

• Full screen: In Kontent.ai, navigate to Custom apps. From the list on the left, select your custom app.
• Dialog: If a custom app’s display mode is set to Dialog, you’ll see a Custom apps dialog in the bottom-right corner of the UI.

Both display methods only show custom apps that are available to you based on your assigned roles.