Bekanntmachungsmodul

Mit diesem Modul kann eine App Benutzern einer Crowdin-Enterprise-Organisation Hinweise anzeigen.

Positionen für Bekanntmachungen:

header-alert: der Hinweisstreifen unterhalb des Seiten-Headers, der auf jeder Seite der Organisation vorhanden ist
glossary: oberhalb der Begriffstabelle auf einer Glossarseite

Das Modul ist nur in Crowdin Enterprise und nur in selbst gehosteten Apps verfügbar.

So funktioniert es

Ein Organisationsadministrator installiert die App und wählt aus, wer ihre Bekanntmachungen sehen kann.
Ein Benutzer öffnet eine Seite mit der Position des Moduls. Crowdin Enterprise sendet eine Anfrage mit dem aktuellen Kontext an die url des Moduls.
Die App antwortet mit den Bekanntmachungen, die der Benutzer sehen soll, oder mit einer leeren Liste.
Crowdin Enterprise zeigt die Bekanntmachungen an der jeweiligen Position an. Der Benutzer kann die Bekanntmachungen schließen, die die App als schließbar markiert hat.

Zugriff

Du kannst Zugriff auf dieses Modul für eine der folgenden Benutzerkategorien gewähren:

Nur Organisationsadministratoren
Organisationsadministratoren, Projektmanager und Entwickler
Alle Benutzer in den Projekten der Organisation
Ausgewählte Benutzer

Crowdin Enterprise wählt für dieses Modul standardmäßig Alle Benutzer in den Organisationsprojekten aus.

Struktur

{
  "baseUrl": "https://app.example.com",
  "modules": {
    "announcement": [
      {
        "key": "header-announcements",
        "name": "Header announcements",
        "url": "/announcements/header",
        "placement": "header-alert"
      }
    ]
  }
}

Eine App kann mehrere Bekanntmachungsmodule deklarieren, eines pro Position oder mehrere an derselben Position.

Eigenschaften

`key`	Typ: `string` Erforderlich: ja Beschreibung: Kennung des Moduls innerhalb der Crowdin-App.
`name`	Typ: `string` Erforderlich: ja Beschreibung: Der für Menschen lesbare Name des Moduls.
`url`	Typ: `string` Erforderlich: ja Beschreibung: Die relative URL, von der Crowdin Enterprise die Bekanntmachungen anfordert.
`placement`	Typ: `string` Erforderlich: ja Zulässige Werte: `header-alert`, `glossary` Beschreibung: Gibt an, wo die Bekanntmachungen des Moduls angezeigt werden.
`environments`	Typ: `string` Zulässige Werte: `crowdin-enterprise` Beschreibung: Menge der Umgebungen, in denen ein Modul installiert werden kann. Dieser Parameter wird für produktübergreifende Anwendungen benötigt.

Kommunikation zwischen der Bekanntmachungs-App und Crowdin

Crowdin Enterprise fordert die Bekanntmachungen jedes Mal an, wenn die Position des Moduls gerendert wird. Crowdin Enterprise sendet eine POST-Anfrage an baseUrl + url mit dem JWT der App im Authorization-Header. Die App hat 10 Sekunden Zeit zu antworten.

Anfrage an die App

Beispiel für die Nutzlast der Anfrage:

{
  "context": {
    "placement": "glossary",
    "userId": 123,
    "glossaryId": 456
  }
}

context.placement

Typ: string

Beschreibung: Die Position, für die die Bekanntmachungen angefordert werden.

context.userId

Typ: integer

Beschreibung: Der Benutzer, für den die Bekanntmachungen angefordert werden.

context.glossaryId

Typ: integer

Beschreibung: Das Glossar, dessen Seite der Benutzer geöffnet hat.
Gesendet zusammen mit der Position glossary.

Die Organisation wird anhand des JWT identifiziert, daher enthält der Payload nur den Kontext.

Erwartete Antwort der App

Beispiel für die Nutzlast der Antwort:

{
  "data": {
    "items": [
      {
        "id": "autumn-release-terms",
        "text": "The autumn release terminology is in the glossary. Check it before you start translating.",
        "dismissible": true,
        "expiresAt": "2026-10-01T00:00:00+00:00",
        "actionLabel": "Read the release notes",
        "actionUrl": "https://example.com/releases/autumn"
      }
    ]
  }
}

Gib ein leeres items-Array zurück, wenn die App nichts anzuzeigen hat.

`id`	Typ: `string` Erforderlich: ja Beschreibung: Kennung der Bekanntmachung innerhalb des Moduls, bis zu 255 Zeichen. Eine geschlossene Bekanntmachung bleibt geschlossen, solange sie diesen Wert behält. Gib daher einer bearbeiteten Bekanntmachung eine neue `id`, damit sie erneut angezeigt wird.
`text`	Typ: `string` Erforderlich: ja Beschreibung: Die Bekanntmachung selbst, bis zu 65.535 Zeichen. Der Text wird als Klartext angezeigt. Darin enthaltene unveränderte `http`- und `https`-URLs werden zu Links. Im Headerstreifen wird der Text in einer Zeile angezeigt; der vollständige Text steht in einem Tooltip.
`dismissible`	Typ: `boolean` Erforderlich: ja Beschreibung: Gibt an, ob der Benutzer die Bekanntmachung schließen kann.
`expiresAt`	Typ: `string` Beschreibung: Der Zeitpunkt, an dem die Bekanntmachung nicht mehr angezeigt wird, im ISO-8601-Format. Bekanntmachungen ohne dieses Feld werden angezeigt, bis die App sie nicht mehr zurückgibt.
`actionLabel`	Typ: `string` Beschreibung: Die Beschriftung des Aktionslinks der Bekanntmachung, bis zu 255 Zeichen. Verwende es zusammen mit `actionUrl`.
`actionUrl`	Typ: `string` Beschreibung: Die Adresse, die der Aktionslink in einem neuen Tab öffnet, bis zu 2.048 Zeichen. Muss mit `https://` beginnen. Verwende es zusammen mit `actionLabel`.

Crowdin Enterprise liest eine Antwort von bis zu 512 KB mit bis zu 1.000 Elementen und zeigt daraus die ersten 10 gültigen Bekanntmachungen an. Eine Bekanntmachung, die gegen die obigen Regeln verstößt, wird übersprungen; der restliche Teil der Antwort wird weiterhin verwendet.

Anzeigeregeln

Crowdin Enterprise wendet die folgenden Regeln auf die von einer App zurückgegebenen Bekanntmachungen an:

Bekanntmachungen, die der Benutzer nicht schließen kann, werden zuerst angezeigt; der Rest folgt in der Reihenfolge, in der die Apps installiert wurden.
Der Headerstreifen zeigt jeweils eine Bekanntmachung an. Bei mehr als einer Bekanntmachung zeigt der Streifen zusätzlich einen Zähler und Pfeile zum Wechseln zwischen den Bekanntmachungen an.
Wenn eine Bekanntmachung geschlossen wird, wird sie nur in diesem Browser ausgeblendet.
Crowdin Enterprise lädt die Header-Bekanntmachungen alle 15 Minuten neu sowie die Bekanntmachungen an beiden Positionen, wenn der Benutzer zum Tab zurückkehrt. Eine Bekanntmachung mit expiresAt löst bei Ablauf ebenfalls einen Reload aus.

War diese Seite hilfreich?