Javascript APIs

Einführung

Die Javascript-API ermöglicht Ihnen die Interaktion mit dem Sitzungsraum und den Webkomponenten. Sie können zum Beispiel einen Teilnehmer stumm schalten, die Teilnehmerliste abrufen, auf Events hören und benutzerdefinierte Events senden, usw.

Die API kann direkt oder über Post-Nachrichten zwischen dem übergeordneten Fenster und dem iFrame des Besprechungsraums verwendet werden.

Grundlagen

Die APIs sind nur verfügbar, wenn der Besprechungsraum vollständig geladen wurde. Daher müssen Sie auf den wlvmrApiReady Callback auf dem Fensterobjekt hören, bevor Sie andere APIs aufrufen oder auf Events hören können. Der wlvmrApiReady übergibt Ihnen einen handler String, unter dem die APIs registriert sind:

Mit on(event: MeetingRoomApiEvent, callback: ApiEventCallback): void können Sie sich für API-Events registrieren und auf diese reagieren.

Die API-Methoden sind über das Objekt window[handler] verfügbar.

Beispiel

Dieser Beispielcode zeigt Ihnen, wie Sie darauf warten, dass der Besprechungsraum bereit ist, wie Sie sich für Besprechungsraumereignisse anmelden und wie Sie Besprechungsraum-APIs aufrufen:

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

  console.log(`Handler window.${handler} steht bereit`)

  window[handler].on("beforeConnecting", (payload) => {
    console.log(`[WLVMR API] - Event 'beforeConnecting' mit ${payload} erhalten`)
  });

  window[handler].on("participantsUpdated", (payload) => {
    console.log(`[WLVMR API] - Event 'participantsUpdated' mit ${JSON.stringify(payload)} erhalten`)
  });

  window[handler].on("chatMessage", (payload) => {
    console.log(`[WLVMR API] - Event 'chatMessage' mit ${JSON.stringify(payload)} erhalten`)
  });

  // Registrieren Sie hier andere Event-Handler

  // Rufen Sie APIs auf
  window[handler].setAudioInputDeviceId("default", false);
  window[handler].setAudioOutputDeviceId("default", false);
  window[handler].setVideoInputDeviceId("default", true);
}

Javascript API

Die folgende Struktur definiert alle verfügbaren APIs:

interface IMeetingRoomApi {
  // Gibt die aktuelle Veeting Version zurück, z. B. 6.8.0
  getVersion(): string;
  // Gibt die aktuelle Teilnehmerliste zurück
  getParticipantsList(): IApiParticipant[];
  // Aktiviert "Follow Me" (benötigt Moderatorenrechte)
  enableFollowMe(enabled: boolean): void;
  // Schaltet Video stumm
  muteVideo(muted: boolean): void;
  // Schaltet Audio stumm
  muteAudio(muted: boolean): void;
    // Definiert die MediaStreamConstraints für getUserMedia Aufrufe
  // Wenn "merge" auf true gesetzt wird, werden die hier übergebenen Constraints mit den internen Constraints
  // vereint, ansonsten werden nur die hier übergebenen Constraints angewendet
    setMediaStreamConstraints(mediaStreamConstraints: MediaStreamConstraints, merge?: boolean /*default = true*/): void;    
  // Wird ignoriert, falls der Teilnehmer schon verbunden ist
  // Teilnehmer werden beim Teilnehmen automatisch verbunden
  connect(audioOnly: boolean /*Standard false*/): void;
  // Wird ignoriert, falls der Teilnehmer nicht verbunden ist
  // "connected" referenziert nur WebRTC Streams.
  // Teilnehmer können z. B. immer noch auf dem Whiteboard zeichnen, 
  // auch wenn sie nicht verbunden sind
  disconnect(): void;
  // Setzt die Kamera. 
  // Achtung, das API verifiziert nicht, ob die deviceId gültig ist
  setVideoInputDeviceId(deviceId: string, reconnect: boolean /*Standard false*/): void;
  // Setzt das Mikrofon. 
  // Achtung, das API verifiziert nicht, ob die deviceId gültig ist
  setAudioInputDeviceId(deviceId: string, reconnect: boolean /*Standard false*/): void;
  // Setzt den Lautsprecher 
  // Achtung, das API verifiziert nicht, ob die deviceId gültig ist
  // Zur Zeit wird diese Funktion nur von Chrome und Edge unterstützt
  setAudioOutputDeviceId(deviceId: string, reconnect: boolean /*Standard false*/): void;
  // Setzt die Videoauflösung
  setVideoResolution(resolution: MeetingRoomVideoResolution, reconnect: boolean /*Standard false*/): void;
  // Gibt die momentan benutzten Geräte zurück
  getMediaDeviceSettings(): IMediaDeviceSettings;
  // Electron Applikationen können die Anfrage für das Teilen des Bildschirms abfangen.
  // Dies erlaubt es Electron Applikationen, eine vordefinierte ID zu setzen
  setScreensharingInterceptor(callback: () => void): void;
  // Wird im Zusammenhang mit setScreensharingInterceptor benutzt.
  // Wirft einen Fehler, falls kein Screensharing Interceptor gesetzt ist
  startScreensharing(sourceId?: string): void;
  // Wird im Zusammenhang mit setScreensharingInterceptor benutzt.
  // Wirft einen Fehler, falls kein Screensharing Interceptor gesetzt ist
  stopScreensharing(): void;
  // Funktioniert nur dann, wenn die Sitzung nur teilweise aufgezeichnet wird
  // (meeting.recordingType === 'partial')
  startRecording(): void;
  // Funktioniert nur dann, wenn die Sitzung nur teilweise aufgezeichnet wird
  // (meeting.recordingType === 'partial')
  stopRecording(): void;
  // Nur erlaubt für Moderatoren
  forceStopScreensharing(): void;
  // Dies funktioniert in den meisten Browsern ausser Chrome nicht
  // Benötigt eine Interaktion des Teilnehmers mit der Applikation
  enterVideoFullscreen(): void;
  // Sendet eine Nachricht in den Gruppenchat
  sendChatMessage(message: string): void;
  // Sendet eine private Nachricht an einen Teilnehmer
  sendPrivateChatMessage(message: string, participantId: string): void;
  // Sendet einen benutzerdefinierten Event an alle Teilnehmer
  sendCustomMessage(message: ICustomMessage): void;
  // Stoppt die Verbindung zum Server und verlässt den Sitzungsraum
  leaveMeeting(): void;
  // Erlaubt es APIs, die Darstellung der Videos anzupassen
  // Siehe separate Dokumentation dazu
  setVideoDisplayCalculator(videoDisplayCalculator: IVideoDisplayCalculator): void;
  // Hört auf Events des Sitzungsraumes
  on(event: MeetingRoomApiEvent, callback: ApiEventCallback): void;
}

