App Descriptor

App-deskriptoren er en af de vigtigste byggesten i Crowdin-apps. App-deskriptoren er en JSON-fil (f.eks. crowdin.json) indeholdende generelle oplysninger om appen, samt de moduler, appen ønsker at operere med eller udvide. Den beskriver, hvordan appen vil fungere, hvilke ressourcer, som vil blive brugt mv. Et eks. ses nedenfor

App-deskriptorstruktur

{
   "identifier": "app-identifkator",
   "name": "Appen",
   "description": "App-beskr.",
   "logo": "/assets/logos/app-logo.png",
   "baseUrl": "http://eksempel.dk",
   "authentication": {
       "type": "godkendelseskode",
       "clientId": "klient-id"
   },
   "events": {
       "installed": "/hooks/installed"
   },
   "scopes": [
       "project"
   ],
   "modules": {
       "integrations": [
           {
               "key": "modulenøglen",
               "name": "Modulenavn",
               "description": "Modulbeskrivelse",
               "logo": "/assets/logos/module-logo.png",
               "url": "/page/integration",
               "environments": [
                 "crowdin"
              ]
           }
       ]
   }
}
identifier

Type: string (^[a-z0-9-._]+$)

Bemærk: Brug ikke majuskler i app-identifikatoren.

Required: yes

Beskrivelse: En unik nøgle til app-identifikation. Denne identifikator skal være <= 255 characters.

navn

Type: string

Required: yes

Beskrivelse: Menneskeligt læsbare app-navn.

baseUrl

Type: string (uri)

Required: yes

Beskrivelse: Fjern-appens basis-URL brugt til al kommunikation retur til app-instansen.
Efter appen er installeret i et arbejdsområde, kan dens baseUrl ikke ændres uden forudgående afinstallation af appen.

Dette er vigtigt: Vælg baseUrl klogt, før offentliggørelsen af appen.
BaseUrl skal starte med https:// for at sikre, at alle data sendes sikkert mellem vores cloud-instanser og appen.

Bemærk: Hver app skal have en unik baseUrl. Ønskes flere apps tilgængeliggjort fra samme vært,
overveje da at føje et stipræfiks til baseUrl'en.

authentication

Type: Authentication

Required: yes

Beskrivelse: Angiver den godkendelsestype, der skal bruges ved signering af anmodninger mellem værts-appen og Crowdin-appen.

description

Type: string

Description: Klartekstbeskrivelsen af, hvad appen gør.
Beskrivelsen fremgår i Crowdin-UI'en.

logo

Type: string (relativeUri)

Beskrivelse: Billed-URL'en relativ til appens basis-URL, som vist i Crowdin UI'en.

events

Type: Events

Beskrivelse: Tillad app'en at registrere sig til app-event notifikationer.

scopes

Type: [string, … ]

Beskrivelse: Sæt af anmodede udtrækninger fra appen.

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

Type: object

Beskrivelse: Listen over modultyper, appen muliggør.

environments

Type: [string, … ]

Allowed values: crowdin, crowdin-enterprise

Description: Set of environments where a module could be installed.
This parameter is needed for cross-product applications.

{
  "environments": [
    "crowdin"
  ]
}

Authentication

Angiver den godkendelsestype, der skal bruges ved signering af anmodninger mellem værts-app og Crowdin-app. Crowdin-apps understøtter to godkendelsestyper:

  • brug af OAuth-app (authorization_code-værdi)
  • uden OAuth-app (ingen-værdi)

Såfremt Crowdin-appen på et tidspunkt kræver adgang til Crowdin-API’en, anbefales brug af authorization_code, i øvrige tilfælde kan none bruges. Godkendelsestypen none giver adgang til Crowdin-API’en samt authorization_code, men kun når Crowdin-appen eksekveres på brugersiden, f.eks. når iframe åbnes.

Eks.:

{
   "authentication": {
       "type": "authorization_code",
       "clientId": "klient-id"
   }
}

​ Properties:

type

Type: string

Defaults to: none

Allowed values: none, authorization_code

Beskrivelse: Godkendelsestypen, der skal anvendes.

clientId

Type: string

