Warum Experience Composer API großartig ist

Vonage hat kürzlich die Experience Composer (EC) API. Dieses Angebot stellt einen API-gesteuerten Cloud-Service zur Verfügung, um das gesamte Erlebnis Ihrer Webanwendung mit der Vonage Video API zu erfassen. Das bedeutet, dass das Erscheinungsbild Ihrer Webanwendung nun vollständig aufgezeichnet, über HLS oder RTMP ausgestrahlt oder als neuer Stream in einer Videositzung veröffentlicht werden kann.

In diesem Beitrag erfahren Sie, wie Sie mit Experience Composer einen neuen Video-Stream zu einer bestehenden Vonage-Sitzung hinzufügen können, der Ihr Markenlogo, benutzerdefinierte HTML-Elemente und einen iframe mit Google Calendar enthält. Sie können ein Video wie die Anwendung aussieht, finden Sie am Ende dieses Beitrags.

Host View Diagram

Stellen Sie sich eine Projektplanungssitzung zwischen einem Produktmanager und einem Softwareentwickler vor. Der Produktmanager als Gastgeber veröffentlicht einen Produktplanungskalender mit Fristen und eine HTML-Tabelle mit Arbeitsaufgaben mit Zuständigkeiten und Status. Der Video-Feed des Gastgebers wird mit dem Markenlogo überlagert. Die Gastgeberansicht enthält alle diese Elemente sowie das Video des Gastes.

Der Softwareentwickler in der Rolle des Gastes ist ein Konsument des Streams des Gastgebers, der den Kalender, die Datentabelle und das Video des Gastgebers mit dem Marken-Overlay enthält.

Voraussetzungen

1. Ein Vonage Video API-Konto. Wenn Sie noch kein Konto haben, können Sie sich anmelden und eines erstellen.

2. Node.js Version >= 14.17.5

3. Experience Composer API für Ihren Account aktiviert haben. Sie können dies im Account-Portal.

Wir verwenden Bootstrap aus dem CDN und CSS-Raster, um die Entwicklungszeit zu verkürzen. Ich werde nicht in die Details von CSS gehen, aber Sie können einen Blick auf die CSS-Dateien zusammen mit dem vollständigen Code in der GitHub Repo.

Architektur-Diagramm

Das folgende Diagramm zeigt die Architektur dessen, was wir aufbauen werden. Alles bleibt in einer einzigen Vonage-Videositzung, Video Session A. Zu Beginn wird der Host, Stream A, zusammen mit dem Gast, Stream B, in der Sitzung veröffentlicht. Experience Composer abonniert Stream A und veröffentlicht einen neuen Stream, Stream A (Composite), der das Video des Hosts mit Marken-Overlay sowie den Google-Kalender und die Datentabelle enthält. Der Gast wird diesen zusammengesetzten Stream konsumieren. Beide Nutzer können miteinander kommunizieren.

Architecture Diagram

Der Server

Der Server erstellt Räume, erstellt Sitzungen, generiert Token und sendet Anfragen an die Experience Composer-API, um zu starten und beenden Streams.

Hinweis: Die Experience Composer API wird im Vonage Server SDK derzeit nicht unterstützt. Das Starten und Stoppen von Experience Composer-Streams wird über REST-Aufrufe durchgeführt.

Der /render Endpunkt in unserem Server nimmt die sessionId und die roomName von der POST-Anfrage auf der Client-Seite. Die sessionId wird dann an createRender übergeben, der Experience Composer startet und einige Daten über den Render zurückgibt. Die id wird dann extrahiert und in dem sessions Objekt unter dem roomName als renderId.

app.post('/render', async (req, res) => {
  try {
    const { sessionId, roomName } = req.body;
    if (sessionId && roomName) {
      const data = await createRender(sessionId);
      const { id } = data;
      sessions[roomName].renderId = id;
      res.status(200).send({ id });
    } else {
      res.status(500);
    }
  } catch (e) {
    res.status(500).send({ message: e });
  }
});

Um den vom Experience Composer veröffentlichten Stream zu stoppen, muss unser /render/stop/:id Endpunkt den Render id zum Anhalten der Experience Composer-Instanz benötigt.

app.get('/render/stop/:id', async (req, res) => {
  try {
    const { id } = req.params;
    if (id) {
      console.log('trying to stop render ' + id);
      const data = await deleteRender(id);
      res.status(200).send(data);
    } else {
      res.status(500);
    }
  } catch (e) {
    res.status(500).send({ message: e });
  }
});

Hinweis: Der Code für die createRender und deleteRender Funktionen befindet sich in der Datei index.js-Datei.

Um die Anfragen mit der API zu authentifizieren, müssen wir ein JSON Web Token (JWT) erstellen, wie in der Entwicklerdokumentation. Ich habe das jsonwebtoken Paket von npmverwendet, aber Sie können auch jedes andere Paket verwenden.

Um den Render zu erstellen, müssen wir ein paar Parameter im JSON-Body übergeben, wie in der der Dokumentation. Einige der Parameter sind obligatorisch, wie zum Beispiel die url, sessionId, token, und projectId. Achten Sie besonders auf den url Parameter. Stellen Sie sich diesen als die URL vor, die der "unsichtbare Benutzer", Experience Composer, besuchen wird. Dann JavaScript-Code geladen, damit Experience Composer nur den Host abonniert und ein neuer Stream in der sessionId.

