# Custom Tools – eigene Widgets im Meetingraum

Source: https://www.veeting.com/de/developer-documentation/custom-tools

## Übersicht

Mit Custom Tools bringen Sie Ihre eigene Oberfläche in den Meetingraum, gleichberechtigt neben Video, Dokumenten und Whiteboard. Ein Tool besteht aus einem Icon, einem Label und einer Ihrer Seiten, die der Raum in einem iFrame darstellt.

Sie konfigurieren die Tools in den Systemeinstellungen einer White-Label-Instanz. **Pro Instanz gibt es genau eine Konfiguration**, standardmässig ist keine hinterlegt.

## Die Quelle wählen

Sie stellen ein Tool auf zwei Wegen bereit. Eine Instanz nutzt jeweils einen davon.

| Quelle       | Was sie tut                                                                                 | Wann sie passt                                                          |
| ------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| iFrame-URL   | Eine feste URL, für alle sichtbar                                                           | Alle Teilnehmer sehen dasselbe Tool.                                    |
| API-Endpunkt | Wir rufen für jeden Teilnehmer Ihren Endpunkt auf, und Sie geben die passenden Tools zurück | Die Tools unterscheiden sich pro Teilnehmer, oder Sie brauchen mehrere. |

Wie Sie sich auch entscheiden: Custom Tools müssen für die Instanz aktiviert sein, sonst erscheint nichts.

## Eine feste iFrame-URL

![Konfiguration eines Custom Tools über eine feste iFrame-URL](/assets/img/documentation/custom-tools-iframe-configuration.png)

Liefern Sie die URL über HTTPS aus. Ihr Webserver muss zudem Header senden, die dem Browser erlauben, Ihre Seite innerhalb unserer Seite darzustellen.

### Das Label

Sie geben entweder einen festen String an oder eine Liste von Übersetzungen, mit Pipes (`|`) getrennt.

| Label                                                                 | Ergebnis                                                                                                                                                                                            |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| My Custom Tool                                                        | Zeigt immer «My Custom Tool», egal, in welcher Sprache der Meetingraum läuft.                                                                                                                       |
| en:My Custom Tool\|de-CH:Mein eigenes Tool\|fr:Mon outil personnalisé | Auf Englisch erscheint «My Custom Tool», auf Deutsch «Mein eigenes Tool» und so weiter. Fehlt eine Sprache in der Liste, greift der erste Eintrag. Setzen Sie die Standardsprache an den Anfang.    |

### Was wir an Ihre URL anhängen

Wir ergänzen Query-Parameter, damit Ihre Seite weiss, wer sie betrachtet. Das gilt für eine feste URL und für die `iFrameUrl` jedes Tools, das ein API-Endpunkt zurückgibt:

| Parameter       | Wert                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------- |
| participantName | Der Name des Teilnehmers                                                                    |
| participantId   | Die eindeutige ID des Teilnehmers                                                           |
| meetingId       | Die 24 Zeichen lange Meeting-ID, zum Beispiel `5349b4ddd2781d08c09890f3`                    |
| meetingToken    | Die Meetingnummer mit Bindestrichen, zum Beispiel `0000-0000-0000-0000`                     |
| culture         | Die aktuelle Oberflächensprache des Raums, zum Beispiel `en`, `en-US` oder `de-DE`          |

Drei Dinge sollten Sie wissen:

- Wechselt der Teilnehmer die Sprache des Raums, laden wir den iFrame des Tools mit dem neuen `culture` neu.
- **`moderatorToken` senden wir hier nicht.** Den erhält nur ein API-Endpunkt, siehe unten. Mit einer festen iFrame-URL erkennen Sie deshalb nicht, ob der Betrachter Moderator ist.
- Enthält Ihre URL bereits ein `?`, hängen wir die Parameter mit `&` an. Eine URL mit eigenem Query-String funktioniert also weiterhin.

