cs-icon.svg

Marketplace App Manifest

An App Manifest is the representation of an app within Contentstack, encapsulating the app's identity, behaviors, and permissions within the ecosystem. This foundational entity holds crucial metadata necessary for the installation, management, and behavior of an app while it operates within Contentstack.

This detailed document acts as a comprehensive guide to understanding the significance, structure, and management of App Manifests. Its primary goal is to illuminate the core components and features that constitute an App Manifest, shedding light on how it influences an application's presence within Contentstack.

As a foundational entity controlled by the organizations in Contentstack, an App Manifest holds information such as the app's name, description, visibility settings, event interactions, and authorization scopes. A thorough comprehension of these aspects is crucial for configuring, installing, and effectively managing an application's behavior within Contentstack.

Supported Attributes for App Manifest:

App Manifest Example

Let’s look at an example of an App Manifest.


{
  "uid": "659e7d2a3079300012b23803",
  "name": "My Awesome App",
  "description": "This app does wonders",
  "target_type": "stack",
  "visibility": "private",
  "framework_version": "1.0",
  "version": 2,
  "ui_location": {
    "locations": [
      {
        "type": "cs.cm.stack.sidebar",
        "meta": [
          {
            "uid": "659e7e0cf****5626786803e",
            "path": "/sidebar",
            "enabled": true,
            "required": false,
            "signed": true,
            "description": "This app provides some wonderful insights about your entry"
          }
        ]
      }
    ]
  },
  "webhook": {
    "enabled": true,
    "custom_headers": [],
    "http_basic_auth": "username",
    "http_basic_password": "password",
    "target_url": "https://example.com/webhook",
    "channels": [
      "cs.apps.installations.install",
      "content_types.entries.create"
    ],
    "notifiers": [],
    "branch_scope": "$all"
  },
  "oauth": {
    "client_id": "ox_Hxe74BKqBo-DQ",
    "client_secret": "dWhzhSIccRwc7sEB6a-***ShB8wLtzUA",
    "redirect_uri": "https://example.com/oauth/callback",
    "user_token_config": {
      "enabled": false,
      "scopes": [],
      "allow_pkce": false
    },
    "app_token_config": {
      "enabled": false,
      "scopes": []
    }
  },
  "hosting": {
    "provider": "external",
    "deployment_url": "http://localhost:3000"
  },
  "organization_uid": "blte***e9b6abc4d33c",
  "created_by": {
    "uid": "blt0c2c***ec5a7bde6"
  },
  "updated_by": {
    "uid": "blt0c2c***ec5a7bde6"
  },
  "created_at": "2024-01-10T11:19:06.029Z",
  "updated_at": "2024-01-10T11:22:52.268Z"
}

Manifest Properties

UID (System Defined)

Type: string

Description: Specifies the identity of the app.

Code: "uid": "659e7d2a3079300012b23803"

Name (Required)

Type: string

Description: Specifies a name of the app. This name is used across multiple locations where the app appears.

Minimum length: 3

Maximum length: 20

Code: name: "My Awesome App"

Description (Optional)

Type: string

Description: Specifies a short description of the app.

Maximum length: 2000

Code: description: "This app does wonders"

Target Type (Optional)

Type: string

Description: Specifies the type of the app.

The Target Type property can be defined as either "stack" or "organization". This specifies whether the app can be installed at the stack level or organization level. If this property is not specified, the app is considered a stack app by default. This property once defined, cannot be modified later.

Code: target_type: "stack"

Framework Version (System Defined)

Type: string

Description: Specifies the framework version used while creating your app.

The Contentstack Apps Framework uses versioning to maintain compatibility with existing applications, ensuring that framework modifications do not disrupt apps unexpectedly.

Code: "framework_version": "1.0"

Version (System Defined)

Type: number

Description: Specifies the version number of the app.

The version number will be displayed next to your app's name during the app installation. Initially, the app is generated with the version number 1 and thereafter, it auto-increments with each subsequent update.

Code: "version": 1

Visibility (System Defined)

Description: Specifies whether the app is private or not.

The Visibility property can be defined as private, public, or public_unlisted. By default, newly created apps are set as private, allowing installation only within the app developer's organization. When an app is marked as public or public_unlisted, it becomes available for installation in any Contentstack organization. Public apps are listed on the Contentstack Marketplace, while public_unlisted apps require the developer to provide the installation URL for access.

