App Descriptor

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.​

App Descriptor Structure

{
   "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: string (^[a-zA-Z0-9-._]+$)

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 Custom Apps section of the Integrations & API page of the project.

logo

Type: string (relativeUri)

Description: The image URL relative to the app's base URL which will be displayed in the Custom Apps section.

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.

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 (authorization_code 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 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.

Приклад:

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

​ Properties:

type

Type: string

Defaults to: none

Allowed values none, authorization_code

Description: The type of authentication to use.

clientId

Type: string

Description: OAuth client id for authorization via the authorization_code 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.

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.

Приклад:

{
   "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 authorization_code. Read more about Authentication.

uninstall

Type: string

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

Events payload

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

userId

Type: integer

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

organizationId

Type: integer

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

domain

Type: string

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

baseUrl

Type: string

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

code

Type: string

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: 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 the app uninstalled from. For Crowdin the domain value is always null

baseUrl

Type: string

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

Ця стаття була корисною?