Descritor de aplicativos

O descritor de aplicativo é um dos elementos essenciais dos aplicativos Crowdin. O descritor do aplicativo é um arquivo JSON (por exemplo, crowdin.json) que inclui informações gerais para o aplicativo, bem como os módulos com os quais o aplicativo deseja operar ou estender. Descreve como o aplicativo funcionará, quais recursos serão usados etc. Você pode ver um exemplo abaixo.

Estrutura do descritor do aplicativo

{
   "identifier": "meu-identificador-de-aplicativo",
   "name": "Meu aplicativo",
   "description": "Descrição do aplicativo",
   "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": "Nome do módulo",
               "description": "Descrição do módulo",
               "logo": "/assets/logos/module-logo.png",
               "url": "/page/integration"
           }
       ]
   }
}
identifier

Tipo: string (^[a-zA-Z0-9-._]+$)

Requerido: sim

Descrição: Uma chave exclusiva para identificar o aplicativo. Esse identificador deve ser <= 255 characters.

name

Tipo: string

Requerido: sim

Descrição: O nome legível por humanos do aplicativo.

baseUrl

Tipo: string (uri)

Requerido: sim

Descrição: O URL base do aplicativo remoto, que é usado para todas as comunicações de volta para a instância do aplicativo.
Depois que o aplicativo é instalado em um espaço de trabalho, o baseUrl do aplicativo não pode ser alterado sem desinstalá-lo previamente.

Isso é importante: escolha seu BaseUrl com sabedoria antes de tornar seu aplicativo público.
O baseUrl deve começar com https:// para garantir que todos os dados sejam enviados com segurança entre nossas instâncias de nuvem e seu aplicativo.

Nota: Cada aplicativo deve ter um baseUrl exclusivo. Se você gostaria de servir a vários aplicativos do mesmo host,
considere adicionar um prefixo de caminho ao baseUrl.

authentication

Tipo: Authentication

Requerido: sim

Descrição: Especifica o tipo de autenticação a ser usado ao assinar solicitações entre o aplicativo host e o aplicativo para Crowdin.

description

Tipo: string

Descrição: A descrição legível por humanos do que o aplicativo faz.
A descrição estará visível na interface do usuário do Crowdin.

logo

Tipo: string (relativeUri)

Descrição: O URL da imagem em relação ao URL base do aplicativo que será exibido na UI do Crowdin.

events

Tipo: Events

Descrição: Permite que o aplicativo se registre para notificações de eventos do aplicativo.

scopes

Tipo: [string, … ]

Descrição: Conjunto de escopos solicitado por este aplicativo.

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

Tipo: object

Descrição: A lista de módulos que este aplicativo oferece.

Autenticação

​ Especifica o tipo de autenticação a ser usado ao assinar solicitações do aplicativo host para o aplicativo para Crowdin. Os aplicativos para Crowdin suportam dois tipos de autenticação:

  • usando o aplicativo para OAuth (valor authorization_code)
  • sem o aplicativo para OAuth (valor none)

Caso seu aplicativo Crowdin exija acesso à API Crowdin a qualquer momento, é recomendável usar o authorization_code, em outros casos, sinta-se à vontade para usar o none. O tipo de autenticação none concede acesso à API Crowdin, bem como ao authorization_code, mas apenas quando o aplicativo Crowdin é executado no lado do usuário, por exemplo, quando o iframe é aberto.

Exemplo:

{
   "authentication": {
       "type": "authorization_code",
       "clientId": "seu--id-de-cliente"
   }
}

​ ​ Propriedades:

type

Tipo: string

Padrão para: none

Valores permitidos: none, authorization_code

Descrição: O tipo de autenticação a ser usado.

clientId

Tipo: string

Descrição: ID do cliente OAuth para autorização via tipo de authorization_code.

Módulos

Módulos são como os aplicativos estendem o Crowdin e interagem com ele. Usando módulos, seu aplicativo pode fazer o seguinte:

  • Estenda a Interface do usuário do Crowdin.
  • Crie integrações com serviços externos.