Code: visibility: "private"

UI Location (Optional)

Description: Specifies where the app will be visible.

The UI Location specifies where the app appears in the product interface, and enables configuration of location-specific options. You can specify multiple locations for an app. Also, some framework APIs are available only to apps in certain locations. See About UI Locations for more information.

The ui_location configuration contains a list of locations, each specifying its type and individual meta configurations.

Let's take a look at the list of all location types supported by an organization app:

  1. App Config Location (cs.org.config): Contentstack lets you manage custom configuration for your app through App Config Location.

Now, let's explore the list of all location types supported by a stack app:

  1. Custom Field UI Location (cs.cm.stack.custom_field): Contentstack lets you build customizable fields through Custom Field UI Location.
  2. Dashboard UI Location (cs.cm.stack.dashboard): Contentstack lets you customize your dashboard view by adding new widgets through Dashboard UI location.
  3. Asset Sidebar Location (cs.cm.stack.asset_sidebar): Contentstack lets you extend the asset management capability through Asset Sidebar UI location.
  4. App Config Location (cs.cm.stack.config): Contentstack lets you manage custom configuration for your app through App Config Location.
  5. RTE Location (cs.cm.stack.rte): Contentstack lets you enhance the capabilities of your JSON Rich Text Editor through RTE Location.
  6. Full Page Location (cs.cm.stack.full_page): Contentstack lets you build full page applications through Full Page UI location.
  7. Field Modifier Location (cs.cm.stack.field_modifier): Contentstack lets you extend capabilities of the fields through Field Modifier UI location.
  8. Sidebar Location (cs.cm.stack.sidebar): Contentstack lets you extend the capabilities of the entry editor through Sidebar UI location.

Properties that may be specified for each location:

  • name (optional): Specifies the name of the location. This will be displayed at the location after app installation. If this property is not specified, the app name is used as the location name. For multiple configurations of the same location, ensure each has a distinct and appropriate unique name.
  • signed (optional): When enabled, Contentstack adds a JWT Token to the initial HTTP request made for your app's first page. This token can be used to verify if the request originated from Contentstack. Please refer Signed Locations for more information.
  • path (optional): Enables you to define the location relative to the base URL where the app is hosted. This is particularly useful when the developer intends the app to appear in multiple locations.
  • enabled (optional): Allows you to define whether the location is visible after the app installation. By default, a location without this property is treated as enabled. Users can manage this option post-installation by accessing the UI Locations tab on the configuration screen.
  • required (optional): When enabled, the location becomes mandatory and cannot be disabled after the app's installation. Locations without this property are, by default, considered optional.

Code:


"ui_location": {
    "locations": [
      {
        "type": "cs.cm.stack.sidebar",
        "meta": [
          {
            "uid": "659e7e0cf****5626786803e",
            "path": "/sidebar",
            "enabled": true,
            "required": false,
            "signed": true,
            "description": "This app provides some wonderful insights about your entry"
          }
        ]
      }
    ]
  }

Webhook (Optional)

A webhook provides a mechanism or a method for enabling real-time communication and data exchange between Contentstack and your application.

Properties that can be specified for a webhook:

  • enabled (required): Allows you to define whether the webhook is active after the app installation. Users can view execution logs of the webhook post-installation by accessing the Webhook tab on the configuration screen.
  • target_url (required): This URL will receive a notification when the webhook is triggered. Only HTTPS endpoints are allowed, and localhost is not supported. To secure the target_url with basic authorization, provide the necessary details in the http_basic_auth and http_basic_password fields. You can also provide custom_headers to further secure the URL.
  • channels (required): Channels describe the list of all events for which the webhook is subscribed. Below is a complete list of all events supported by the Contentstack App Framework:
    MethodDescription
    cs.apps.installations.installApp installed
    cs.apps.installations.uninstallApp uninstalled
    cs.apps.installations.updateApp installation updated
    cs.apps.installations.upgradeApp version updated
    content_types.entries.createAny entry is created
    content_types.entries.updateAny entry is updated
    content_types.entries.deleteAny entry is deleted
    content_types.entries.environments.publish.successAn entry is successfully published in any environment
    content_types.entries.environments.unpublish.successAn entry is successfully unpublished from any environment
    content_types.createNew content type is created
    content_types.updateAny content type is updated
    content_types.deleteAny content type is deleted
    assets.createNew asset is created
    assets.environments.publish.successAn asset is successfully published in any environment
    assets.updateAny asset is updated
    assets.deleteAny asset is deleted
    assets.environments.unpublish.successAn asset is successfully unpublished from any environment
    global_fields.createNew global field is created
    global_fields.updateAny global field is updated
    global_fields.deleteAny global field is deleted
    releases.environments.deployAny release deployed on all environments.
  • notifiers (optional): Notifiers specify the list of email addresses to notify whenever the Circuit Breaker disables the webhook. By default, the creator of the app and the user who installs it will receive notifications. However, for additional users to receive alerts, configuration is necessary. Contentstack sends the email alert to the specified user(s).