Sie haben vielleicht bemerkt, dass in der createRender Funktion bemerkt haben, dass es ein zusätzliches Objekt properties enthält, das einen name Parameter enthält. Dieser Name wird sich als nützlich erweisen, wenn wir auf streamCreated Ereignisse auf der Client-Seite hören. Wir werden später darauf zurückkommen, aber im Moment müssen Sie nur wissen, dass dies der Name des Streams ist, den wir in der Sitzung veröffentlichen werden.

Unser Server wird auch für die Bereitstellung des statischen HTML-Inhalts für den Client verantwortlich sein. Wir werden einige Routen für die verschiedenen Ansichten in unserer Anwendung einrichten. Eine Route für den Host (den Präsentator, der den Kalender, die Tabelle usw. veröffentlicht), eine weitere für den Gast oder den Konsumenten des Host-Streams und eine weitere für den Experience Composer (das ist der url Parameter, den wir in dem bereits erwähnten JSON-Body senden).

app.get('/host', (req, res) => {
  res.sendFile(__dirname + '/src/host.html');
});

app.get('/ec', (req, res) => {
  res.sendFile(__dirname + '/src/ec.html');
});

app.get('/user', (req, res) => {
  res.sendFile(__dirname + '/src/user.html');
});

Client-seitig

Wir werden eine Vanilla JS-Beispielanwendung erstellen, aber Sie können Experience Composer mit einem beliebigen Framework Ihrer Wahl verwenden. Der clientseitige Code befindet sich im Ordner src-Ordner.

Gast-Ansicht

Stellen Sie sich den Gast als Betrachter des zusammengesetzten Streams des Gastgebers vor, während er gleichzeitig sein Video und seinen Ton sendet, um mit dem Gastgeber zu kommunizieren.

Der Code für die Gastansicht befindet sich in der HTML-Datei user.html mit JavaScript und CSS enthalten. Der Gast wird seinen Video-Stream veröffentlichen und nur den vom Experience Composer veröffentlichten Stream abonnieren. Wir können den vom Experience Composer veröffentlichten Stream selektiv abonnieren, da wir einen Namen für den Stream festgelegt haben.

Wenn wir den streamCreated Ereignis-Listener einrichten, abonnieren wir den Stream nur, wenn der Name des Streams EC ist. Damit soll verhindert werden, dass der Gast den regulären Video-Stream des Gastgebers (ohne Tabelle, Overlay und Iframe) abonniert.

session.on('streamCreated', function streamCreated(event) {
  if (event.stream.name === 'EC') {
    const subscriberOptions = {
      width: '800px',
      height: '500px',
    };
    session.subscribe(
      event.stream,
      'subscriber',
      subscriberOptions,
      handleError
    );
  }
});

So sieht die Gästeansicht aus. Sie können zwei verschiedene Streams sehen. Auf der linken Seite veröffentlicht der Gast seinen Video-Stream, während er auf der rechten Seite den zusammengesetzten Stream abonniert, der vom Experience Composer veröffentlicht wird und den Video-Feed vom Gastgeber, den Kalender, das Overlay und die Datentabelle enthält.

Guest View Diagram

Host-Ansicht

Der Gastgeber ist in diesem Fall die Person, die den Video-Feed zusammen mit einigen benutzerdefinierten Elementen, die für die Anwendung spezifisch sind, veröffentlicht. In dieser Ansicht hat der Gastgeber seinen Video-Feed und abonniert den Video-Feed des Gastes. Das Layout der Gastgeberansicht enthält auch die benutzerdefinierten Elemente (Google-Kalender, eine Datentabelle und ein Marken-Overlay), die vom Experience Composer in der Sitzung veröffentlicht werden.

Die Host-Ansicht wird über die /host Route unserer Anwendung. Ich habe auch beschlossen, einen Abfrageparameter hinzuzufügen, um den Host und den Experience Composer zu identifizieren. Die vollständige Route unseres Hosts wird also sein ${applicationUrl}/host?role=host.

Auch hier sieht die Hostansicht so aus.

Host View Diagram

Der Host und Experience Composer teilen sich die gleiche JavaScript-Datei haben aber separate HTML-Dateien. Die Markup-Datei für den Host finden Sie hier. Um festzustellen, ob Host oder EC, habe ich zwei Funktionen erstellt, isHost und isExperienceComposer.

function isHost() {
  return queryString === '?role=host' && window.location.pathname === '/host';
}

function isExperienceComposer() {
  return (
    queryString === '?role=experience_composer' &&
    window.location.pathname === '/ec'
  );
}

So können wir selektiv die benötigten Streams abonnieren. Der Host braucht den vom Experience Composer erstellten Stream nicht zu abonnieren, da er dann seinen eigenen Stream abonnieren würde. Daher können wir selektiv den Stream abonnieren, dessen Name sich von EC unterscheidet.

