App Descriptor

The app descriptor is one of the essential building blocks of Crowdin apps. The app descriptor is a JSON file (for example, manifest.json) that includes general information for the app, as well as the modules that the app wants to operate with or extend. It describes how the application will work, what resources will be used, etc. You can see an example below.​

App Descriptor Structure

{
   "identifier": "your-application-identifier",
   "name": "Your Application",
   "description": "Application description",
   "logo": "/assets/logos/app-logo.png",
   "baseUrl": "http://example.com",
   "authentication": {
       "type": "crowdin_app",
       "clientId": "your-client-id"
   },
   "events": {
       "installed": "/hooks/installed"
   },
   "scopes": [
       "project"
   ],
   "modules": {
       "project-integrations": [
           {
               "key": "your-module-key",
               "name": "Module Name",
               "description": "Module description",
               "logo": "/assets/logos/module-logo.png",
               "url": "/page/integration",
               "environments": [
                 "crowdin", "crowdin-enterprise"
              ]
           }
       ]
   }
}
identifier

Type: string (^[a-z0-9-._]+$)

Note: Don't use uppercase in the app identifier.

Required: yes

Description: A unique key to identify the app. This identifier must be <= 255 characters.

name

Type: string

Required: yes

Description: The human-readable name of the app.

baseUrl

Type: string (uri)

Required: yes

Description: The base URL of the remote app, which is used for all communications back to the app instance.
Once the app is installed in a workspace, the app's baseUrl can’t be changed without uninstalling the app beforehand.

This is important: choose your baseUrl wisely before making your app public.
The baseUrl must start with https:// to ensure that all data is sent securely between our cloud instances and your app.

Note: Each app must have a unique baseUrl. If you would like to serve multiple apps from the same host,
consider adding a path prefix into the baseUrl.

authentication

Type: Authentication

Required: yes

Description: Specifies the authentication type to use when signing requests between the host application and the Crowdin app.

description

Type: string

Description: The human-readable description of what the app does.
The description will be visible in the Crowdin UI.

logo

Type: string (relativeUri)

Description: The image URL relative to the app's base URL which will be displayed in the Crowdin UI.

events

Type: Events

Description: Allow the app to register for app event notifications.

scopes

Type: [string, … ]

Description: Set of scopes requested by this app.

{
  "scopes": [
    "project",
    "tm"
  ]
}
modules

Type: object

Description: The list of modules this app provides.

environments

Type: [string, … ]

Allowed values: crowdin, crowdin-enterprise

Description: Set of environments where a module could be installed.

{
  "environments": [
    "crowdin-enterprise"
  ]
}

Authentication

​Specifies the authentication type to use when signing requests from the host application to the Crowdin app. Crowdin Apps support two types of authentication:

  • using OAuth app (crowdin_app value)
  • without OAuth app (none value)

In case your Crowdin app requires access to Crowdin API at any time, it’s recommended to use the crowdin_app, in other cases feel free to use the none. The authentication type none grants access to Crowdin API as well as the crowdin_app, but only when the Crowdin app is executed on the user side, for example, when the iframe opens.

Example:

{
   "authentication": {
       "type": "crowdin_app",
       "clientId": "your-client-id"
   }
}

​ Properties:

type

Type: string

Defaults to: none

Allowed values: none, crowdin_app

Description: The type of authentication to use.

clientId

Type: string

Description: OAuth client id for authorization via the crowdin_app type.

Modules

Modules are how apps extend Crowdin and interact with it. Using modules your app can do the following things:

  • Extend the Crowdin UI.
  • Create integrations with external services.
  • Add support for new custom file formats.
  • Customize processing for supported file formats.

Read more about UI Modules and File Processing Modules.

Events

​Allow an app to register callbacks for events that occur in the workspace. When an event is fired, a POST request will be made to the appropriate URL registered for the event. The installed callback is an integral part of the installation process of an app, whereas the remaining events are essentially webhooks. Each property within this object is a URL relative to the app’s base URL.

Example:

{
   "events": {
       "installed": "/hook/installed",
       "uninstall": "/hook/uninstall"
   }
}

​ Properties:

installed

Type: string

Description: The event that is sent to an app after a user installed the app in Crowdin.

This event is required if you use crowdin_app. Read more about Authentication.

uninstall

Type: string

Description: The event that is sent to an app before the app uninstallation from Crowdin.

Installed Event Payload

The Installed event is sent from Crowdin to the remote app when a user installs the app in Crowdin. The Installed event contains the information about the Crowdin workspace or profile the Crowdin App was installed to, the information about the app itself, as well as the credentials to fetch an API token.

Read more about Installed Event Flow.

Payload examples:

{
    "appId": "your-application-identifier",
    "appSecret": "dbfg....asdffgg",
    "clientId": "your-client-id",
    "userId": 1,
    "organizationId": 1,
    "domain": null,
    "baseUrl": "https://crowdin.com"
}
{
    "appId": "your-application-identifier",
    "appSecret": "dbfg....asdffgg",
    "clientId": "your-client-id",
    "userId": 1,
    "organizationId": 1,
    "domain": "{domain}",
    "baseUrl": "https://{domain}.crowdin.com"
}

Properties:

appId

Type: string

Description: The identifier of the app that is declared in the app descriptor file.

appSecret

Type: string

Description: The unique secret used for authorization of your Crowdin app.

clientId

Type: string

Description: The OAuth client identifier that is declared in the app descriptor file.

userId

Type: integer

Description: The numeric identifier of the user that installed the app in Crowdin Enterprise.

organizationId

Type: integer

Description: The numeric identifier of the organization the app was installed to.

domain

Type: string

Description: The name of the organization in Crowdin Enterprise the app was installed to. For Crowdin the domain value is always null

baseUrl

Type: string

Description: The baseUrl of the organization in Crowdin Enterprise the app was installed to. For Crowdin the baseUrl value is always "https://crowdin.com"

Uninstall Event Payload

The uninstall event is sent from Crowdin Enterprise to the remote Crowdin app when a user uninstalls the app from Crowdin Enterprise. The Uninstall event, like the install event, contains the information about the Crowdin workspace or account the Crowdin App was installed to, and the information about the app itself. After receiving the uninstall event, it’s necessary to find and remove all of the data related to the Crowdin workspace or account the app is removed from.

Payload examples:

{
   "appId": "your-application-identifier",
   "clientId": "your-client-id",
   "organizationId": 1,
   "domain": null,
   "baseUrl": "https://crowdin.com"
}
{
   "appId": "your-application-identifier",
   "clientId": "your-client-id",
   "organizationId": 1,
   "domain": "{domain}",
   "baseUrl": "https://{domain}.crowdin.com"
}

Properties:

appId

Type: string

Description: The identifier of the app that is declared in the app descriptor file.

clientId

Type: string

Description: The OAuth client identifier that is declared in the app descriptor file.

organizationId

Type: integer

Description: The numeric identifier of the organization the app uninstalled from.

domain

Type: string

Description: The name of the organization in Crowdin Enterprise the app uninstalled from. For Crowdin the domain value is always null

baseUrl

Type: string

Description: The baseUrl of the organization in Crowdin Enterprise the app uninstalled from. For Crowdin the baseUrl value is always "https://crowdin.com"

Was this article helpful?