JavaScript APIs

Übersicht

Mit der JavaScript-API steuern Sie aus Ihrer eigenen Seite heraus einen laufenden Meetingraum. Sie muten Teilnehmer, lesen die Teilnehmerliste, senden Chat-Nachrichten, wechseln Geräte und hören auf Events. Das gelingt Ihnen mit einem eingebetteten iFrame genauso wie mit den Web-Komponenten von Veeting Blocks.

Verwendung mit einem KI-Assistenten

Wenn Sie mit einem KI-Coding-Assistenten arbeiten, können Sie den folgenden Text in Ihren Assistenten kopieren und mit einem Satz ergänzen, der beschreibt, was Sie programmieren möchten.

Der Prompt verweist auf unsere Entwicklerdokumentation, die wir für Coding-Assistenten in einer separaten, token-optimierten KI-Version ausliefern.

Lies zuerst diese Seite, bevor Du Code schreibst:
https://www.veeting.com/de/developer-documentation/javascript-apis

Sie dokumentiert die JavaScript-API eines Veeting Rooms
Meetingraums. Halte Dich an diese fünf Regeln:

1. Frage mich zuerst, ob mein Code IM Raum läuft (Veeting Blocks,
   ein eigenes Tool) oder in der Seite rund um einen eingebetteten
   iFrame. Beide erreichen die API völlig unterschiedlich, und die
   Antwort ändert alles Weitere.
2. Warte auf das Event «joined», bevor Du Methoden aufrufst, die
   die Anwesenheit im Meeting voraussetzen.
3. «connected» und «disconnected» beziehen sich auf den WebSocket
   zu unserer API, nicht auf WebRTC-Medien. Behandle sie nicht als
   Medienzustand.
4. Verwende nur Methoden, die auf dieser Seite stehen. Erfinde
   keine und rate keine Signatur.
5. Aus einer übergeordneten Seite sprichst Du per postMessage mit
   dem Raum: {action, payload} hinein, {event, payload} heraus. Das
   geht nur in eine Richtung, Methoden mit Rückgabewert nützen dort
   also nichts. Prüfe message.origin bei allem, was ankommt.

Was ich bauen möchte:

Wo Ihr Code läuft, entscheidet über den Zugang zur API

Das ist wichtiger als alles andere auf dieser Seite, klären Sie es deshalb zuerst.

Betten Sie den Raum als iFrame ein, sind Ihre Seite und der Meetingraum zwei verschiedene Dokumente, meist auf zwei verschiedenen Origins. Ihre Seite kommt nicht an das window des Raums heran und der Raum nicht an Ihres. Alles überquert diese Grenze als Nachricht.

Unterschiedliche Origins sind vorgesehen und unterstützt. Der Raum läuft normalerweise unter Ihrer eigenen White-Label-Domain, meeting.example.com, während Ihre Anwendung unter app.example.com oder ganz woanders liegt. Beides braucht keine Sonderbehandlung: Eine andere Subdomain und eine völlig andere Domain verhalten sich hier gleich.

Den Raum aus der umgebenden Seite steuern

Events empfangen

Der Meetingraum sendet jedes Event an sein übergeordnetes Fenster. Hören Sie darauf:

window.addEventListener("message", (message) => {
  // Always check the origin. The room posts to any parent, so this check is
  // yours to make, and without it any page could forge these events.
  if (message.origin !== "https://<DOMAIN-NAME>") {
    return;
  }

  const { event, payload } = message.data;

  if (event === "joined") {
    console.log("The meeting room is ready");
  }

  if (event === "participantsUpdated") {
    console.log(`${payload.length} participants in the room`);
  }
});

event ist einer der 12 Namen weiter unten, payload genau das, was dieses Event mitführt. Sie müssen nichts abonnieren: Jedes Event geht an die übergeordnete Seite, ob Sie darauf hören oder nicht.

Methoden aufrufen