Leia mais sobre módulos.

Eventos

Permitir que um aplicativo registre retornos de chamada para eventos que ocorrem no espaço de trabalho. Quando um evento é disparado, uma solicitação POST é feita para o URL apropriado registrado para o evento. O retorno de chamada instalado é parte integrante do processo de instalação de um aplicativo, enquanto os eventos restantes são essencialmente webhooks. Cada propriedade dentro desse objeto é um URL relativo ao URL base do aplicativo.

Exemplo:

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

​ ​ Propriedades:

instalado

Tipo: string

Descrição: O evento que é enviado a um aplicativo depois que um usuário instala o aplicativo no Crowdin.

Este evento é obrigatório se você usar authorization_code. Leia mais sobre autenticação.

desinstalar

Tipo: string

Descrição: O evento que é enviado a um aplicativo antes da desinstalação do aplicativo no Crowdin.

Carga útil de eventos

Evento instalado

O evento Instalado é enviado do Crowdin para o aplicativo Crowdin remoto quando um usuário instala o aplicativo no Crowdin. O evento Instalado contém as informações sobre o espaço de trabalho do Crowdin em que o aplicativo Crowdin foi instalado, as informações sobre o próprio aplicativo, bem como o aplicativo authorization_code. Assim que o authorisation_code for recebido, é necessário autorizar o aplicativo usando os tokens de acesso e atualização.

Leia mais sobre fluxo de evento instalado.

Exemplo de carga​

{
   "appId": "meu-indentificador-do-aplicativo",
   "clientId": "seu-id-de-cliente",
   "userId": 1,
   "organizationId": 1,
   "domain": null,
   "baseUrl": "https://crowdin.com",
   "code": "def.....608bdad9c625bd2eedf1fd6"
}

Propriedades:

aplicado

Tipo: string

Descrição: O identificador do aplicativo declarado no arquivo do descritor do aplicativo.

clientId

Tipo: string

Descrição: O identificador do cliente OAuth declarado no arquivo do descritor do aplicativo.

userId

Tipo: integer

Descrição: O identificador numérico do usuário que instalou o aplicativo no Crowdin.

organizationId

Tipo: integer

Descrição: O identificador numérico da organização em que o aplicativo foi instalado.

domain

Tipo: string

Descrição: O nome da organização em que o aplicativo foi instalado. Para Crowdin, o valor do domínio é sempre null

baseUrl

Tipo: string

Descrição: O baseUrl da organização em que o aplicativo foi instalado. Para Crowdin, o valor baseUrl é sempre "https://crowdin.com"

code

Tipo: string

Descrição: O código usado para autorização de seu aplicativo para Crowdin.

Evento de desinstalação

O evento de desinstalação é enviado do Crowdin para o aplicativo Crowdin remoto quando um usuário desinstala o aplicativo no Crowdin. O evento Uninstall, assim como o evento install, contém as informações sobre a área de trabalho Crowdin em que o aplicativo para Crowdin foi instalado e as informações sobre o próprio aplicativo. Depois de receber o evento de desinstalação, é necessário encontrar e remover todos os dados relacionados ao espaço de trabalho do Crowdin do qual o aplicativo foi removido.

Exemplo de carga​

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

Propriedades:

aplicado

Tipo: string

Descrição: O identificador do aplicativo declarado no arquivo do descritor do aplicativo.

clientId

Tipo: string

Descrição: O identificador do cliente OAuth declarado no arquivo do descritor do aplicativo.

organizationId

Tipo: integer

Descrição: O identificador numérico da organização da qual o aplicativo desinstalou.

domain

Tipo: string

Descrição: O nome da organização da qual o aplicativo foi desinstalado. Para Crowdin, o valor do domínio é sempre null

baseUrl

Tipo: string

Descrição: O baseUrl da organização da qual o aplicativo foi desinstalado. Para Crowdin, o valor baseUrl é sempre "https://crowdin.com"

Este artigo foi útil?