Por que a API do Experience Composer é excelente

A Vonage lançou recentemente API do Experience Composer (EC). Essa oferta fornece um serviço em nuvem baseado em API para capturar toda a experiência do seu aplicativo web usando a Video API da Vonage. Isso significa que a aparência e a experiência do seu aplicativo web agora podem ser totalmente gravadas, transmitidas via HLS ou RTMP, ou publicadas como uma nova transmissão em uma sessão de vídeo.

Nesta postagem, vamos explicar como você pode usar o Experience Composer para adicionar uma nova transmissão de Video a uma sessão existente do Vonage, incluindo o logotipo da sua marca, elementos HTML personalizados e um iframe com o Google Agenda. Você pode ver um Vídeo que mostra como fica o aplicativo no final desta postagem.

Host View Diagram

Imagine uma sessão de planejamento de projeto entre um gerente de produto e um desenvolvedor de software. O gerente de produto, na qualidade de anfitrião, publicará um calendário de planejamento do produto com prazos e uma tabela em HTML contendo itens de trabalho com responsáveis e status. A transmissão de vídeo do anfitrião terá o logotipo da marca sobreposto. A tela do anfitrião exibirá todos esses itens, bem como o vídeo do convidado.

O desenvolvedor de software, na qualidade de convidado, é um consumidor da transmissão do anfitrião, que inclui o calendário, a tabela de dados e o Video do anfitrião com a sobreposição da marca.

Pré-requisitos

1. Uma conta da Video API da Vonage. Se você não tiver uma conta, pode se cadastrar e criar uma.

2. Versão do Node.js >= 14.17.5

3. A API do Experience Composer está habilitada para sua Account. Você pode fazer isso no portal da conta.

Vamos usar o Bootstrap do CDN e a grade CSS para agilizar o tempo de desenvolvimento. Não vou entrar em detalhes sobre CSS, mas você pode dar uma olhada nos arquivos CSS junto com o código completo no repositório do GitHub repositório.

Diagrama de arquitetura

O diagrama a seguir mostra a arquitetura do que vamos construir. Tudo permanecerá em uma única sessão de vídeo da Vonage, a Sessão de Vídeo A. Para começar, o anfitrião, o Stream A, será publicado na sessão junto com o convidado, o Stream B. No entanto, o convidado ainda não se inscreverá no anfitrião. O Experience Composer se inscreverá no Stream A e publicará um novo stream, o Stream A (Composto), contendo o Video do anfitrião com sobreposição da marca, juntamente com o Google Agenda e a tabela de dados. O convidado consumirá esse stream composto. Ambos os usuários poderão se comunicar entre si.

Architecture Diagram

O servidor

O servidor cria salas, inicia sessões, gera tokens e envia solicitações à API do Experience Composer para iniciar e interromper transmissões.

Observação: Atualmente, a API do Experience Composer não é compatível com o SDK do Vonage Server. O início e a interrupção das transmissões do Experience Composer serão realizados por meio de chamadas REST.

O /render endpoint em nosso servidor receberá o sessionId e o roomName da solicitação POST do nosso lado do cliente. O sessionId é então passado para createRender , que iniciará o Experience Composer e retornará alguns dados sobre a renderização. O id é então extraído e salvo no sessions objeto sob o roomName como 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 });
  }
});

Da mesma forma, para interromper o fluxo publicado pelo Experience Composer, nosso /render/stop/:id ponto de extremidade chamará o método Render id necessário para interromper a instância do Experience Composer.

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 });
  }
});

Observação: O código para o createRender e deleteRender funções pode ser encontrado no arquivo index.js.

Para autenticar as solicitações na API, precisamos criar um JSON Web Token (JWT), conforme explicado na documentação para desenvolvedores. Utilizei o jsonwebtoken pacote do npm, mas fique à vontade para usar qualquer outro pacote.

Para criar a renderização, precisamos passar alguns parâmetros no corpo do JSON, conforme documentação. Alguns dos parâmetros são obrigatórios, como o url, sessionId, tokene projectId. Preste atenção especial ao url . Pense nele como a URL que o “usuário invisível”, o Experience Composer, irá acessar. Em seguida, código JavaScript será carregado para que o Experience Composer se inscreva apenas no host, e um novo fluxo será publicado no sessionId.

Você deve ter notado na createRender função que há um objeto a mais properties que contém um name parâmetro. Esse nome será útil quando ouvirmos streamCreated eventos no lado do cliente. Voltaremos a isso daqui a pouco, mas tudo o que você precisa saber por enquanto é que esse é o nome do fluxo que vamos publicar na sessão.

Nosso servidor também será responsável por fornecer o conteúdo HTML estático ao cliente. Vamos configurar algumas rotas para as diferentes visualizações do nosso aplicativo. Uma rota para o host (o apresentador que publicará o calendário, a tabela etc.), outra para o convidado ou consumidor do stream do host e mais uma para o Experience Composer (esse é o url parâmetro que enviamos no corpo JSON mencionado anteriormente).

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');
});

Do lado do cliente

Vamos criar um aplicativo de exemplo em Vanilla JS, mas você pode usar o Experience Composer com qualquer framework de sua preferência. O código do lado do cliente está localizado na pasta src.

Opinião de um convidado

Pense no convidado como um espectador da transmissão combinada do anfitrião, ao mesmo tempo em que envia seu próprio Video e áudio para se comunicar com o anfitrião.