Code:


"webhook": {
    "enabled": true,
    "custom_headers": [],
    "http_basic_auth": "username",
    "http_basic_password": "password",
    "target_url": "https://example.com/webhook",
    "channels": [
      "cs.apps.installations.install",
      "content_types.entries.create"
    ],
    "notifiers": [],
    "branch_scope": "$all"
  }

OAuth (System Defined)

Contentstack enables external applications and services to access its APIs using the OAuth 2.0 protocol. During app creation, OAuth configuration is set, and users can later update details like redirect URL and scopes for both user and app token configurations. These settings are essential for generating an access token, granting access to the Contentstack APIs.

Properties that can be specified for a configuring OAuth:

  • client_id (system defined): Identifies your application and frequently appears in the OAuth negotiation URLs.
  • client_secret (system defined): Acts as a secret credential when exchanging tokens with Contentstack.
  • redirect_uri (required): The Redirect URL is where the authorization server sends users after they've successfully authorized the app. It's important to keep this URL secure to prevent redirection to random places. Developers need to register one or more redirect URLs when setting up the app. Users can set up to 10 redirect URLs, and the first one listed becomes the default.
  • user_token_config (system defined): Specifies the scopes and allow_pkce options for user token flow.
  • app_token_config (system defined): Specifies the scopes for app token flow.

Code:


"oauth": {
    "client_id": "ox_Hxe74BKqBo-DQ",
    "client_secret": "dWhzhSIccRwc7sEB6a-6bUShB8wLtzUv",
    "redirect_uri": "https://example.com/oauth/callback",
    "user_token_config": {
      "enabled": false,
      "scopes": [],
      "allow_pkce": false
    },
    "app_token_config": {
      "enabled": false,
      "scopes": []
    }
  }

Hosting (System Defined)

For an app to be accessible, Contentstack needs to know the URL of the app. Initially, during app creation, the default URL is set to http://localhost:3000. You can later update it to match wherever your app is running. For frontend apps, there's also the option to host directly with Launch.

Properties that may be required to be specified when configuring hosting:

  • provider (required): A provider determines the type of hosting option you have configured. Currently, we support two providers: launch and external. When configuring hosting with Launch, you must provide details such as project_uid, environment_uid, and the deployment URL. However, if you opt for an external provider, only the deployment URL needs to be specified.
  • deployment_url (required): Contentstack uses this public URL to access your application. During development, you may choose to use localhost. However, for the app to be accessible to others, it needs to be hosted on the internet.

Code:

 
 "hosting": {
    "provider": "external",
    "deployment_url": "http://localhost:3000"
  }

Organization UID (System Defined)

Description: Specifies the organization in which the app is created.

Code: "organization_uid": "bltb00c436e709d1865"

Created By (System Defined)

Description: Specifies the identity of the user who created this app.

Code: "created_by": {"uid":"blt65a****e72183ade"}

Updated By (System Defined)

Description: Specifies the identity of the user who last updated the app.

Code: "updated_by": {"uid":"blt65a****e72183ade"}

Created At (System Defined)

Description: Specifies the timestamp when the app was created.

Code: "created_at": "2021-07-06T05:02:58.868Z"

Updated At (System Defined)

Description: Specifies the timestamp when the app was last updated.

Code: "updated_at": "2021-07-06T05:02:58.868Z"

Was this article helpful?

More articles in "Working with Developer Hub"

About Developer Hub

Learn more

Types of Apps

Learn more

Creating an App in Developer Hub

Learn more

Installing your App via Developer Hub

Learn more

Configuring an App

Learn more

Managing your Apps

Learn more

Uninstalling an App

Learn more

Deleting an App

Learn more

Managing Webhooks in an App

Learn more

App Hosting

Learn more

App Versioning

Learn more
^