Publishing an app
Currently, Contentful’s Marketplace is open to only a select group of technology and integration partners.
If you or your organization wants to publish an app on the Contentful marketplace, please fill out this form and our partnerships team will reach out to you. We encourage you to reach out before you start development so we can assist during the process.
Remember that your customers use Contentful as the central hub for their content and publishing. When developing your app, consider how it can enrich the core functionality of Contentful and aim to build a polished experience with that in mind. Only apps that provide tangible value to customers will be listed in the marketplace.
To aid in creating an app fit for the marketplace, this document lists best practices for developing and securing an app, as well as informing you about what to expect from the review process.
The contents of this document are subject to change and will reflect updates we make to the review process.
Table of contents
Maintenance and support
Users need to be able to rely on your solutions, and should be able to contact you if they need help. Specifically, your app will need to be:
- Open source: As of January 2024, we require all partner apps listed on Contentful's Marketplace to be hosted in our Marketplace Partner Apps repository. This allows Contentful to maintain a degree of oversight over the code that's included in apps on the Marketplace, and to ensure our customers can directly inspect the code base for any app they have installed.
- Maintained: Your app should be kept up to date, reflecting changes in both your own service, and Contentful. This includes any dependencies required by your app, which should be kept at all times to the most recent version possible. (For apps in the Marketplace Partner Apps repository, we use Dependabot to continually update dependencies.)
- Documented: Users should be able to find instructions on how to use your app, preferably with examples on how to integrate it. Your marketplace listing should provide guidance to customers about how to use your app and point them to your website or support page if they need help. The documentation should be available in a public location.
- Supported: When users experience problems with your app, they should be able to contact you in a timely fashion. The marketplace listing must include a link to a form or an email address where users will receive support. For apps listed in the Marketplace Partner Apps repository, developers need to be responsive to security issues, dependency upgrades and other areas of concern that might be raised from time to time by the Contentful partner team.
Best practices in development
This section covers best practices for the development process. The goal is to create a seamless experience for both developers integrating your app, and content editors using it.
Configuration data for different aspects of the app should be stored in their appropriate locations.
- To configure the app for the entire space, use the configuration parameters during app installation.
- For content model or field level configuration, use instance parameters.
- If each entry needs to be configured individually, you can extend the content model and store the configuration data within the entry, for example within a JSON field.
You should make the process of installing your app as straightforward as possible.
- If your app renders in content type specific locations (entry editor, field editor, or entry sidebar) you should allow users to assign the app to Content Types of their choice in the App Configuration location. An example of how to do this can be found here.
If an app integrates a service that provides external methods of storing content, like an asset management app, it can be hard to synchronize data between Contentful and the external service. In these cases, storing only the references inside Contentful and keeping the data in the external service is common. We recommend adhering to the following best practices for storing references in Contentful data:
- References to external data should be validated to give users feedback on whether the referenced data exists in the external service.
- For entry fields that contain references to external data, your app should use the Entry Field location of the App SDK to resolve the reference and show a preview within Contentful, or visually notify the user if the reference is not valid. For an SKU field, for example, this can be as simple as making an API call to your service and displaying some text underneath the entry, stating whether it is a valid SKU or not. The more context the user gets when editing the field, the better. Again, in the example of a SKU, the displayed text could also contain the product name or other information.
- Customers might use Contentful to create complex publishing pipelines. To make integrating your app simple, we recommend kepping the amount of API calls necessary to resolve references to data in your service as low as possible.
The visual design for an app should be compatible with the existing user interface in the Contentful web app, to provide a seamless experience to the user. This can easily be done by using Forma36, a styling library built by Contentful with this use-case in mind. You are also free to use your existing brand or styling, but the visual fidelity should be kept in sync with the surround user interface. Above all, you should avoid mixing your own UI design with Forma36, as it can make it hard to distinguish which parts of the user interface belong to your app, and which do not.
Before finalizing your app, make sure you’ve tested every element, including installation, onboarding, and all other features to ensure they work and match your documentation. The best way to do this is to install the app from scratch on a new space, and to run through each piece of functionality. You should also test reinstalling your app in a space it has previously been uninstalled from, to prevent any issues around reconfiguring the app.
Security
To ensure that the app does not expose user data or otherwise pose risks to potential users, we suggest following the security best practices outlined in this section. This section is only relevant if you are authenticating users against a service outside of Contentful, or your app is using App Identities and Events.
If your app uses App Identities and Events, and you are not using a custom authentication method, consider implementing request verification.
There are two common patterns of handling authentication in apps, each with their own set of best practices, and they will be covered separately in the following subsections. We recommend following one of these patterns, but do not strictly require you to do this. If your authentication method differs strongly from those described below, we recommend finding out which of the described patterns more closely resembles your approach, and then considering how the security concerns might apply to your scenario.
Space scoped authentication
Authentication on a per-space basis involves configuring a single point of authentication for all users of the space that the app is installed to. This is usually done by accepting an API token or similar when installing the app into a space, and then storing it as part of the app configuration parameters.
The app configuration parameters are available to all app instances, so you must assume that any user of the space will be able to read tokens and credentials stored within them. To simplify changing the token in case it is leaked by a user, it should be easy to replace the token at any time. This process should not require re-installation of the app, and should instead allow use of the app configuration screen to overwrite the old token.
Additionally, when creating tokens for use in your app, or when directing users to do so through your service, we recommend adjusting authorization to only include the minimum required scope. For example, if the app requires a token to read data from a third-party service, the token should be scoped to read-only access on the side of the service. We recommend only having the token include write access when absolutely necessary.
Avoid storing any authentication tokens in Contentful, or changing any data in Content Types or Entries for the sake of authentication or authorization.
User scoped authentication
Authentication on a per-user basis involves separately authenticating every user in the space-environment that the app is installed to. This is usually done by implementing OAuth or credential based login as part of the UI-flow. For example, an app that adds a new button to the sidebar can choose to instead display a login window if the user isn't logged in. This way, the authentication is handled over the user's browser sessions, and no user data is exposed.
Avoid storing user or session related information in Contentful, or changing any data in Content Types or Entries for the sake of authentication or authorization.
Legal terms
Any app developer wanting to publish their app in the Contentful marketplace is subject to the Marketplace Terms of Service, which we require you to sign as part of the review process.
Marketplace listing
Once your application has been reviewed and approved, we will reach out to request the marketing information needed to create a public listing. After verifying that the information is complete and fit to be included in the listing, we will coordinate with you to set a date for publishing it.