O código para a visualização do visitante pode ser encontrado no arquivo HTML user.html , que inclui o JavaScript e o CSS. O visitante publicará sua transmissão de Video e se inscreverá apenas na transmissão publicada pelo Experience Composer. Podemos nos inscrever seletivamente na transmissão publicada pelo Experience Composer porque definimos um nome para ela.

Ao configurarmos o streamCreated ouvinte de eventos, só nos inscreveremos no stream se o nome dele for EC. Isso serve para impedir que o convidado se inscreva no stream de Video normal do anfitrião (sem tabela, sobreposição e iframe).

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

Esta é a aparência da tela do convidado. É possível ver duas transmissões diferentes. À esquerda, o convidado está transmitindo seu vídeo, enquanto à direita ele está acessando a transmissão composta publicada pelo Experience Composer, que contém o feed de Video do anfitrião, o calendário, a sobreposição e a tabela de dados.

Guest View Diagram

Visão do anfitrião

O anfitrião, neste caso, é a pessoa que publicará o feed de vídeo juntamente com alguns elementos personalizados específicos do aplicativo. Nesta visualização, o anfitrião tem seu próprio feed de vídeo e se inscreverá no feed de vídeo do convidado. O layout da visualização do anfitrião também terá os elementos personalizados (Calendário do Google, uma tabela de dados e sobreposição da marca) que serão publicados na sessão pelo Experience Composer.

A visualização do host será carregada na /host rota do nosso aplicativo. Também decidi adicionar um parâmetro de consulta para identificar o host e o Experience Composer. Portanto, a rota completa do nosso host será ${applicationUrl}/host?role=host.

Mais uma vez, é assim que a visualização do anfitrião ficará.

Host View Diagram

O host e o Experience Composer compartilharão o mesmo arquivo JavaScript , mas terão arquivos HTML separados. O arquivo de marcação do host pode ser encontrado aqui. Para determinar se é o host ou o EC, criei duas funções, isHost e isExperienceComposer.

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

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

Isso nos permitirá assinar seletivamente os fluxos de que precisamos. O host não precisa se inscrever no fluxo criado pelo Experience Composer, pois, nesse caso, estaria se inscrevendo em seu próprio fluxo. Portanto, podemos nos inscrever seletivamente no fluxo cujo nome seja diferente de EC.

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

A subscribe função decidirá onde anexar o editor, dependendo se é o host ou o Experience Composer que está se inscrevendo no stream. Se for o host tentando se inscrever, vamos querer anexar o Video do outro usuário (convidado) ao elemento DOM cujo id é subscriber, ou seja, no canto inferior direito da visualização do Anfitrião.

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

Como se trata de um aplicativo de exemplo, adicionei também, por conveniência, dois botões para iniciar e parar a transmissão do Experience Composer. Esses botões ficarão visíveis apenas para o anfitrião, mas você pode publicar a transmissão do Experience Composer programaticamente assim que o streamCreated evento para o anfitrião for acionado.

As chamadas de recuperação para iniciar e interromper o fluxo do Experience Composer estão implementadas no src/index.js e as funções são chamadas ao clicar nos botões no arquivo arquivo host.html.

Outra diferença importante entre o anfitrião e o Experience Composer é que precisamos instruir explicitamente o anfitrião a publicar. Portanto, uma vez conectados à sessão, só publicaremos se formos o anfitrião.

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);
    }
  }
 });

O Experience Composer publicará automaticamente na sessão, de modo que nosso código JavaScript não precisa instruir o Experience Composer a publicar.

Experimente a Visualização do Composer

O Experience Composer carregará a URL que passamos no lado do servidor ao fazer a chamada à API. Ele carregará o código JavaScript e o publicará na sessão (também passada como parâmetro). Pense no Experience Composer como um usuário invisível que acessa a URL, captura a tela e publica o resultado como um novo fluxo na sessão.

Como criamos algumas funções auxiliares para saber se é o Experience Composer ou o host que está entrando, podemos impedir que o Experience Composer publique por meio do nosso código JavaScript assim que ele se conectar à sessão. Consulte a seção anterior.

Também é importante levar em conta que o Experience Composer precisa apenas se inscrever no stream do host, pois queremos que o stream publicado contenha apenas o feed de vídeo composto do host.

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

Se você observar o layout desejado na visualização do Experience Composer, precisamos adicionar o assinante no canto superior direito da página, o que corresponde ao elemento publisher elemento DOM

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

Esta é a visualização do Experience Composer, com o fluxo assinado do host no canto superior direito.

Experience Composer View Diagram

##Video de demonstração

O vídeo a seguir mostra a visualização do anfitrião e a visualização do convidado.

Gravação e transmissão

Esta aplicação não oferece a função de arquivamento/gravação. No entanto, você pode fazer isso configurando o streamMode para o modo “manual” ao iniciar o arquivamento e, em seguida, adicionar os fluxos que deseja incluir no gravação.

Nesse caso, queremos que apenas o fluxo do Experience Composer e o fluxo do convidado sejam arquivados. Caso contrário, se adicionássemos os três fluxos ou definíssemos streamMode a opção “automático”, teríamos três fluxos na gravação, sendo que dois deles seriam do apresentador.

A transmissão publicada pelo Experience Composer também pode ser transmitida via HLS ou RTMP para um público mais amplo.

Conclusão

O Experience Composer é uma ferramenta muito poderosa que permite que você ofereça uma experiência mais rica em suas videochamadas, publicando transmissões com praticamente qualquer coisa que você imaginar, desde que seja exibível em uma página da web.

Vai experimentar o novo Experience Composer? Agradecemos seus comentários na Slack da Comunidade Vonage.