Antes de seguir adiante com a leitura da documentação, tenha em mente que já existem diversas integrações prontas para utilizar o Elos em seu sistema. Veja as integrações já prontas no menu de Integrações de nossa Central de Ajuda.

Ao longo deste artigo, você encontra conteúdos sobre:

• Indicações de uso da integração via API e documentação essencial;
• Diferença de uso das salas via integração e via Portal Elos;
• Armazenamento de dados;
• Customizações definidas a partir de regras de negócios;
• Permissões de abertura de sala;
• Personalizações úteis via API;
• Encerramento da sessão;
• Gravações;
• Uso em iframe;
• Webhooks;
• Fluxo de atualizações;

Indicações de uso da integração via API e documentação essencial;

Este artigo é focado na integração por meio de API, a qual recomendamos em dois casos:

• quando você deseja implementar algo muito diferente para um sistema que já dispõe de integração pronta;
• quando você necessita integrar algum sistema novo, para o qual ainda não existe integração desenvolvida.

O mais comum é que a integração por API seja utilizada quando se deseja integrar o Elos a um sistema próprio, para o qual não se dispõe de integração pronta.

A API do Elos é compatível com a API do BigBlueButton (BBB), de forma que se o produto já possui integração com o BBB será possível utilizar a mesma API para integrar com o Elos. A documentação sobre a API do BBB está disponível em https://docs.bigbluebutton.org/dev/api.html. Ainda suportamos a API estendida de webhooks, que permite à integração receber eventos relevantes das sessões em andamento ou gravações: https://docs.bigbluebutton.org/dev/webhooks.html.

O acesso à API normalmente é feito via bibliotecas que já existem e são mantidas pela comunidade. Usando bibliotecas, você não precisará implementar a integração de baixo nível com a API, você pode simplesmente utilizar os métodos fornecidos pela biblioteca para criar sua integração. Caso a biblioteca não ofereça acesso a um método ou parâmetro desejável para a sua integração, você pode modificar a biblioteca para este fim. O uso de uma biblioteca fará com que você não se preocupe com assinatura de requisições, ordem de parâmetros, entre outros.

Entre as bibliotecas mais conhecidas e utilizadas para acessar a API estão:
Biblioteca para PHP: https://github.com/bigbluebutton/bigbluebutton-api-php
Biblioteca para Javascript: https://github.com/mconf/bigbluebutton-api-js
Biblioteca para Ruby: https://github.com/mconf/bigbluebutton-api-ruby
Biblioteca para Rails: https://github.com/mconf/bigbluebutton_rails

Diferença entre salas via Portal Elos e via integração

Ao configurar uma integração do Elos com seu sistema, tenha em mente que essa integração conecta seu sistema diretamente a uma sala de videoconferência, e que esse fluxo de comunicação não passa pelo nosso portal. Na prática, isso significa que a integração por API não precisa seguir nenhuma das regras do nosso portal, ou seja, o modo com o qual cada sala é configurada e aberta pode ser totalmente adaptado para as regras de negócio do seu sistema. Pelos mesmos motivos, as informações sobre usuários, salas e gravações geradas via integração não estarão disponíveis no nosso portal.

Se você precisar utilizar uma sala instanciada diretamente pelo nosso portal, atente para o fato de que as regras de negócio (permissões de acesso e configuração da sala) obedecidas serão as do Portal Elos, e não as do seu sistema, mesmo que você esteja logado com uma conta da mesma instituição para a qual configurou a integração.

Armazenamento de dados

Para implementar a integração é necessário o apontamento para um banco de dados (ou qualquer outro mecanismo para armazenamento de dados que você quiser usar) seu, pois é nele que estarão as informações de identificação dos usuários, das salas e das gravações.

Esse banco deverá ser modelado de acordo com as regras de negócio e produto do seu sistema. Um exemplo de como esta lógica pode ser montada é: cada usuário com papel de professor vai ter uma sala, então, cada sala terá um identificador único (ID) ligado ao usuário que é o "dono" da sala. Cabe enfatizar que essa sala não precisa ser cadastrada em nosso portal, visto que ela é criada em nossa infraestrutura via API quando o usuário clica para "abrir". Essa mesma sala fecha quando, por exemplo, o dono da sala clica para "encerrar sessão" (comando repassado para a API). No nosso produto (salas abertas via Portal Elos), o botão de encerrar sessão (ou fechar sala) encontra-se tanto dentro da sala quanto fora dela (visível para o dono), embora o lugar onde o botão de encerrar a sessão aparece também seja uma definição a ser feita por você.

Em resumo, é no seu banco de dados que informações sobre quem pode abrir uma sala, quais configurações serão aplicadas nela, como será a gerência dos participantes, entre outros estarão armazenadas.

