New
Work smarter, not harder with AI Content Type Generator. Learn more.
Search
Log in

FAQ / Extensibility

On this page

What is the difference between webhooks and app events?

Webhooks and App Events are a quite similar concept but apply to different use cases.

If you don’t have control over the backend that receives the events, for example when sending events to a third party service, then you want to use our traditional webhooks. Sending webhooks directly to a third party service provider might require you to apply payload transformations before the webhook is sent which is only possible for traditional webhooks.

When you build the backend yourself it is simpler to apply the webhook transformations in your code rather than using our transformations dsl and you should use App Events.

You can think of App Events as a standard webhook for your app. The app developer can create an event subscription for the App Definition. The given endpoint will then receive events for each of the space-environments the app was installed to. There is no need to create or remove webhooks on app installation or uninstallation.

You can still use webhooks for cases where you don’t have control over the receiving end. We plan to support them going forward.

What is the limit on the app parameters?

“App parameters” is a JSON configuration object that is part of the App Installation. The JSON.stringify’ed value of this object cannot exceed 16 kb.

What is the best way to monitor the health of my apps?

For production apps you should apply the same best practices that you would for the rest of your production grade infrastructure and websites. Keep in mind that you must mention the list of trackers and their purposes in your apps privacy policy.

How do I update my app?

We’re not opinionated about how you release new versions of your app. If you host the app on Contentful, updating is as simple as uploading a new bundle in the app settings or using the cli command. You can release new versions of your app daily, weekly or monthly based on you and your users needs. However, we suggest that you only introduce backwards compatible changes, so that you don't break anything for your users.

Is there a reason to still use service accounts / service users / bot users over App Identities?

We designed App Identities with service accounts and their use cases in mind. While currently some of our newer CMA endpoints are not yet enabled for App Identities we plan to do so in the long run. Once they are there shouldn’t be many use cases where you have to create, maintain and use service accounts.

What is the difference between app keys and app tokens?

App keys are a key pair where we keep the public key and you keep the private key. They are used to request app tokens. Once the app has requested and received an app token it can use this token to authenticate with our CMA. You can think of app tokens as the personal access token for apps. App tokens give apps the ability to access Contentfuls CMA without a real user present and also without the need to create service accounts.

How do I update my app keys?

We allow you to have up to three different active app key pairs. This allows you to create a new keypair and deploy it across your infrastructure before removing the old one. If you don’t pass a key id in the API call to create an App Token we check up to all three existing public keys you stored for the App.

What are any app size limits?

When you host your app on Contentful, there are some limitations for each bundle. See the documentation for what you need to consider.

The limits don't apply for apps that you host yourself. In either case, we recommend that you consider best practices for optimizing performance, such as splitting JavaScript bundles into chunks or loading resources asynchronously to reduce load times.

In what language can I build an app?

There are no restrictions when it comes to the programming language you use to build the backend. We provide a toolkit for node js but you can use any programming language you like.

For the frontend part of Apps you’re restricted to what runs in the browser. You want to use either Javascript or something that compiles down to Javascript like Typescript / Purescript.

Does Contentful provide app usage analytics?

No. At the moment we do not provide such functionality. If you would like to request new features or share your feedback, please fill out the app framework feedback form.

Which entities can app identities access?

App identities only have access to entities within the space environment the app is installed in. They can access the following entities:

  • ContentType

  • EditorInterface

  • Entry

  • Asset

  • Locale

  • Tag

  • Snapshot (only on master environment)

  • The app's own AppInstallation

  • Task

What roles and permissions do apps have?

An app access is limited to the one space and environment it is installed to. Depending on the access a user has it might be limited further. So if a user cannot update a particular field of a particular content type the app will render in read only mode for that particular field.

Can I charge for my app?

Yes. Contentful does not provide a built-in mechanism for billing app users through the App Marketplace, but you can list apps requiring a subscription and offer an alternative payment channel. To see how other apps monetize access, check out Optimizely, Jira, GlobalLink offerings on the marketplace.

What are the requirements for listing my app on the app marketplace?

To be considered for the marketplace listing, apps should fulfill the following criteria:

  • Provide clear value to end users

  • Offer publicly available user documentation

  • Have an official privacy policy and usage license

  • Provide user support and be actively maintained

To determine whether your app qualifies for the marketplace listing, submit a request to our technology partnerships team.

How do I install an app?

Contentful allows users to build two types of apps: marketplace apps and private apps. The installation process depends on the type of the app you want to install.

For marketplace apps, navigate to the app page in the App Marketplace and click Install now. Select the target space and — if you have multiple environments in the space — the target environment. Grant the app access to your space by clicking Authorize access.

App Installation Flow

Finally, fill out the required configuration fields (note that these vary from app to app) and save your settings. For faster access, you can also install Marketplace apps directly from within the web app by visiting the App menu tab in the main navigation.

For private apps, begin by creating an app definition under the App section of your organizational settings. The app definition includes the basic information about your app: name, URL, and target location. For apps using advanced App Framework features, this is where you generate public-private keys and subscribe to app events.

App definition illustration

Once you install the app definition, you can install the app into the target space the same way you install Marketplace apps. To read more about app installation and distribution, refer to our app development guide.

What is the difference between Apps and UI Extensions?

Apps are the next generation of UI Extensions. They are faster to build, update and manage and are easy to orchestrate when used in multiple spaces throughout your organization.  Features like App Identities and App events make it possible to build fully automated workflows with apps, whereas UI Extensions act on behalf of the user and require the user's input to accomplish a task. 

Apps and UI Extensions are compatible at the moment of this writing and share a lot of tooling, including the App SDK. While we plan to support UI Extensions into the foreseeable future, our current product efforts are focused on the app framework. For this reason, we encourage our customers to migrate their UI Extensions to Apps whenever possible to take advantage of the full range of extensibility features we offer. 

Who can install apps within my space?

To create an app definition in your organization, you have to be assigned the Developer, Admin or Owner organizational role. To install an app within your space, you have to be assigned either the Developer or Admin role.

Apps Organizational Roles

Can I customize the Contentful web app?

Yes, you can customize the web app by building apps, introducing UI extensions, or tweaking the standard behavior of field editors. An app is a single page application (SPA) consisting of HTML, CSS and Javascript files that we render in an iframe. The app framework provides a number of standard locations for integrating your app into the web app UI:

  • Entry field

  • Entry editor

  • Entry sidebar  

  • Dialogue

  • Page

Advanced features like App identities and App events allow your apps go beyond the immediate web app UI and modify content using the Content Management API (CMA). You will find more resources on these topics under the Extensibility section of the developer documentation.

How can I distribute the app I built?

If you are interested in making your app available to the wider Contentful community, you can apply to have your app listed on the App Marketplace or open a pull request to feature it in the Awesome Apps list we maintain.

Where can I host my app?

There are two ways to host your app, either using Contentful's built-in hosting which can be enabled in your app's settings or a third party. There are no special requirements for hosting your app with a third party, it only needs to be accessible through a public URL. You might choose to host your app on one of the common cloud and hosting platforms including AWS, GCP, Azure, Vercel, Heroku, Netlify, Glitch, Digital Ocean etc.

Do apps using identities count towards our user quota? 

No, apps do not contribute towards organizational user quota and can be created free of charge. However, for technical reasons, we limit the maximum number of app definitions that can be created per organization at 250 and the maximum number of installations that can be installed per environment at 50. For more information on app limits please refer to the Technical limits page.

add-circle arrow-right remove style-two-pin-marker subtract-circle remove