Senden Sie dem iFrame eine Nachricht mit dem Namen der Methode und ihren Argumenten:

const room = document.getElementById("meeting-frame");

room.contentWindow.postMessage({
  action: "muteAudio",
  payload: [true]
}, "https://<DOMAIN-NAME>");

action ist der Methodenname, payload sind ihre Argumente in der richtigen Reihenfolge als Array. Eine Methode ohne Argumente braucht trotzdem payload: [] oder gar nichts.

Weil der Weg nur in eine Richtung führt, gelten zwei Grenzen:

• Sie erhalten keinen Rückgabewert. Alles, was mit get beginnt, nützt über diese Grenze hinweg also nichts. Lesen Sie die Teilnehmer aus dem Event participantsUpdated statt über getParticipantsList(), und die Raumkonfiguration aus meetingRoomConfigUpdated.
• Sie erhalten auch keinen Fehler. Vertippen Sie sich im Methodennamen, geschieht nichts und niemand meldet es. Prüfen Sie den Namen gegen die Tabellen weiter unten.

Ein vollständiges Beispiel

Ihr eigener Mute-Button und Ihr eigener Teilnehmerzähler, in Ihrer eigenen Seite, ausserhalb des iFrames:

<button id="mute">Mute</button>
<span id="count">0</span> participants

<iframe id="meeting-frame"
  src="https://<DOMAIN-NAME>/meeting/<MEETING-ID>"
  allow="microphone;camera;encrypted-media;fullscreen;autoplay;display-capture;layout-animations;">
</iframe>

<script>
  const ROOM_ORIGIN = "https://<DOMAIN-NAME>";
  const room = document.getElementById("meeting-frame");
  let muted = false;

  window.addEventListener("message", (message) => {
    if (message.origin !== ROOM_ORIGIN) {
      return;
    }
    if (message.data.event === "participantsUpdated") {
      document.getElementById("count").textContent = message.data.payload.length;
    }
  });

  document.getElementById("mute").addEventListener("click", () => {
    muted = !muted;
    room.contentWindow.postMessage({ action: "muteAudio", payload: [muted] }, ROOM_ORIGIN);
  });
</script>

Den Handler erhalten

Der übrige Teil dieses Abschnitts gilt für Code, der im Meetingraum läuft: Veeting Blocks oder ein eigenes Tool. Betten Sie einen iFrame ein, verwenden Sie stattdessen die Nachrichten oben.

Die API existiert erst, wenn der Meetingraum vollständig geladen ist. Aus einem Skript, das beim Laden der Seite läuft, erreichen Sie sie deshalb noch nicht. Definieren Sie stattdessen auf window eine Funktion wlvmrApiReady. Sobald der Raum bereit ist, ruft er sie auf und übergibt Ihnen den Namen des Objekts, unter dem er sich registriert hat.

window["wlvmrApiReady"] = (handler) => {
  if (!window[handler]) {
    console.error(`Handler window.${handler} not found!`);
    return;
  }

  // Every API method lives on this object
  window[handler].muteAudio(true);
};

Daraus folgen zwei Regeln. Beide gehen häufig vergessen:

1. Definieren Sie wlvmrApiReady, bevor der Meetingraum lädt. Weisen Sie die Funktion später zu, ist der Aufruf längst erfolgt und Sie erhalten den Handler nie.
2. Schreiben Sie den Handler-Namen nicht fest in den Code. Sie bekommen ihn als Argument. Greifen Sie immer über window[handler] zu, nie über einen festen Namen.

Ein durchgängiges Beispiel

Warten Sie auf den Raum, abonnieren Sie Events und rufen Sie erst dann Methoden auf:

window["wlvmrApiReady"] = (handler) => {
  if (!window[handler]) {
    console.error(`Handler window.${handler} not found!`);
    return;
  }

  const api = window[handler];

  api.on("joined", () => {
    console.log("The meeting room is ready to use");
  });

  api.on("participantsUpdated", (participants) => {
    console.log(`${participants.length} participants in the room`);
  });

  api.on("chatMessage", (message) => {
    console.log(`${message.fromParticipantName}: ${message.message}`);
  });

  api.setAudioInputDeviceId("default", false);
  api.setVideoInputDeviceId("default", true);
};

Events

Sie abonnieren mit on(event, callback). Es gibt 12 Events.

Hinweis: connected und disconnected beschreiben den WebSocket zu unserer API, nicht die WebRTC-Medien. Ein Teilnehmer kann von den Medien getrennt sein und trotzdem das Whiteboard nutzen.

Methoden

Meeting und Teilnehmer

Audio und Video

Geräte

reconnect steht standardmässig auf false. Übergeben Sie true, baut der Raum die Medien neu auf und die Änderung greift sofort.

Die drei Listen-Methoden können eine Abfrage auslösen. Sie fragen den Browser nach der Medienberechtigung, um die Gerätenamen lesen zu können. Ein Aufruf kann also einen Berechtigungsdialog öffnen. Rufen Sie sie deshalb dann auf, wenn der Teilnehmer damit rechnet, und nicht beim Laden der Seite.

Screensharing und Aufzeichnung

Nachrichten

Darstellung und Events

Zusätzliche Methoden in Veeting Blocks

Setzen Sie Veeting Blocks statt eines eingebetteten Raums ein, erhalten Sie vier zusätzliche Methoden. Mit ihnen steuern Sie den Beitritt selbst:

Typdefinitionen

interface IApiParticipant {
  id: string;
  name: string;
  muted?: boolean;
  handRaised?: boolean;
  fromPSTN?: boolean;
  hasVideo?: boolean;
  hadVideo?: boolean;
  joinedAt: number;
}

interface IApiChatMessage {
  fromParticipantId: string;
  fromParticipantName: string;
  message: string;
}

interface IApiRemainingTimeUpdate {
  remainingSeconds: number;
}

interface IScreenshareState {
  active: boolean;
}

interface IMediaDeviceSettings {
  videoResolution: string;
  audioInputDeviceId: string;
  audioOutputDeviceId: string;
  videoInputDeviceId: string;
}

interface IMeetingConnectionConfig {
  meetingId: string;
  participantName: string;
  participantEmail?: string;
  audio: boolean;
  video: boolean;
  moderatorToken?: string;
  interpreterToken?: string;
  invisibleToken?: string;
  speakerToken?: string;
}

type MediaDirection = "receiveonly" | "sendonly" | "sendreceive";
type JoinMode = "audio-only" | "audio-video" | "video-only" | "no-media";

type ApiEventCallback = (payload: void | IApiParticipant[] | IApiChatMessage
  | IApiRemainingTimeUpdate | IMeetingRoomConfig | ICustomMessage | IScreenshareState) => void;

Häufige Fehler

• Sie weisen wlvmrApiReady zu, nachdem der Meetingraum geladen ist. Die Funktion wird dann nie aufgerufen.
• Sie schreiben den Handler-Namen fest in den Code, statt den übergebenen zu verwenden.
• Sie rufen eine Methode vor dem Event joined auf. Der Raum ist dann zwar geladen, das Meeting aber noch nicht betreten.
• Sie halten connected für einen Beleg, dass Medien fliessen. Es bezieht sich auf den WebSocket zu unserer API.
• Sie erwarten von startScreensharing eine Rückmeldung. Darf der Teilnehmer nicht teilen, kehrt der Aufruf stillschweigend zurück.
• Sie rufen startRecording in einem Meeting auf, das nicht für teilweise Aufzeichnung konfiguriert ist.
• Sie rufen forceStopScreensharing ohne Moderationsrechte auf. Der Server blockiert es.
• Sie übergeben eine Geräte-ID, ohne zu prüfen, ob sie existiert. Die API validiert sie nicht.