应用程序描述符

应用描述符是 Crowdin 应用的重要构建模块之一。 应用描述符是一个 JSON 文件（例如 manifest.json），其中包含应用的基本信息，以及应用希望使用或扩展的模块。

它描述了应用的工作方式、将使用的资源等。

有意开发 Crowdin 应用？

查看我们的 Crowdin Apps SDK，只需几行代码即可创建应用。

应用描述符结构

应用描述符是一个具有以下结构的 JSON 对象：

manifest.json

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

属性	描述
identifier	类型： string（^[a-z0-9-._]+$） 必填： 是 描述： 用于标识应用的唯一键。 此标识符的长度必须 <= 255 个字符。 警告 请勿在应用标识符中使用大写字母。
name	类型： string 必填： 是 描述： 应用的可读名称。
baseUrl	类型： string（uri） 必填： 是 描述： 远程应用的基础 URL，用于与应用实例之间的所有通信。 应用安装到工作区后，在不先卸载应用的情况下无法更改应用的 baseUrl。 重要提示： 在将应用公开之前，请谨慎选择您的 baseUrl。 baseUrl 必须以 https:// 开头，以确保我们的云实例与您的应用之间的所有数据均以安全方式传输。 注意 每个应用必须具有唯一的 baseUrl。 如果您希望从同一主机提供多个应用，请考虑在 baseUrl 中添加路径前缀。
authentication	类型： Authentication 必填： 是 描述： 指定在主机应用程序与 Crowdin 应用之间签署请求时使用的身份验证类型。
description	类型： string 描述： 应用功能的可读说明。 该描述将在 Crowdin 界面中显示。
logo	类型： string（relativeUri） 描述： 相对于应用基础 URL 的图片 URL，将在 Crowdin 界面中显示。
events	类型： Events 描述： 允许应用注册应用事件通知。
scopes	类型： [string, … ] 描述： 此应用请求的权限范围集合。 "scopes": [ "project", "tm" ]
modules	类型： object 描述： 此应用提供的模块列表。
environments	类型： [string, … ] 允许值： crowdin、crowdin-enterprise 描述： 可安装模块的环境集合。 "environments": [ "crowdin-enterprise" ]

身份验证

指定在主机应用程序向 Crowdin 应用发送请求时使用的身份验证类型。 Crowdin 应用支持两种身份验证类型：

• 使用 OAuth 应用（crowdin_app 值）
• 不使用 OAuth 应用（none 值）

如果您的 Crowdin 应用随时需要访问 Crowdin API，建议使用 crowdin_app，否则可以随意使用 none。 身份验证类型 none 与 crowdin_app 一样可以访问 Crowdin API，但仅限于在用户端执行 Crowdin 应用时，例如当 iframe 打开时。

示例：

manifest.json

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

属性	描述
type	类型： string 默认值： none 允许值： none、crowdin_app 描述： 要使用的身份验证类型。
clientId	类型： string 描述： 通过 crowdin_app 类型进行授权的 OAuth 客户端 ID。

模块

模块是应用扩展 Crowdin 并与其交互的方式。 使用模块，您的应用可以执行以下操作：

• 扩展 Crowdin 界面。
• 创建与外部服务的集成。
• 添加对新自定义文件格式的支持。
• 自定义受支持文件格式的处理方式。

了解更多关于 UI 模块和文件处理模块的信息。

事件

允许应用为工作区中发生的事件注册回调。 当事件触发时，将向为该事件注册的相应 URL 发送 POST 请求。 已安装回调是应用安装过程的重要组成部分，而其余事件本质上是 webhook。 此对象中的每个属性都是相对于应用基础 URL 的 URL。

示例：

manifest.json

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

属性	描述
installed	类型： string 描述： 用户在 Crowdin 中安装应用后发送给应用的事件。 如果使用 crowdin_app，则此事件为必填项。 了解更多关于身份验证的信息。
uninstall	类型： string 描述： 在从 Crowdin 卸载应用之前发送给应用的事件。

已安装事件载荷

已安装事件在用户于 Crowdin 中安装应用时从 Crowdin 发送到远程应用。 已安装事件包含有关安装了 Crowdin 应用的 Crowdin 工作区或个人资料的信息、有关应用本身的信息，以及用于获取 API 令牌的凭据。

了解更多关于已安装事件流程的信息。

载荷示例：

{
  "appId": "your-application-identifier",
  "appSecret": "dbfg....asdffgg",
  "clientId": "your-client-id",
  "userId": 1,
  "organizationId": 1,
  "domain": null,
  "baseUrl": "https://crowdin.com"
}

{
  "appId": "your-application-identifier",
  "appSecret": "dbfg....asdffgg",
  "clientId": "your-client-id",
  "userId": 1,
  "organizationId": 1,
  "domain": "{domain}",
  "baseUrl": "https://{domain}.crowdin.com"
}

参数：

属性	描述
appId	类型： string 描述： 在应用描述符文件中声明的应用标识符。
appSecret	类型： string 描述： 用于授权您的 Crowdin 应用的唯一密钥。
clientId	类型： string 描述： 在应用描述符文件中声明的 OAuth 客户端标识符。
userId	类型： integer 描述： 在 Crowdin Enterprise 中安装应用的用户的数字标识符。
organizationId	类型： integer 描述： 安装了该应用的组织的数字标识符。
domain	类型： string 描述： 安装了该应用的 Crowdin Enterprise 组织的名称。 对于 Crowdin，domain 值始终为 null
baseUrl	类型： string 描述： 安装了该应用的 Crowdin Enterprise 组织的 baseUrl。 对于 Crowdin，baseUrl 值始终为 https://crowdin.com

卸载事件载荷

卸载事件在用户从 Crowdin Enterprise 卸载应用时从 Crowdin Enterprise 发送到远程 Crowdin 应用。 卸载事件与安装事件一样，包含有关安装了 Crowdin 应用的 Crowdin 工作区或账户的信息，以及有关应用本身的信息。 收到卸载事件后，需要查找并删除与移除该应用的 Crowdin 工作区或账户相关的所有数据。

载荷示例：

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

参数：

属性	描述
appId	类型： string 描述： 在应用描述符文件中声明的应用标识符。
clientId	类型： string 描述： 在应用描述符文件中声明的 OAuth 客户端标识符。
organizationId	类型： integer 描述： 卸载了该应用的组织的数字标识符。
domain	类型： string 描述： 卸载了该应用的 Crowdin Enterprise 组织的名称。 对于 Crowdin，domain 值始终为 null
baseUrl	类型： string 描述： 卸载了该应用的 Crowdin Enterprise 组织的 baseUrl。 对于 Crowdin，baseUrl 值始终为 https://crowdin.com