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.

App Descriptor Structure

The app descriptor is a JSON object with the following 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"
        ]
      }
    ]
  }
}

Property	Description
`identifier`	Type: `string` (`^[a-z0-9-._]+$`) Required: yes Description: A unique key to identify the app. This identifier must be <= 255 characters. Don’t use uppercase in the app identifier.
`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. 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"
  }
}

Property Description

Property	Description
`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.

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

Property Description

Property	Description
`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

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.

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 example:

{
  "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:

Property	Description
`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 page helpful?

Property	Description
`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`