Customizações definidas a partir de regras de negócio

No que diz respeito a possibilidades de customização quando integrando o Elos por API: as possibilidades são muitas. Embora este seja um ponto positivo, exige que haja uma boa modelagem de produto e de negócio antes da implementação da parte técnica. Isso significa que antes de colocar a mão na massa, é necessário que seja definido como você quer que seja o sistema de videoconferência do seu produto e como você quer que ele seja acessado. Alguns exemplos de definições são:

• Como será a gerência de salas (Cada usuário tem sua sala? Usuários criam múltiplas salas? etc);
• Quem pode iniciar uma sessão na sala;
• Quem é moderador e quem é apenas participante;
• Quem pode acessar a sala e se precisa aprovação de moderadores para isso;
• Se a reunião poderá ser gravada;
• Personalizar a apresentação inicial;
• Configurar restrições dos participantes (limitar acesso a algumas funcionalidades);
• Habilitar e desabilitar funcionalidades automaticamente (iniciar vídeo automaticamente, esconder lista de usuários, etc).

Estes são apenas alguns pontos. Em breve disponibilizaremos a documentação detalhada completa acerca dessas definições.

Além da lógica por trás das salas, a API ainda oferece opções para monitoramento e listagem de recursos. Por exemplo, é possível buscar informações como o número de salas abertas no momento (além de efetuar operações sobre elas, como encerrá-las), como também apresentar uma listagem de todas as gravações feitas. Tudo isso pode ser feito por meio de diretivas que já existem na API.

Permissões e abertura da sala