Typendefinition

Die folgenden Objekte werden als Input respektive Output-Parameter benutzt

Interfaces

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

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 IVideoPosition {
  participantId: string;
  width: number;
  height: number;
  top: number;
  left: number;
  zIndex: number;
  // Wichtig: CSS Klasse MÜSSEN mit dem Prefix 'video-container-' versehen sein
  cssClasses?: string[]
}

interface IVideoDisplayConfig {
  videoPositions: IVideoPosition[],
  hiddenContainers: boolean[]
}

interface IVideoDisplayCalculator {
  calculatePositions(
    containerWidth: number,
    containerHeight: number,
    secondaryPosition: SecondaryVideoPosition,
    secondaryDisplay: SecondaryDisplay,
    secondarySize: SecondaryVideoSize,
    primaryParticipants: string[],
    secondaryParticipants: string[],
    participantsOrder: string[],
    hasSelfView: boolean,
    isSelfviewInSecondary: boolean,
    isTVMode: boolean
  ): IVideoDisplayConfig;
}


interface IMeetingRoomConfig {
  isNamedRoom: boolean;
  meetingId: string;
  roomId: string;
  id: string;
  topic: string;
  meetingType: MeetingType;
  dialInEnabled: boolean;
  passwordProtected: boolean;
  hasVideo: boolean;
  startTime: number;
  endTime: number;
  isOpen: boolean;
  isPreOpen: boolean;
  isClosed: boolean;
  isActive: boolean;
  isDemoMeeting: boolean;
  isPromoMeeting: boolean;
  isFreeMeeting: boolean;
  isRecorded: boolean;
  isAccountValid: boolean;
  maxNumberOfParticipants?: number;
  organizerId: string;
  accountId: string;
  logoFileName?: string;
  disableLogs?: boolean;
  broadcastingEnabled?: boolean;
  participantsEmail?: Availability;
  authType?: MeetingRoomAuthType;
  meetingRoomLayout?: MeetingRoomLayout;
  joinMeetingSound?: string;
  leaveMeetingSound?: string;
  closingMeetingSound?: string;
  closedMeetingSound?: string;
}

interface ICustomMessage {
  from?: string;
  to?: string;
  data?: any;
  onlyToModerators?: boolean;
}

Enums

enum MeetingRoomApiEvent {
  beforeConnecting = "beforeConnecting",
  serverConnected = "serverConnected", // WebRTC Verbindung aufgebaut
  connected = "connected", // WebRTC Verbindung aufgebaut
  disconnected = "disconnected", // WebRTC Verbindung unterbrochen
  leave = "leave",
  participantsUpdated = "participantsUpdated",
  chatMessage = "chatMessage",
  privateChatMessage = "privateChatMessage",
  meetingDurationUpdated = "meetingDurationUpdated",
  meetingRoomConfigUpdated = "meetingRoomConfigUpdated",
  customMessage = "customMessage",
  screenshareStateChange = "screenshareStateChange"
}

enum SecondaryVideoSize {
  small = 0.15,
  large = 0.5
}

enum MeetingRoomVideoResolution {
  "1280x960" = "1280x960",
  "1280x720" = "1280x720",
  "960x720" = "960x720",
  "960x540" = "960x540",
  "640x480" = "640x480",
  "640x360" = "640x360",
  "320x240" = "320x240",
  "320x180" = "320x180",
  "160x120" = "160x120"
}

enum MeetingType {
  standard = "standard",
  offTheRecord = "offTheRecord",
  boardroom = "boardroom",
  classroom = "classroom",
  audiobridge = "audiobridge"
}

enum MeetingRoomLayout {
  classic = "classic",
  presentation = "presentation",
  template = "template"
}

enum Availability {
  required = "required",
  optional = "optional",
  hidden = "hidden"
}

enum MeetingRoomAuthType {
  none = "none",
  invited = "invited",
  accountMember = "accountMember",
  platformMember = "platformMember",
  external = "external"
}

Typen

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

type SecondaryVideoPosition = "none" | "left" | "top" | "right" | "bottom";
type SecondaryDisplay = "display" | "hidden";