Marketplace App Manifest

The App Manifest is the representation of an app within Contentstack, encapsulating the app's identity, locations, 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.

Users can view the app’s manifest by clicking the respective app and navigating to the “App Manifest” section. Users who can manage the app have access to the full view of the manifest, while other users in the organization can access the basic view of the app manifest.

Highlighted below is a comprehensive guide to understanding the significance, structure and management of App Manifest components such as the app's name, description, visibility settings, event interactions, and authorization scopes.

Supported Attributes for App Manifest:

• UID (System Defined)
• Name (Required)
• Description (Optional)
• Target Type (Optional)
• Framework Version (System Defined)
• Version (System Defined)
• Visibility (System Defined)
• UI Location (Optional)
• Webhook (Optional)
• OAuth (System Defined)
• Hosting (System Defined)
• Organization UID (System Defined)
• Created By (System Defined)
• Updated By (System Defined)
• Created At (System Defined)
• Updated At (System Defined)

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"

}

Type: string

Description: Specifies the identity of the app.

Code: "uid": "659e7d2a3079300012b23803"

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"

Type: string

Description: Specifies a short description of the app.

Maximum length: 2000

Code: description: "This app does wonders"

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"

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"

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

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"

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:

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

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"

          }

        ]

      }

    ]

  }

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:
  

  Method	Description
  cs.apps.installations.install	App installed
  cs.apps.installations.uninstall	App uninstalled
  cs.apps.installations.update	App installation updated
  cs.apps.installations.upgrade	App version updated
  content_types.entries.create	Any entry is created
  content_types.entries.update	Any entry is updated
  content_types.entries.delete	Any entry is deleted
  content_types.entries.environments.publish.success	An entry is successfully published in any environment
  content_types.entries.environments.unpublish.success	An entry is successfully unpublished from any environment
  content_types.create	New content type is created
  content_types.update	Any content type is updated
  content_types.delete	Any content type is deleted
  assets.create	New asset is created
  assets.environments.publish.success	An asset is successfully published in any environment
  assets.update	Any asset is updated
  assets.delete	Any asset is deleted
  assets.environments.unpublish.success	An asset is successfully unpublished from any environment
  global_fields.create	New global field is created
  global_fields.update	Any global field is updated
  global_fields.delete	Any global field is deleted
  releases.environments.deploy	Any release deployed on all environments
  branch.create-initiated	When branch creation is initiated
  branch.create-completed	When branch creation is completed
  branch.delete-initiated	When the branch deletion is initiated
  branch.delete-completed	When the branch deletion is completed
  branch_alias.assigned	When the branch alias is assigned
  branch_alias.unassigned	When the branch alias is unassigned

• 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"

  }

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": []

    }

  }

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"

  }

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

Code: "organization_uid": "bltb00c436e709d1865"

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

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

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

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

Description: Specifies the timestamp when the app was created.

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

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

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