Beskrivelse: OAuth-klient-ID for godkendelse via typen authorization_code.

Modules

Moduler er måden, hvorpå apps udvider og interagerer med Crowdin. Vha. moduler kan en app gøre flg.:

  • Udvid Crowdin-UI’en.
  • Opret integrationer med eksterne tjenester.

Læs mere om Moduler.

Events

Tillad en app at registrere tilbagekald for begivenheder, som forekommer i arbejdsområdet. Når en begivenhed udløses, vil en POST-anmodning gå til den relevante URL registreret til begivenheden. Det installerede callback er en integreret del af en apps installationsproces, mens de resterende begivenheder hovedsagelig udgør webhooks. Hver egenskab i dette objekt er en URL relativ til appens basis-URL.

Eks.:

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

​ Properties:

installed

Type: string

Beskrivelse: Begivenheden sendt til en app, efter at en bruger har installeret appen i Crowdin.

Denne begivenhed er obligatorisk ved brug af authorization_code. Læs mere om Godkendelse.

uninstall

Type: string

Beskrivelse: Begivenheden sendt til en app, inden den afinstalleres i Crowdin.

Events payload

Installed event

Install event sendes fra Crowdin til Crowdin fjern-appen, når en bruger installerer denne i Crowdin. Install event indeholder oplysningerne om det Crowdin-arbejdsområde, hvori Crowdin-appen er installeret, om selve appen samt appens authorization_code. Så snart authorization_code modtages, er det nødvendigt at godkende appen vha. adgangs- og opdaterings-tokens.

Læs mere om Installed Event Flow.

Payload-eks.: ​

{
   "appId": "app-identifikator",
   "clientId": "Klient-ID'en",
   "userId": 1,
   "organizationId": 1,
   "domain": null,
   "baseUrl": "https://crowdin.com",
   "code": "def.....608bdad9c625bd2eedf1fd6"
}

Egenskaber:

appId

Type: string

Beskrivelse: Identifikator for appen er angivet i app-deskriptor filen.

clientId

Type: string

Beskrivelse: OAuth-klientidentifikator, som erklæret i app-deskriptor filen.

userId

Type: integer

Beskrivelse: Den numeriske identifikator på brugeren, der installerede appen i Crowdin.

organizationId

Type: integer

Beskrivelse: Den numeriske identifikator på organisationen, hvori appen er installeret.

domain

Type: string

Beskrivelse: Navnet på organisationen, hvori appen er installeret. For Crowdin, er domæneværdien altid null

baseUrl

Type: string

Beskrivelse: baseUrl'en på organisationen, hvori appen er installeret. Til Crowdin er baseURL-værdien altid "https://crowdin.com"

kode

Type: string

Beskrivelse: Koden brugt til godkendelse af ens Crowdin-app.

Uninstall event

Uninstall event sendes fra Crowdin til Crowdin fjern-appen, når en bruger afinstallerer denne i Crowdin. Uninstall event indeholder ligesom Install event oplysningerne om Crowdin-arbejdsområdet, hvori Crowdin-appen blev installeret samt oplysningerne om selve appen. Efter modtagelse af en uninstall event er det nødvendigt at finde og fjerne alle data relateret til Crowdin-arbejdsområdet, hvorfra appen er fjernet.

Payload-eks.: ​

{
   "appId": "app-identifikator",
   "clientId": "klient-ID",
   "organizationId": 1,
   "domain": null,
   "baseUrl": "https://crowdin.com"
}

Egenskaber:

appId

Type: string

Beskrivelse: Identifikator for appen er angivet i app-deskriptor filen.

clientId

Type: string

Beskrivelse: OAuth-klientidentifikator, som erklæret i app-deskriptor filen.

organizationId

Type: integer

Beskrivelse: Den numeriske identifikator på organisationen, hvorfra appen er afinstalleret.

domain

Type: string

Beskrivelse: Navnet på organisationen, hvorfra appen er afinstalleret. For Crowdin, er domæneværdien altid null

baseUrl

Type: string

Beskrivelse: baseUrl'en for organisationen, hvorfra appen er afinstalleret. Til Crowdin er baseURL-værdien altid "https://crowdin.com"

Var denne artikel nyttig?