The app descriptor is one of the essential building blocks of Crowdin apps. The app descriptor is a JSON file (for example, crowdin.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.
{
"identifier": "my-application-identifier",
"name": "My Application",
"description": "Application description",
"logo": "/assets/logos/app-logo.png",
"baseUrl": "http://example.com",
"authentication": {
"type": "authorization_code",
"clientId": "your-client-id"
},
"events": {
"installed": "/hooks/installed"
},
"scopes": [
"project"
],
"modules": {
"integrations": [
{
"key": "my-module-key",
"name": "Module Name",
"description": "Module description",
"logo": "/assets/logos/module-logo.png",
"url": "/page/integration"
}
]
}
}
identifier | Type: Required: yes Description: A unique key to identify the app. This identifier must be <= 255 characters. |
name | Type: Required: yes Description: The human-readable name of the app. |
baseUrl | Type: Required: yes Description: The base URL of the remote app, which is used for all communications back to the app instance. This is important: choose your baseUrl wisely before making your app public. Note: Each app must have a unique baseUrl. If you would like to serve multiple apps from the same host, |
authentication | Type: Required: yes Description: Specifies the authentication type to use when signing requests between the host application and the Crowdin app. |
description | Type: Description: The human-readable description of what the app does. |
logo | Type: Description: The image URL relative to the app's base URL which will be displayed in the Custom Apps section. |
events | Type: Description: Allow the app to register for app event notifications. |
scopes | Type: [ Description: Set of scopes requested by this app. |
modules | Type: Description: The list of modules this app provides. |
Specifies the authentication type to use when signing requests from the host application to the Crowdin app. Crowdin Apps support two types of authentication:
authorization_code value)none value)In case your Crowdin app requires access to Crowdin API at any time, it’s recommended to use the authorization_code, in other cases feel free to use the none. The authentication type none grants access to Crowdin API as well as the authorization_code, but only when the Crowdin app is executed on the user side, for example, when the iframe opens.
Exemplo:
{
"authentication": {
"type": "authorization_code",
"clientId": "your-client-id"
}
}
Properties:
type | Type: Defaults to: Allowed values Description: The type of authentication to use. |
clientId | Type: Description: OAuth client id for authorization via the |
Modules are how apps extend Crowdin and interact with it. Using modules your app can do the following things:
Read more about Modules.
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.
Exemplo:
{
"events": {
"installed": "/hook/installed",
"uninstall": "/hook/uninstall"
}
}
Properties:
installed | Type: Description: The event that is sent to an app after a user installed the app in Crowdin. This event is required if you use |
uninstall | Type: Description: The event that is sent to an app before the app uninstallation from Crowdin. |
Installed event
The Installed event is sent from Crowdin to the remote Crowdin app when a user installs the app in Crowdin. The Installed event contains the information about the Crowdin workspace the Crowdin App was installed to, the information about the app itself, as well as the app authorization_code. As soon as the authorization_code is received it’s necessary to authorize the app using the access and refresh tokens.
Read more about Installed Event Flow.
Payload example:
{
"appId": "my-application-identifier",
"clientId": "your-client-id",
"userId": 1,
"organizationId": 1,
"domain": null,
"baseUrl": "https://crowdin.com",
"code": "def.....608bdad9c625bd2eedf1fd6"
}
Properties:
appId | Type: Description: The identifier of the app that is declared in the app descriptor file. |
clientId | Type: Description: The OAuth client identifier that is declared in the app descriptor file. |
userId | Type: Description: The numeric identifier of the user that installed the app in Crowdin. |
organizationId | Type: Description: The numeric identifier of the organization the app was installed to. |
domain | Type: Description: The name of the organization the app was installed to. For Crowdin the domain value is always |
baseUrl | Type: Description: The baseUrl of the organization the app was installed to. For Crowdin the baseUrl value is always |
code | Type: Description: The code used for authorization of your Crowdin app. |
Uninstall event
The uninstall event is sent from Crowdin to the remote Crowdin app when a user uninstalls the app from Crowdin. The Uninstall event, like the install event, contains the information about the Crowdin workspace 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 the app is removed from.
Payload example:
{
"appId": "my-application-identifier",
"clientId": "your-client-id",
"organizationId": 1,
"domain": null,
"baseUrl": "https://crowdin.com"
}
Properties:
appId | Type: Description: The identifier of the app that is declared in the app descriptor file. |
clientId | Type: Description: The OAuth client identifier that is declared in the app descriptor file. |
organizationId | Type: Description: The numeric identifier of the organization the app uninstalled from. |
domain | Type: Description: The name of the organization the app uninstalled from. For Crowdin the domain value is always |
baseUrl | Type: Description: The baseUrl of the organization the app uninstalled from. For Crowdin the baseUrl value is always |