Do ponto de vista técnico, a sala existe na nossa infraestrutura do momento em que ela é instanciada pelo comando create da API até o momento em que ela é fechada, podendo ser fechada de diversas formas, detalhadas mais adiante neste mesmo artigo. Depois que a sala é encerrada ela não existe mais no Elos. A referência da sala vai existir na sua base de dados, assim como "quem são os usuários" também vai existir na sua base de dados. É muito importante criar um identificador de sala (meetingID) que seja único, pois é através dele que você fará referências à esta sala e a todos recursos relacionados à ela, como a sua gravação. Recomendamos que seja utilizado um GUID (https://pt.wikipedia.org/wiki/Identificador_%C3%BAnico_universal) para identificação única da sala.

Convém atentar: o create pode ser repetido sempre que for necessário, por isso uma boa prática de uso da API é usar a regra: se o usuário tem permissão de abrir a sala, que seja dado primeiro o create e depois o join (a chamada que autoriza e direciona o usuário para a sessão) do usuário para a sala, dessa forma garante-se que a sessão esteja aberta quando o sistema receber o join e isso minimiza as chances de erro no processo. Já quando o usuário não tem permissão de abrir a sala, deve ser feita a verificação de sala aberta e somente dar o join se a sala já estiver aberta (no papel de participante). Caso o create seja dado novamente quando a sala já estiver rodando, não vai retornar erro, vai apenas indicar que a sala já estava aberta.

Além do ID da sala, há outras duas informações que são passadas junto do comando create e que são muito importantes no uso da API:

• senha de moderador;
• senha de participantes.

Estes valores servem para identificar os usuários que vão conectar na sala e atribuir as devidas permissões. Através dessa senha, verifica-se se o usuário será participante ou moderador. Então, as senhas sempre devem ser diferentes (caso contrário todo mundo seria moderador!). Uma boa prática é não deixar o usuário final escolher essa senha, ou seja, mesmo que a sua sala seja protegida com senha, é melhor separar esta senha da senha usada na API. Veja um exemplo: em nosso portal, a sala pode ser privada, e se for privada o usuário define uma senha para ela. Essa senha é utilizada apenas pelo portal para decidir se o participante pode entrar na sala ou não. Depois de decidir isso, o portal decide qual o papel da pessoa nessa sala e então usa senhas internas (que só ele conhece e que são aleatórias), para indicar para a API qual o papel a pessoa deve assumir.

É importante que:

• ID da sala seja uma palavra grande e aletatória, idealmente um GUID;
• Senha de participante seja uma hash;
• Senha de moderador seja uma hash diferente da senha de participante;
• O usuário final não tenha visibilidade dessas senhas.

Outra informação importante em relação à API é que quando a sessão for criada podem ser passados metadados para esta sessão, que são dados da reunião ou aula que você deseja que estejam disponíveis posteriormente, também na gravação. Por exemplo: em uma integração que é usada por usuários com o papel “funcionários”, toda vez que determinada sala é aberta são passados os metadados de que a sessão é administrativa e então, posteriormente, esse metadado estará vinculado à gravação. Com isso, pode-se gerar analytics para saber, por exemplo, os setores que mais estão gravando e também gerenciar as gravações por setor. Não há limite de metadados, e sugerimos que sempre sejam passados, no mínimo, o endereço do site e a versão da integração, podendo estender-se a todas as informações que possam ser úteis para que essa sessão e/ou gravação possam ser indexadas posteriormente.

Personalizações úteis via API

Parâmetros interessantes para serem utilizados no create:

• autoStartRecording: inicia a gravação automaticamente quando a sessão é aberta. Valor padrão: false
• allowStartStopRecording: determina se o moderador pode alterar o status de gravação. Valor padrão: true
• meta_enable-breakout-rooms: determina se a funcionalidade de salas de apoio estará disponível para os usuários. Valor padrão: true
• meta_enable-closed-captions: determina se a funcionalidade de legendas estará disponível para os usuários. Valor padrão: false
• meta_enable-external-video: determina se a funcionalidade de compartilhamento de vídeo externo estará disponível para os usuários. Valor padrão: true
• meta_enable-interactions-button: determina se a funcionalidade de botões de levantar a mão e interações estará disponível para os usuários. Valor padrão: true
• meta_enable-multiple-notes: determina se a funcionalidade de múltiplas notas compartilhadas estará disponível para os usuários. Valor padrão: false
• meta_enable-poll: determina se a funcionalidade de enquete estará disponível para os usuários. Valor padrão: true
• meta_enable-private-chat: determina se a funcionalidade de bate-papo privado estará disponível para os usuários. Valor padrão: true
• meta_enable-private-room: determina se a funcionalidade de sala privada estará disponível para os usuários. Valor padrão: false
• meta_enable-public-chat: determina se a funcionalidade de bate-papo público estará disponível para os usuários. Valor padrão: true
• meta_enable-questions: determina se a funcionalidade de perguntas estará disponível para os usuários. Valor padrão: false
• meta_enable-shared-notes: determina se a funcionalidade de notas compartilhadas estará disponível para os usuários. Valor padrão: true
• meta_enable-streaming: determina se a funcionalidade de transmissão (streaming) estará disponível para os usuários. Valor padrão: true
• meta_enable-timer: determina se a funcionalidade de cronômetro/temporizador estará disponível para os usuários. Valor padrão: true
• meta_enable-transfer: determina se a funcionalidade de salas grandes com transmissão estará disponível para os usuários. Valor padrão: false
• meta_enable-user-reaction: determina se a funcionalidade de reações estará disponível para os usuários. Valor padrão: true
• meta_enable-viewer-questions: determina se a funcionalidade de perguntas estará disponível para os convidados. Valor padrão: false

Parâmetros interessantes para serem utilizados no join:

• userdata-bbb_auto_share_webcam: abre automaticamente o preview de câmera após o usuário configurar o áudio. Valor padrão: false
• userdata-bbb_hide_presentation: esconde a apresentação ao entrar. Valor padrão: false
• userdata-bbb_auto_join_audio: ativa o áudio ao entrar na sala. Valor padrão: true
• userdata-bbb_listen_only_mode: ativa o modo ouvinte como opção para ativar o áudio. Valor padrão: true
• userdata-bbb_skip_check_audio: retira o teste de áudio. Valor padrão: false
• userdata-bbb_override_default_locale: define o idioma da sala virtual. Por padrão, a sala virtual utiliza o idioma do navegador. Valores possíveis são pt-br e en-us

Sobre o encerramento da sessão

Existem quatro hipóteses para uma sessão ser encerrada:

• Quando um moderador seleciona a opção "Encerrar a sessão" dentro da sala. Qualquer moderador possui esta opção, e após confirmação, todos os usuários são desconectados, e a sala é fechada. Por conta disso, é importante ponderar sobre quem na sessão deve entrar como moderador, e quem deve entrar como participante. Não é uma boa prática que todos os participantes conectem como moderador, pois aumenta a chance de, por acidente, alguém encerrar a sessão.
• Quando todos os participantes desconectarem. Após todos sairem, a sala ainda permanece ativa por 5 minutos e depois é encerrada automaticamente.
• Por API através do método end. Não há confirmação para este método, ou seja, quando ele é chamado para uma sala rodando, essa sessão é encerrada imediatamente. Esta opção normalmente aparece nas integrações em algum local de gerência da sala, em que o usuário dono da sala consegue enxergar o status da sala rodando e tem a opção de encerrá-la clicando na interface da integração.
• Por inatividade. Caso uma sessão permaneça por uma hora sem nenhuma atividade, ela é encerrada automaticamente. É considerado atividade todas as ações de entrada e saída de usuários, ativação de microfone e câmera, início e fim de fala de um participante, anotações no quadro branco, entre outros. Esta condição existe para evitar o cenário de uma sessão rodando por tempo indeterminado por engano. Veja mais em: https://ajuda.elos.vc/kb/article/152226/fechamento-de-sala-por-inatividade.

Sobre API e gravações

No que diz respeito a gravações de sessões, a API pode gerenciar, por exemplo, que a gravação seja despublicada (não mais poderá ser assistida), que seja apagada e que tenha metadados acrescentados posteriormente. Em nosso portal, por exemplo, utilizamos a atualização de metadados quando o usuário configura um título para a sessão e quando coloca descrição no agendamento - isso aciona o updateRecordings, que então atualiza o metadado dentro da gravação.

Sobre API e Elos em iframe

Uma motivação para a escolha da integração por API também pode ser a possibilidade dar mais visibilidade à sua marca. Isso ocorre ao incorporar a sala através de um iframe dentro do próprio sistema integrado. Com isso você consegue manter a sua URL e, possivelmente, alguns componentes da sua identidade visual mesmo quando as pessoas estiverem dentro de uma conferência no Elos. Cabe sinalizar que atualmente existem algumas limitações para este modo, embora não comprometam a integridade do serviço.

Para tanto, é necessário passar algumas diretivas para o iframe conseguir capturar câmera e microfone. Um ponto importante é que no source do iframe não se coloque de fato a URL da API para entrar na sala. O ideal é utilizar uma URL interna do sistema, que tenha o papel de validar o usuário, identificar se o mesmo pode estar ali ou não, qual a sala que está tentando acessar, se tem ou não permissão de acesso, se vai acessar como convidado ou moderador, etc. No source sempre é definido qual é essa URL interna.

Para utilizar o iframe usamos o seguinte comando:

<iframe
allow="microphone *; camera *; display-capture *; clipboard-read *; clipboard-write *; screen-wake-lock *;"
allowfullscreen=""
data-hj-allow-iframe=""
mozallowfullscreen=""
msallowfullscreen=""
oallowfullscreen=""
src="/conference/rooms/sheila-uberti/join?user%5Bemail%5D=&amp;user%5Bkey%5D=&amp;user%5Bname%5D=Felipe+Cecagno"
webkitallowfullscreen="">
</iframe>

Webhooks

É possível, através da API de webhooks, registrar um endpoint para receber eventos relevantes sobre sessões e gravações. Esse registro pode ser feito com granularidade de sessão (passando o meetingID na requisição hooks/create) ou global, para todas as sessões, conforme documentado em https://docs.bigbluebutton.org/dev/webhooks.html#hookscreate

Entretanto, diferente da implementação original do BigBlueButton, nós modificamos o modelo de validação da integridade dos eventos emitidos, da seguinte forma:

• Ao registrar um webhook através do método hooks/create, é retornado um campo authToken na resposta em XML;
• O authToken deve ser salvo no banco para ser usado mais tarde na validação dos eventos recebidos;
• Quando o evento é recebido, nos headers HTTP virá um bearer com o valor do authToken - caso o valor não seja o mesmo, o evento deve ser rejeitado.

Para que sua implementação seja compatível com Elos e BigBlueButton, basta considerar na implementação que, caso o authToken não seja retornado ao registrar um hook, pode-se considerar que o authToken é igual ao shared secret do serviço.

Os eventos emitidos pelo Elos são:

• meeting-created
• meeting-ended
• user-joined
• user-left
• rap-archive-ended
• rap-sanity-started
• rap-sanity-ended
• rap-process-started
• rap-process-ended
• rap-publish-started
• rap-publish-ended
• rap-published
• rap-unpublished
• rap-deleted

Para saber mais sobre as fases no processamento de gravações, acesse https://docs.bigbluebutton.org/dev/recording.html.

Gravações

As gravações são disponibilizadas em dois formatos:

• presentation: utilizado para visualização no navegador, permite a navegação rápida clicando sobre as miniaturas dos slides e mensagens de bate-papo, acesso às notas compartilhadas e busca;
• presentation_video: é um arquivo MP4, para que o usuário baixe e armazene o vídeo para o seu computador.

No formato presentation, é possível personalizar a visualização através de parâmetros na URL:

• l=media: configura o layout da gravação para que apenas o vídeo fique visível na tela.

Sobre novidades e melhorias

Estamos constantemente trabalhando para aprimorar nossa solução, oferecendo aos clientes e usuários a melhor experiência possível em videoconferência. Novidades e melhorias são continuamente lançadas, e você pode acompanhar as atualizações aqui.

Sugestões são muito bem-vindas, a qualquer momento. Sinta-se à vontade para contatar-nos sempre que quiser compartilhar conosco um feedback ou sugestão ou mesmo para pedir ajuda.