Die Werte sind URL-codiert. Decodieren Sie sie also, bevor Sie damit arbeiten. Ein Name mit einem Leerzeichen oder einem `&` kommt so unversehrt bei Ihnen an.

## Ein API-Endpunkt

Mit einem API-Endpunkt entscheiden Sie pro Teilnehmer, welche Tools erscheinen. Bis zu fünf dürfen es sein.

![Konfiguration eines Custom Tools über einen API-Endpunkt](/assets/img/documentation/custom-tools-api-configuration.png)

Tritt jemand bei, rufen wir Ihren Endpunkt auf und zeigen dieser Person an, was Ihr Endpunkt zurückgibt.

![Ein Browser betritt das Meeting, der Meeting-Server ruft Ihren API-Endpunkt mit Angaben zu Teilnehmer und Meeting auf, Ihr Endpunkt entscheidet über die Tools und liefert bis zu fünf zurück, und der Meetingraum zeigt sie an](/assets/img/documentation/custom-tools-api-workflow.de.svg)

```mermaid
sequenceDiagram
    autonumber
    participant B as Webbrowser
    participant V as Web-Meeting-Server
    participant I as Ihr API-Endpunkt
    B->>V: Betritt das Meeting
    V->>I: GET, mit Angaben zu Teilnehmer und Meeting
    Note over I: Entscheidet, welche Tools<br/>diese Person sieht
    I-->>V: Liefert bis zu fünf Tools
    V-->>B: Liefert die Liste der Tools
    Note over B: Zeigt die Tools<br/>im Meetingraum
```

### Der Aufruf

Wir schicken ein HTTP `GET` mit diesen Query-Parametern und legen Ihr konfiguriertes Geheimnis in den Header `X-API-KEY`:

| Parameter       | Wert                                  |
| --------------- | ------------------------------------- |
| participantName | Der Name des Teilnehmers              |
| participantId   | Die eindeutige ID des Teilnehmers     |
| meetingId       | Die 24 Zeichen lange Meeting-ID       |
| meetingToken    | Die Meetingnummer mit Bindestrichen   |
| moderatorToken  | Der Moderatoren-Token des Teilnehmers |

> **Hinweis:** Die Anfrage an Ihren Endpunkt enthält `culture` **nicht**, `moderatorToken` hängen wir dagegen **immer** an. Die `iFrameUrl` jedes Tools, das Sie zurückgeben, erhält `culture` trotzdem, zusammen mit den übrigen Parametern aus «Was wir an Ihre URL anhängen». Bei einem Teilnehmer ohne Moderationsrechte ist der Parameter zwar vorhanden, enthält aber keinen gültigen Wert. Prüfen Sie deshalb den Wert selbst und nicht, ob der Parameter vorhanden ist. Alle Werte sind URL-codiert.

```bash
curl 'https://<CUSTOM-TOOL-API-URL>?participantName=Joe%20Doe\
&participantId=XXXXX\
&meetingId=5349b4ddd2781d08c09890f3\
&meetingToken=0000-0000-0000-0000\
&moderatorToken=YYYYY' \
  -H 'X-API-KEY: <CUSTOM-TOOL-API-KEY>' \
  -H 'accept: application/json, text/plain, */*'
```

### Die Antwort

Antworten Sie mit HTTP 200 und einem **reinen JSON-Array** von Tool-Objekten. Verpacken Sie es nicht. Anders als bei der REST API entpackt hier niemand eine `data`-Eigenschaft für Sie.

| Eigenschaft | Bedeutung                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| iFrameUrl   | Die URL, die wir darstellen. **Fehlt sie, überspringen wir das Tool.**                                       |
| toolIcon    | Ein SVG-String für das Icon. Alles über 50'000 Zeichen verwerfen wir, und das Tool erhält das Standard-Icon. |
| labels      | Ein Array von Label-Objekten                                                                                 |

Ein Label-Objekt:

| Eigenschaft | Bedeutung                                                         |
| ----------- | ----------------------------------------------------------------- |
| culture     | Das Locale dieses Labels, zum Beispiel `en`, `en-US` oder `de-DE` |
| label       | Der anzuzeigende Text, zum Beispiel «My Custom Tool»              |

```json
[
  {
    "iFrameUrl": "https://www.example.com/custom-tool-1",
    "toolIcon": "<svg>...</svg>",
    "labels": [
      {
        "culture": "en-US",
        "label": "Custom tool 1"
      },
      {
        "culture": "de",
        "label": "Spezialtool 1"
      }
    ]
  }
]
```

### Grenzen und Fallbacks

- **Höchstens fünf Tools.** Wir hören nach dem fünften brauchbaren Tool auf; alles danach ignorieren wir.
- Ein Tool ohne `iFrameUrl` überspringen wir vollständig.
- Fehlt `labels` oder ist das Array leer, erhält das Tool das Label «Custom tool».
- Kann der Meetingraum das Locale des Teilnehmers nicht zuordnen, nimmt er das erste Label Ihres Arrays. Setzen Sie Ihren bevorzugten Standard deshalb an den Anfang.
- **Fünf Sekunden für die Antwort.** Wir warten höchstens 5 Sekunden auf Ihren Endpunkt. Der Teilnehmer ist während dieser Zeit bereits im Raum. Ein langsamer Endpunkt verzögert also die Tools, nie den Beitritt.
- Antwortet Ihr Endpunkt mit einem Fehler, antwortet er nicht innerhalb von 5 Sekunden oder gibt er kein Array zurück, zeigen wir keine Custom Tools an. Das Meeting läuft normal weiter.

## Häufige Fehler

- `meetingId` und `meetingToken` vertauschen. `meetingId` ist die 24 Zeichen lange, `meetingToken` die mit den Bindestrichen.
- `moderatorToken` bei einer festen iFrame-URL erwarten, wo wir ihn nie senden.
- `culture` in der Anfrage an den API-Endpunkt erwarten. Es wird nur an die iFrame-URL angehängt.
- Das Vorhandensein von `moderatorToken` als Nachweis für Moderationsrechte werten.
- Die API-Antwort verpacken, statt ein reines Array zurückzugeben.
- Mehr als fünf Tools zurückgeben und sich wundern, wo die übrigen geblieben sind.
- Das Tool über HTTP ausliefern oder mit Headern, die das Einbetten verbieten.
- Einen Teilnehmernamen direkt aus dem Query-String lesen, ohne ihn zu decodieren.
- Vor der Antwort langsame Abfragen erledigen. Nach 5 Sekunden warten wir nicht mehr, und dieser Teilnehmer erhält keine Custom Tools.

---

## Die übrige Dokumentation

- [Externer Autorisierungsdienst](https://www.veeting.com/de/developer-documentation/external-meeting-authorization-service)
- [iFrame und Web Komponenten](https://www.veeting.com/de/developer-documentation/iframe-and-web-components)
- [JavaScript APIs](https://www.veeting.com/de/developer-documentation/javascript-apis)
- [JavaScript und Typescript APIs](https://www.veeting.com/de/veeting-blocks/apis)
- [Komponenten](https://www.veeting.com/de/veeting-blocks/components)
- [Kontrolle über die Videodarstellung](https://www.veeting.com/de/developer-documentation/video-display-calculator)
- [Parameter in der URL](https://www.veeting.com/de/developer-documentation/query-parameters)
- [Raumsystem-Steuerung](https://www.veeting.com/de/developer-documentation/room-system-control)
- [Recording Pipeline](https://www.veeting.com/de/developer-documentation/recording-pipeline)
- [Veeting Blocks - Übersicht](https://www.veeting.com/de/veeting-blocks/introduction)
- [Veeting Rooms REST APIs](https://www.veeting.com/de/developer-documentation/api-usage)
- [Webhooks](https://www.veeting.com/de/developer-documentation/web-hooks)

Alles in einer Datei: https://www.veeting.com/llms-full.txt
