App Descriptor

Bu içerik henüz dilinizde mevcut değil.

The app descriptor is a JSON file, usually manifest.json, that tells Crowdin what the app is and which modules it adds.

App Descriptor Structure

The app descriptor is a JSON object. A self-hosted app serves it from its own server, and a serverless app keeps it in the project and pushes it to Crowdin with the CLI.

Self-Hosted App

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

Serverless App

A serverless descriptor has no baseUrl, declares UI modules without a url, and leaves out events, which point at URLs on a server of your own.

{
  "identifier": "your-application-identifier",
  "name": "Your Application",
  "description": "Application description",
  "bundle": {
    "mode": "internal"
  },
  "scopes": [
    "project"
  ],
  "modules": {
    "project-menu": [
      {
        "key": "your-module-key",
        "name": "Module name"
      }
    ]
  }
}

Fields

Property	Description
`identifier`	Type: `string` Required: yes Description: A unique key to identify the app, 255 characters or fewer.
`name`	Type: `string` Required: yes Description: The human-readable name of the app.
`baseUrl`	Type: `string` (`uri`) Required: yes (self-hosted apps only) Description: The base URL of the remote app, used for all communication back to it. A descriptor without a `baseUrl` describes a serverless app, which Crowdin hosts and runs.
`bundle`	Type: `object` Description: Serverless apps only. Where Crowdin serves the app from. Set `mode` to `internal` for the bundle uploaded to Crowdin, or to `external` with a `url` that points to a local development server.
`authentication`	Type: `Authentication` Description: The authentication type used when signing requests between Crowdin and the app. Defaults to `none`, which is the type serverless apps use.
`description`	Type: `string` Description: The human-readable description of what the app does. It is visible in the Crowdin UI.
`logo`	Type: `string` (`relativeUri`) Description: The image URL relative to the app’s base URL, displayed in the Crowdin UI.
`events`	Type: `Events` Description: Callbacks for app event notifications (self-hosted apps only).
`scopes`	Type: [`string`, … ] Required: yes Description: Set of scopes requested by this app.
`modules`	Type: `object` Required: yes Description: The list of modules this app provides. Serverless apps provide UI modules.
`default_permissions`	Type: `object` Description: Who can use the app right after installation. `user` accepts `owner`, `managers`, `all`, or `guests`, and `project` accepts `own` or `restricted`.
`stringBasedAvailable`	Type: `boolean` Description: Whether the app’s modules are available in string-based projects. In file-based projects they are always available.

The baseUrl must start with https://, and it cannot change after the app is installed without uninstalling the app first, so choose it before you make the app public.

Authentication

Specifies the authentication type Crowdin uses when it signs requests to the app:

crowdin_app: Through an OAuth app. Use it when the app calls the Crowdin API on its own, at any time.
none: Without an OAuth app. The app still reaches the API, but only while it runs on the user side, for example while its iframe is open. Serverless apps use this type.
crowdin_agent: Through a dedicated bot user that Crowdin creates when the app is installed, so the app keeps working in projects afterwards, for example on a custom workflow step. The app’s API calls are authenticated as that user. Required by the Workflow Step Type module.

Read more about Security for Crowdin Apps.

Example:

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

Field	Type	Description
`type`	`string`	The type of authentication to use: `none` (the default), `crowdin_app`, or `crowdin_agent`.
`clientId`	`string`	OAuth client id for authorization via the `crowdin_app` type.

Modules

Modules are how an app extends Crowdin. Each type declares where the app appears in the interface or what it processes:

UI modules: Panels, dashboards, menus, and dialogs inside Crowdin.
AI modules: Custom AI providers, prompt providers, and processors for AI requests.
File processing modules: Custom file formats, and processing before or after import and export.
Other modules: Custom machine translation engines, webhooks, workflow steps, QA checks, and spellcheckers.

Read more about UI Modules, AI Modules, and File Processing Modules.

A self-hosted app registers callbacks for events that happen in the workspace. Each property in this object is a URL relative to the app’s baseUrl, and Crowdin sends a POST request to it when the event fires. The installed callback is part of the installation itself, and the rest behave like webhooks.

Example:

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

Event	Type	Description
`installed`	`string`	Sent to the app after a user installs it in Crowdin. Required with the `crowdin_app` and `crowdin_agent` authentication types.
`uninstall`	`string`	Sent to the app before it is uninstalled from Crowdin.

Installed Event Payload

Crowdin sends the installed event to the app when a user installs it. The payload describes the workspace or profile the app was installed to, the app itself, and the credentials the app needs to fetch an API token.

Uninstall Event Payload

Crowdin sends the uninstall event to the app before the app is removed. Like the installed event, the payload describes the workspace or account the app was installed to and the app itself. Use it to remove the data you stored for that workspace or account.

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:

Field	Type	Description
`appId`	`string`	The identifier of the app that is declared in the app descriptor file.
`clientId`	`string`	The OAuth client identifier that is declared in the app descriptor file.
`organizationId`	`integer`	The numeric identifier of the organization the app was uninstalled from.
`domain`	`string`	The name of the organization in Crowdin Enterprise the app was uninstalled from. In Crowdin the value is always `null`.
`baseUrl`	`string`	The `baseUrl` of the organization in Crowdin Enterprise the app was uninstalled from. In Crowdin the value is always `https://crowdin.com`.

Bu sayfa faydalı oldu mu?