Configurar um cliente web básico

Este tutorial irá guiá-lo pelas etapas de configuração de um cliente básico para um aplicativo web da Video API da Vonage.

Visão geral

Todas as aplicações que utilizam a Video API da Vonage exigem tanto um cliente e um servidor componente. O código do lado do cliente é o que é carregado no navegador do usuário final e lida com a maior parte das funcionalidades do OpenTok, incluindo conectando para o sessão, publicação áudio e vídeo correntes para a sessão, e assinando para os fluxos de outros clientes. Para obter mais informações sobre clientes, servidores e sessões, consulte Noções básicas sobre a Video API.

Neste tutorial, você utilizará OpenTok.js, a biblioteca do lado do cliente da OpenTok para a web, para criar de forma rápida e fácil um aplicativo de vídeo interativo em tempo real.

Aqui estão os tópicos que serão abordados neste tutorial:

Tempo estimado de conclusão: 20 minutos

Quer pular este tutorial? Você pode acessar diretamente o código completo do cliente web na Bate-papo por vídeo básico pasta da nossa Repositório do aplicativo de exemplo para a Web no GitHub. O repositório inclui um arquivo README com documentação sobre como executar e explorar o código.

Requisitos

Para concluir este tutorial, você precisará de:

Etapa 1: Criação das pastas do projeto e do modelo HTML

