App definitions

AppDefinition is an entity type that stores all information about a single app on the organization level. By itself this entity does not do anything. To use an app you need to create an AppInstallation in a selected space-environment pointing to your definition.

Definitions centralize app management within an organization. Changes to a definition will automatically be propagated to all of its installations. There is no need to update installations when updating a definition.

A definition contains information about whether the app frontend is hosted by Contentful or outside of Contentful. If the app frontend is hosted outside of Contentful, the definition will have a src (Third party URL or localhost for development as a string) property. If the app is hosted by Contentful, the definition will have a bundle property, which is a link to an AppBundle entity. The AppBundle can contain just frontend assets, Functions code, or both. It is possible for an app to have both a bundle and src property only when the app has a bundle containing just functions code (no frontend) and then is using a Third Party URL to host the frontend.

App definition properties

• name: a human-readable name of the app
• src: publicly available source URL of the app; requires HTTPS with exception of localhost (for development)
• bundle: a link to an AppBundle if hosted on Contentful
• locations: list of places in the web app where the app can be rendered; see below
• parameters: definitions of configuration parameters

App locations

Locations are described in more detail in the App SDK reference.

The locations property is an array of one or more of:

Entry field location

All valid fieldTypes are:

• Short text: { "type": "Symbol" }
• Short text, list: { "type": "Array", "items": { "type": "Symbol" } }
• Long text: { "type": "Text" }
• Rich text: { "type": "RichText" }
• Number, integer: { "type": "Integer"}
• Number, decimal: { "type": "Number" }
• Boolean: { "type": "Boolean" }
• Date and time: { "type": "Date" }
• Location: { "type": "Location" }
• JSON object: { "type": "Object" }
• Entry reference: { "type": "Link", "linkType": "Entry" }
• Entry reference, list: { "type": "Array", "items": { "type": "Link", "linkType": "Entry" } }
• Media reference: { "type": "Link", "linkType": "Asset" }
• Media reference, list: { "type": "Array", "items": { "type": "Link", "linkType": "Asset" } }

Page location

When you add a page location in your AppDefinition, there is the possibility to add an optional navigationItem property to it.

1
{
2
  "location": "page",
3
  "navigationItem": {
4
    "name": "My app",
5
    "path": "/my-app"
6
  }
7
}

1
{
2
  "location": "page",
3
  "navigationItem": {
4
    "name": "My app",
5
    "path": "/my-app"
6
  }
7
}

If provided, a link will be added to the “Apps” navigation item in the Contentful web app pointing to your app installation.

Example

The following app definition is called “Hello world” which is served from https://example.com/hello-app.html and can be rendered both as an editing widget for short text fields and as an app configuration screen:

1
{
2
  "name": "Hello world",
3
  "src": "https://example.com/hello-app.html",
4
  "locations": [
5
    {
6
      "location": "entry-field",
7
      "fieldTypes": [
8
        { "type": "Symbol" }
9
      ]
10
    },
11
    {
12
      "location": "app-config"
13
    }
14
  ]
15
}

App definitions collection

Get all app definitions

Create a new app definition

App definition

Get an app definition

Update an app definition

Delete an app definition