Descrittore dell'App

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

Descrizione: La descrizione leggibile dall'uomo di cosa fa l'app.
La descrizione sarà visibile nell'UI di Crowdin Imprese.

logo

Type: string (relativeUri)

Descrizione: L'URL dell'immagine relativa all'URL di base dell'app che sarà mostrato nell'UI di Crowdin Imprese.

events

Type: Events

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

scopes

Type: [string, … ]

Descrizione: Serie di ambiti richiesti da quest'app.

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

Type: object

Description: The list of modules this app provides.

Autenticazione

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

Esempio:

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

Moduli

I moduli sono come le app estendono Crowdin Imprese e vi interagiscono. Using modules your app can do the following things:

  • Estendi l’UI di Crowdin Imprese.
  • Create integrations with external services.

Leggi di più sui Moduli.

Eventi

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

Esempio:

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

​ Properties:

installed

Type: string

Descrizione: L'evento inviato a un'app dopo che un utente ha installato l'app in Crowdin Impresa.

This event is required if you use authorization_code. Leggi di più sull'Autenticazione.

uninstall

Type: string

Descrizione: L'evento inviato a un'app prima della sua disinstallazione da Crowdin Impresa.

Events payload

Installed event

L’evento installato è inviato da Crowdin Impresa all’app remota di Crowdin quando un utente installa l’app in Crowdin Impresa. L’evento Installato contiene le informazioni sull’area di lavoro di Crowdin Impresa in cui è stata installata l’App di Crowdin, le informazioni sull’app stessa, nonché l’authorization_code dell’app. As soon as the authorization_code is received it’s necessary to authorize the app using the access and refresh tokens.

Leggi di più sul Flusso dell’Evento Installato.

Payload example: ​

{
   "appId": "my-application-identifier",
   "clientId": "your-client-id",
   "userId": 1,
   "organizationId": 1,
   "domain": "{domain}",
   "baseUrl": "https://{domain}.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

Descrizione: L'identificativo numerico dell'utente che ha installato l'app in Crowdin Impresa.

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.

baseUrl

Type: string

Description: The baseUrl of the organization the app was installed to.

code

Type: string

Description: The code used for authorization of your Crowdin app.

Uninstall event

L’evento di disinstallazione è inviato da Crowdin Impresa all’app remota di Crowdin quando un utente la disinstalla da Crowdin Impresa. L’evento di Disinstallazione, come l’evento d’installazione, contiene le informazioni sull’area di lavoro di Crowdin Impresa in cui è stata installata l’App di Crowdin, e le informazioni sull’app stessa. Dopo averlo ricevuto, è necessario trovare e rimuovere tutti i dati correlati all’area di lavoro di Crowdin Impresa da cui è stata rimossa l’app.

Payload example: ​

{
   "appId": "my-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 the app uninstalled from.

baseUrl

Type: string

Description: The baseUrl of the organization the app uninstalled from.

Questo articolo è stato utile?