Para este projeto, você criará um arquivo HTML, um arquivo JavaScript e um arquivo CSS.

  1. Antes de começar a programar, crie uma nova pasta de projeto no seu computador para armazenar esses arquivos (o exemplo abaixo se chama meuprojeto (mas você pode dar o nome que quiser). Em seguida, adicione um /js e /css pasta, juntamente com arquivos vazios para index.html, app.js, e app.css na seguinte estrutura:

    /myproject
    /js
        app.js
    /css
        app.css
    index.html

    Depois de configurar seu projeto, abra a pasta principal do projeto no seu editor de código e vá até o index.html arquivo.

  2. Copie o código a seguir (usando o (botão “Copiar”) e adicione-o ao seu arquivo index.html no editor de código:

    <html> <head> <title> OpenTok Getting Started </title> <link href="css/app.css" rel="stylesheet" type="text/css"> <script src="https://static.opentok.com/v2/js/opentok.min.js"></script> </head> <body> <div id="videos"> <div id="subscriber"></div> <div id="publisher"></div> </div> <script type="text/javascript" src="js/app.js"></script> </body> </html>

    O código acima inclui referências ao OpenTok.js biblioteca, bem como os arquivos JS e CSS que você acabou de criar. O código também inclui editora e assinante divs, que conterão os fluxos de vídeo — usaremos essas classes para personalizar o layout mais tarde.

    Este exemplo carrega o OpenTok.js diretamente do site static.opentok.com. O OpenTok.js também está disponível como um pacote NPM. Para obter instruções sobre como usar o pacote NPM, consulte https://www.npmjs.com/package/@opentok/client.

Etapa 2: Configuração da autenticação

Preencha o formulário em branco app.js arquivo no seu editor de código — a maioria das etapas restantes envolverá adicionar código a esse arquivo.

Para se conectar a uma sessão do OpenTok, o cliente precisará ter acesso a algumas credenciais de autenticação — um Chave da API, ID da sessão, e Token. Em um aplicativo de produção, essas credenciais devem ser geradas por um servidor, mas, para agilizar o processo, vamos simplesmente definir os valores manualmente por enquanto.

  1. Comece copiando o bloco de código a seguir e adicionando-o ao seu arquivo app.js:

    // replace these values with those generated in your Video API account var apiKey = "YOUR_API_KEY"; var sessionId = "YOUR_SESSION_ID"; var token = "YOUR_TOKEN"; // (optional) add server code here initializeSession();

  2. Você precisará ajustar o código acima, definindo manualmente os valores para o apiKey, sessionId e token. Para isso, faça login na sua Account da Video API, crie um novo projeto da API do OpenTok ou use um projeto existente da API do OpenTok; em seguida, acesse a página do seu projeto e role a tela para baixo até a Ferramentas do projeto seção — a partir daí, você pode gerar manualmente um ID de sessão e um token. Use a chave de API do projeto juntamente com o ID de sessão e o token que você gerou para substituir YOUR_API_KEY, YOUR_SESSION_ID e YOUR_TOKEN no código acima (não se esqueça de deixar as aspas.)

Importante: Você pode continuar obtendo os valores do ID da sessão e do token da sua Account durante os testes e o desenvolvimento, mas, antes de entrar em produção, é necessário configurar um servidor. Consulte o guia opcional para configurar um servidor no final deste tutorial.

Para obter mais informações sobre as sessões, fichas, e servidores, confira Noções básicas sobre a Video API.

Etapa 3: Conectando-se à sessão e criando um editor

Você deve ter notado que o initializeSession() método que é chamado na última etapa, após a obtenção do ID da sessão e do token. Esse método inicializa um objeto de sessão e, em seguida, se conecta à sessão, mas ainda não o definimos em nosso código.

  1. Copie o código a seguir e cole-o abaixo do código existente no seu arquivo app.js:

    // Handling all of our errors here by alerting them function handleError(error) { if (error) { alert(error.message); } } function initializeSession() { var session = OT.initSession(apiKey, sessionId); // Subscribe to a newly created stream // Create a publisher var publisher = OT.initPublisher('publisher', { insertMode: 'append', width: '100%', height: '100%' }, handleError); // Connect to the session session.connect(token, function(error) { // If the connection is successful, publish to the session if (error) { handleError(error); } else { session.publish(publisher, handleError); } }); }

Criação de uma editora

O aplicativo inicializa um OpenTok publisher objeto com OT.initPublisher(). Esse método aceita três parâmetros opcionais:

  • O elemento DOM que o vídeo do editor substitui — neste caso, o publisher div
  • As características da editora — neste caso, a insertMode, height, e width atributos
  • O terceiro parâmetro (que não está presente em nosso código) especifica o manipulador de conclusão

Saiba mais sobre essas opções no OT.initPublisher() documentação de referência.

Inicializando e conectando-se à sessão

O OT.initSession() O método recebe dois parâmetros — a chave da API do OpenTok e o ID da sessão. Ele inicializa e retorna um OpenTok session objeto.

O connect() método do session O objeto conecta o aplicativo cliente à sessão do OpenTok. É necessário estabelecer a conexão antes de enviar ou receber fluxos de áudio e vídeo na sessão (ou antes de interagir com a sessão de qualquer forma). O connect() O método recebe dois parâmetros — um token e uma função de manipulador de conclusão function(error).

Assim que a sessão estiver conectada, publicamos nela com session.publish(publisher).

Se o cliente não conseguir se conectar à sessão do OpenTok, um objeto de erro é passado para o manipulador de conclusão do evento de conexão — nesse caso, ele exibe uma mensagem de erro no console usando console.error().

Etapa 4: Inicialização do assinante

Por fim, queremos que os clientes possam inscrever-se para assistir (ou visualizar) as transmissões uns dos outros durante a sessão.

  1. Na sua situação atual app.js no arquivo, você deve ter um comentário que diga // Subscribe to a newly created stream. Copie o código a seguir e insira-o logo abaixo desse comentário:

    session.on('streamCreated', function(event) { session.subscribe(event.stream, 'subscriber', { insertMode: 'append', width: '100%', height: '100%' }, handleError); });

Quando um novo fluxo é criado na sessão, o objeto Session dispara um streamCreated evento. Quando o cliente detecta um fluxo, queremos que ele se inscreva nesse fluxo, e fazemos isso no código acima com o session.subscribe() método. Esse método recebe quatro parâmetros:

  • O objeto Stream ao qual o cliente está se inscrevendo — event.stream
  • O elemento DOM ou o ID do elemento DOM (opcional) que o vídeo do assinante substitui — neste caso, o subscriber div
  • Um conjunto de propriedades (opcional) que personalizam a aparência da visualização do assinante — neste caso, a insertMode, height, e width atributos
  • A função de tratamento de conclusão (opcional) que é chamada quando o subscribe() o método é executado com sucesso ou falha

Saiba mais sobre essas opções no Session.subscribe() documentação de referência.

Etapa 5: Testando seu código em um navegador

Neste momento, o seu app.js O arquivo deve ficar mais ou menos assim (com alguns ajustes):

// replace these values with those generated in your Video API account var apiKey = "YOUR_API_KEY"; var sessionId = "YOUR_SESSION_ID"; var token = "YOUR_TOKEN"; // Handling all of our errors here by alerting them function handleError(error) { if (error) { alert(error.message); } } // (optional) add server code here initializeSession(); function initializeSession() { var session = OT.initSession(apiKey, sessionId); // Subscribe to a newly created stream session.on('streamCreated', function(event) { session.subscribe(event.stream, 'subscriber', { insertMode: 'append', width: '100%', height: '100%' }, handleError); }); // Create a publisher var publisher = OT.initPublisher('publisher', { insertMode: 'append', width: '100%', height: '100%' }, handleError); // Connect to the session session.connect(token, function(error) { // If the connection is successful, initialize a publisher and publish to the session if (error) { handleError(error); } else { session.publish(publisher, handleError); } }); }

No seu código finalizado, você deve ter valores fixos para substituir YOUR_API_KEY, YOUR_SESSION_ID e YOUR_TOKEN — se você ainda não fez isso, consulte Configurando a autenticação acima.

  1. Se tudo estiver correto, vá em frente e teste seu código carregando o arquivo index.html no Chrome ou no Firefox.

    Ao carregar a página, talvez seja necessário permitir que o navegador acesse sua webcam e seu microfone. Depois disso, você deverá ver uma transmissão de vídeo sua (ou do que quer que a webcam esteja captando) sendo exibida na página.

  2. Se isso funcionasse, silenciar o áudio Em seguida, abra outra aba (mantendo a original aberta) e carregue a mesma URL. Agora você deve conseguir rolar a página para baixo e ver um segundo vídeo. Se clicar com o botão direito do mouse em qualquer um dos vídeos e selecionar “Inspecionar elemento”, você verá que um dos vídeos está ocupando toda a subscriber div, e o outro está preenchendo o publisher div.

Dica para solução de problemas: Se nenhum vídeo estiver sendo exibido na página, abra a aba “console” nas ferramentas do seu navegador (command+option+i no Mac, CTRL+i no Windows) e verifique se há erros. O problema mais provável é que sua chave de API, ID de sessão ou token não esteja configurado corretamente. Como você inseriu suas credenciais diretamente no código, também é possível que seu token tenha expirado.

Passo 6: Uma pequena personalização em CSS

Neste momento, você já tem um cliente completo e funcional usando o OpenTok. Esta última etapa servirá apenas para demonstrar algumas personalizações básicas em CSS para criar um layout do tipo “imagem na imagem”.

  1. Abra o arquivo app.css vazio no seu editor de código e adicione o seguinte código a ele:

body, html { background-color: gray; height: 100%; } #videos { position: relative; width: 100%; height: 100%; margin-left: auto; margin-right: auto; } #subscriber { position: absolute; left: 0; top: 0; width: 100%; height: 100%; z-index: 10; } #publisher { position: absolute; width: 360px; height: 240px; bottom: 10px; left: 10px; z-index: 100; border: 3px solid white; border-radius: 3px; }

  1. Depois de salvar o CSS, reabra sua página inicial em duas abas separadas do navegador novamente — agora você deverá ver dois fluxos de vídeo, mas um deles será menor e estará aninhado dentro do fluxo de vídeo maior.

Ao analisar o CSS acima, dá para ver que fizemos isso ajustando a altura, a largura e a posição do #publisher div. Esse layout “imagem na imagem” é uma prática comum em bate-papos por vídeo, mas fique à vontade para ajustar o CSS e brincar com o tamanho e a posição dessas divs como quiser.

Parabéns! Você concluiu o tutorial “Configurar um cliente web básico”.
Você pode continuar experimentando e ajustando o código que desenvolveu aqui para o lado do cliente do seu aplicativo, mas lembre-se de que precisará implementar o componente de servidor da sua aplicação antes de entrar em produção (consulte Configurando seu servidor (abaixo).

Próximos passos

Quando terminar esta seção, continue desenvolvendo e aprimorando seu aplicativo OpenTok com estes recursos úteis:

Configurando seu servidor

No tutorial acima, pedimos que você codificar diretamente suas credenciais de autenticação. No entanto, para um aplicativo de produção, o sessionId e token Os valores no seu código devem ser gerados pelo servidor de aplicativos e repassados ao cliente. Aqui estão algumas razões pelas quais você não deve usar credenciais codificadas diretamente no código-fonte do seu aplicativo de produção:

  • Os tokens expiram após um determinado período (especificado no momento da geração); portanto, é necessário gerar novos tokens regularmente
  • Você não poderá criar novas sessões dinamicamente; portanto, todos os usuários do seu aplicativo ficariam restritos a uma única “sala”

Você pode continuar testando seu aplicativo com valores codificados diretamente, mas, quando estiver pronto para configurar um servidor, há várias maneiras de fazer isso:

Opção 1 do servidor — Inicie um servidor REST simples no Heroku com um clique

Essa é provavelmente a maneira mais rápida de colocar um servidor em funcionamento, mas sua funcionalidade é limitada. Basta clicar no botão do Heroku abaixo; você será redirecionado para o site do Heroku e solicitado a inserir sua chave de API e seu segredo de API do OpenTok — você pode obter esses valores na página do seu projeto em seu Account da Video API. Se você não tiver um Account no Heroku, precisará se cadastrar (é grátis).

Deploy

Quer dar uma olhada no código? O botão acima executa o código do servidor a partir do aprendendo-opentok-php Repositório do GitHub. Acesse o repositório para revisar o código e consultar a documentação adicional — você pode até mesmo criar um fork do repositório e fazer alterações antes da implantação.

Prefere o Node.js? Visite o aprendendo-opentok-node repositório com a mesma funcionalidade usando Node.js (incluindo o botão de implantação no Heroku).

Depois que o servidor estiver implantado no Heroku (seja em PHP ou Node.js), você precisará adicionar algumas linhas ao seu código do lado do cliente. No seu app.js arquivo, você deverá ver um comentário // (optional) add server code here.

Copie o código a seguir e use-o para substituir // (optional) add server code here e o initializeSession() Chame no seu arquivo app.js:

// (optional) add server code here var SERVER_BASE_URL = 'https://YOURAPPNAME.herokuapp.com'; fetch(SERVER_BASE_URL + '/session').then(function(res) { return res.json() }).then(function(res) { apiKey = res.apiKey; sessionId = res.sessionId; token = res.token; initializeSession(); }).catch(handleError);

Você precisará substituir https://YOURAPPNAME.herokuapp.com com a URL real do seu aplicativo no Heroku — você pode encontrá-la na página do seu aplicativo no site do Heroku.

O código acima usa Ajax para enviar uma solicitação ao /sessão ponto final (https://YOURAPPNAME.herokuapp.com/session), que deve retornar uma resposta HTTP que inclua o ID da sessão, o token e a chave da API no formato JSON, os quais são então atribuídos às variáveis correspondentes.

Isso /session O endpoint sempre retornará o mesmo ID de sessão, mas gerará um novo token a cada vez que for chamado — isso faz com que cada cliente receba um token exclusivo.

Opção 2 do servidor — Compilar do zero usando os SDKs do servidor

A Opção 1 utiliza endpoints REST para transmitir credenciais ao cliente, mas essa é apenas uma das muitas maneiras de implementar um servidor com o OpenTok. Se você deseja um nível maior de personalização, pode consultar o Documentação do SDK do servidor para a linguagem do lado do servidor de sua escolha (disponível para PHP, Node.js, Java, .NET, Python e Ruby). A documentação aborda o processo de configuração e os diversos métodos necessários para gerar sessões e tokens, além de outras funcionalidades do lado do servidor.

Opção 3 do servidor — Use um dos nossos aplicativos de exemplo cliente-servidor para a web

Desenvolvemos aplicativos de exemplo básicos com código cliente-servidor completo para cada linguagem do lado do servidor (PHP, Node.js, Java, .NET, Python e Ruby). Eles já incluem os clientes completos; portanto, você não precisará do código do cliente que configurou neste tutorial.

Para ver os aplicativos de exemplo no seu idioma preferido, acesse nosso Página de exemplos de código e selecione uma das linguagens do lado do servidor em Sistema cliente-servidor simples para a web.