session.on('streamCreated', function (event) {
  if (isHost() && event.stream.name !== 'EC') {
    subscribe(event.stream);
  }
});

Die Funktion subscribe Funktion entscheidet, wo der Herausgeber angehängt werden soll, je nachdem, ob der Gastgeber oder der Experience Composer den Stream abonniert. Wenn der Gastgeber versucht, den Stream zu abonnieren, soll das Video des anderen Benutzers (Gast) an das DOM-Element mit der ID subscriberist, d. h. unten rechts in der Host-Ansicht.

function subscribe(stream) {
  session.subscribe(
    stream,
    isExperienceComposer() ? 'publisher' : 'subscriber',
    {
      width: '100%',
      height: '100%',
    },
    handleError
  );
}

Da es sich um eine Beispielanwendung handelt, habe ich der Einfachheit halber auch zwei Schaltflächen zum Starten und Stoppen des Experience Composer-Streams hinzugefügt. Diese Schaltflächen sind nur für den Host sichtbar, aber Sie können den Experience Composer-Stream programmatisch veröffentlichen, sobald das streamCreated Ereignis für den Host ausgelöst wird.

Die Fetch-Aufrufe zum Starten und Stoppen des Experience Composer-Streams sind in der Datei src/index.js implementiert und die Funktionen werden durch Klicken auf die Schaltflächen in der Datei host.html-Datei.

Ein weiterer wichtiger Unterschied zwischen dem Host und dem Experience Composer besteht darin, dass wir dem Host ausdrücklich sagen müssen, dass er veröffentlichen soll. Sobald wir also mit der Sitzung verbunden sind, werden wir nur veröffentlichen, wenn es der Host ist.

session.connect(token, function (error) {
  if (error) {
    handleError(error);
  } else {
    if (isHost()) {
      const publisher = OT.initPublisher(
        'publisher',
        {
          width: '100%',
          height: '100%',
          name: 'host',
        },
        handleError
      );
      publish(publisher);
    }
  }
 });

Der Experience Composer veröffentlicht automatisch in der Sitzung, sodass unser JavaScript-Code den Experience Composer nicht zur Veröffentlichung anweisen muss.

Experience Composer-Ansicht

Der Experience Composer lädt die URL, die wir beim API-Aufruf server-seitig übergeben. Er lädt den JavaScript-Code und veröffentlicht ihn in der Sitzung (die ebenfalls als Parameter übergeben wird). Stellen Sie sich den Experience Composer als einen unsichtbaren Benutzer vor, der der URL beitritt, den Bildschirm erfasst und das Ergebnis als neuen Stream in der Sitzung veröffentlicht.

Da wir einige Hilfsfunktionen erstellt haben, um zu wissen, ob es sich um den Experience Composer oder den Host handelt, können wir die Veröffentlichung des Experience Composers durch unseren JavaScript-Code verhindern, sobald er sich mit der Sitzung verbindet. Siehe den vorherigen Abschnitt.

Es ist auch wichtig zu berücksichtigen, dass der Experience Composer nur den Stream des Hosts abonnieren muss, da der veröffentlichte Stream nur den zusammengesetzten Video-Feed des Hosts enthalten soll.

session.on('streamCreated', function (event) {
  if (isExperienceComposer() && event.stream.name === 'host') {
    subscribe(event.stream);
  }
});

Wenn Sie sich das gewünschte Layout in der Experience Composer-Ansicht ansehen, müssen wir den Abonnenten an die obere rechte Ecke der Seite anhängen, was dem publisher DOM-Element

function subscribe(stream) {
  session.subscribe(
    stream,
    isExperienceComposer() ? 'publisher' : 'subscriber',
    {
      width: '100%',
      height: '100%',
    },
    handleError
  );
}

Dies ist die Experience Composer-Ansicht mit dem abonnierten Stream des Hosts oben rechts.

Experience Composer View Diagram

##Video Demo

Das folgende Video zeigt Ihnen die Host-Ansicht und die Gast-Ansicht.

Aufzeichnung und Ausstrahlung

In dieser Anwendung ist keine Archivierung/Aufzeichnung vorgesehen. Sie können dies jedoch tun, indem Sie die Option streamMode auf den Modus "manuell" setzen, wenn Sie die Archivierung starten und dann die Streams hinzufügen, die Sie in die Aufnahme.

In diesem Fall wollen wir nur den Stream von Experience Composer und den Stream des Gastes archivieren. Andernfalls, wenn wir die drei Streams hinzufügen oder die Option streamMode auf Auto setzen, würden wir 3 Streams in der Aufzeichnung haben, von denen 2 der Host wären.

Der von Experience Composer veröffentlichte Stream kann auch über HLS oder RTMP an ein breiteres Publikum gesendet werden.

Schlussfolgerung

Experience Composer ist ein sehr leistungsfähiges Angebot, das es Ihnen ermöglicht, Ihre Videoanrufe zu bereichern, indem Sie Streams mit so ziemlich allem veröffentlichen, was Sie sich vorstellen können, solange es auf einer Webseite gerendert wird.

Werden Sie den neuen Experience Composer ausprobieren? Wir freuen uns über Ihr Feedback auf dem Vonage Community Slack.